MPI_FILE_READ(3)

💖 MPI_FILE_READ(3) — the Open MPI glow-up edition 💖

okay bestie, welcome to MPI_FILE_READ, one of the Open MPI gworls 💅 it lives in section 3 of the manual (yes that's the library-calls section, iykyk), and today we're reading a file starting at wherever the individual file pointer is currently parked. Blocking, noncollective, no drama, just vibes ✨

---

✨ SYNTAX ✨

🎀 C Syntax

#include <mpi.h>

int MPI_File_read(MPI_File fh, void *buf,
     int count, MPI_Datatype datatype, MPI_Status *status)

🎀 Fortran Syntax

USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_FILE_READ(FH, BUF, COUNT,
     DATATYPE, STATUS, IERROR)
     <type>  BUF(*)
     INTEGER FH, COUNT, DATATYPE, STATUS(MPI_STATUS_SIZE),IERROR

🎀 Fortran 2008 Syntax

USE mpi_f08
MPI_File_read(fh, buf, count, datatype, status, ierror)
     TYPE(MPI_File), INTENT(IN) :: fh
     TYPE(*), DIMENSION(..) :: buf
     INTEGER, INTENT(IN) :: count
     TYPE(MPI_Datatype), INTENT(IN) :: datatype
     TYPE(MPI_Status) :: status
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror

---

🌸 INPUT PARAMETERS 🌸

• fh — the file handle, that little handle-shaped bestie (handle).
• count — how many elements are chilling in your buffer (integer).
• datatype — what type each buffer element is (handle).

---

🦋 OUTPUT PARAMETERS 🦋

• buf — initial address of the buffer (integer).
• status — the status object (status).
• ierror — Fortran only, the error status (integer).

---

👑 DESCRIPTION 👑

So MPI_File_read attempts to read from the file tied to fh — specifically at the current individual file pointer position, the one the system is keeping track of for you — a total of count data items of datatype type, and it drops them right into your buffer buf. 🫶

The data gets pulled out of those parts of the file that the current view specifies. And then MPI_File_read stores the number of data-type elements it actually read into status. Every other field of status? undefined, bestie. Do not go looking at them. 🙈

⚠️ It is erroneous to call this function if MPI_MODE_SEQUENTIAL mode was specified when the file was opened. Like, don't even try it. That's a whole no-no. 💀

---

😭 ERRORS 😭

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 that last argument. That's just how they do it. ✨

Before the error value is even 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 — so like, before MPI_Init <#mpi-init> / MPI_Init_thread <#mpi-init-thread>, after MPI_Finalize <#mpi-finalize>, or when you're using the Sessions Model exclusively — the error raises the initial error handler. That initial error handler can be changed by calling MPI_Comm_set_errhandler <#mpi-comm-set-errhandler> on MPI_COMM_SELF when you're using the World model, or via the mpi_initial_errhandler CLI argument to mpiexec, or via the info key to MPI_Comm_spawn <#mpi-comm-spawn> / MPI_Comm_spawn_multiple <#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. periodt.

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

• MPI_ERRORS_ARE_FATAL — Causes the program to abort all connected MPI processes. just straight up ending it 💀
• 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 <#mpi-abort> was called on that communicator. If it's called on a window or file, it acts as if MPI_Abort <#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 back to the application. the chill one 🍓

MPI applications can also implement their own error handlers by calling:

• MPI_Comm_create_errhandler <#mpi-comm-create-errhandler> and then MPI_Comm_set_errhandler <#mpi-comm-set-errhandler>
• MPI_File_create_errhandler <#mpi-file-create-errhandler> and then MPI_File_set_errhandler <#mpi-file-set-errhandler>
• MPI_Session_create_errhandler <#mpi-session-create-errhandler> and then MPI_Session_set_errhandler <#mpi-session-set-errhandler>, or at MPI_Session_init <#mpi-session-init>
• MPI_Win_create_errhandler <#mpi-win-create-errhandler> and then MPI_Win_set_errhandler <#mpi-win-set-errhandler>

💀 Note that MPI does not guarantee that an MPI program can continue past an error. like, at all. fr fr.

See the MPI man page <#open-mpi> for a full list of MPI error codes <#open-mpi-errors> — go get your full reading list, bestie 📚

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

---

💜 Copyright 💜

2003-2026, The Open MPI Community

---

and that's the whole page, bestie 🌈💖 you ate. this was MPI_FILE_READ(3) from Open MPI, dated Sep 10, 2026 — go forth and read those files, main character energy only 👑✨