MPI_FILE_SET_ERRHANDLER(3)

💖 MPI_FILE_SET_ERRHANDLER(3) 💖

okay bestie, welcome to Open MPI's little corner of the manual — this one's all about MPI_File_set_errhandler, aka the glow-up machine that gives your file a brand new error handler. it's giving "new outfit, who dis" but for error handling. slay. 🎀

---

✨ NAME ✨

MPI_File_set_errhandler — sets the error handler for a file. literally that's it, that's the whole job. 💅

---

✨ SYNTAX ✨

🌸 C Syntax

#include <mpi.h>

int MPI_File_set_errhandler(MPI_File file, MPI_Errhandler
     errhandler)

🌸 Fortran Syntax

USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_FILE_SET_ERRHANDLER(FILE, ERRHANDLER, IERROR)
     INTEGER FILE, ERRHANDLER, IERROR

🌸 Fortran 2008 Syntax

USE mpi_f08
MPI_File_set_errhandler(file, errhandler, ierror)
     TYPE(MPI_File), INTENT(IN) :: file
     TYPE(MPI_Errhandler), INTENT(IN) :: errhandler
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror

---

✨ INPUT/OUTPUT PARAMETER ✨

• file — the File handle. 🗂️ (yes it's listed as input/output, it said what it said)

---

✨ INPUT PARAMETER ✨

• errhandler — the new error handler for the file (handle). 🫶

---

✨ OUTPUT PARAMETER ✨

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

---

✨ DESCRIPTION ✨

so basically: this attaches a new error handler to a file. no cap. 🦋

the error handler you pass in has to be either:

• one of the predefined error handlers, or
• an error handler that was created by calling MPI_File_create_errhandler.

that's the vibe check. 👑

---

✨ ERRORS ✨

kay so, almost all MPI routines return an error value — C routines hand it back as the return result of the function, and Fortran routines put it in the last argument. classic. 💀

before that error value gets returned, the current MPI error handler associated with the communication object (think: communicator, window, file) gets called. and if there's no communication object associated with the MPI call? then the call is considered attached to MPI_COMM_SELF and it'll call the associated MPI error handler. 😭

when MPI_COMM_SELF is not initialized (aka 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. and that initial error handler can be changed by:

• calling MPI_Comm_set_errhandler on MPI_COMM_SELF when using the World model, or
• the mpi_initial_errhandler CLI argument to mpiexec, or
• the info key to MPI_Comm_spawn / MPI_Comm_spawn_multiple.

and if no other appropriate error handler has been set? then MPI_ERRORS_RETURN gets called for MPI I/O functions, and MPI_ERRORS_ABORT gets called for all other MPI functions. noted. 📝

Open MPI ships three predefined error handlers you can use, and they are:

• MPI_ERRORS_ARE_FATAL — causes the program to abort all connected MPI processes. dramatic much? yes. iconic. 🩸
• MPI_ERRORS_ABORT — an error handler that can be invoked on a communicator, window, file, or session. when called on a communicator, it acts as if MPI_Abort was called on that communicator. if 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. if called on a session, it aborts only the local process. 🙈
• MPI_ERRORS_RETURN — returns an error code to the application. the chill one. 😌

MPI applications can also implement their own error handlers, by calling (in these exact little combos):

• 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

⚠️ real talk: note that MPI does not guarantee that an MPI program can continue past an error. so like… don't build your whole personality on surviving one. 😳

see the MPI man page for a full list of MPI error codes. 📚

also see the Error Handling section of the MPI-3.1 standard for more information. 🧚

---

👑 Copyright 👑

2003-2026, The Open MPI Community

---

okay and that's the whole page, bestie — love that for us. this one's from Open MPI, dated Sep 10, 2026, and it's MPI_FILE_SET_ERRHANDLER(3). go set some errhandlers, you main character. 💖✨🎀🦋🌸