MPI_File_read_at(3)

✨ MPI_File_read_at — bestie, we're reading at an EXPLICIT offset ✨

okay so this one lives in the MPI manual (yes, that MPI, the message-passing icon), and it's about grabbing data out of a file at a spot you pick. no hidden file pointer drama. we love a decisive queen. 💅

---

🌸 NAME 🌸

MPI_File_read_at — Read using explicit offset. that's the whole vibe. you say where, it reads from there. periodt.

---

🦋 SYNOPSIS 🦋

int MPI_File_read_at(MPI_File fh, MPI_Offset offset, void *buf, int count,
MPI_Datatype datatype, MPI_Status *status)

int MPI_File_read_at_c(MPI_File fh, MPI_Offset offset, void *buf,
MPI_Count count, MPI_Datatype datatype,
MPI_Status *status)

two versions bestie!! the classic one with a plain int count, and the _c glow-up where count is an MPI_Count instead. slay. 💖

---

🎀 INPUT PARAMETERS 🎀

• fh — the file handle (a handle, so it's giving "you already opened this, right?" energy).
• offset — the file offset (an integer). this is your call, no auto-advancing, no surprises. iconic.
• count — how many elements are in the buffer (an integer).
• datatype — the datatype of each buffer element (a handle).

---

💖 OUTPUT PARAMETERS 💖

• buf — initial address of buffer (choice). yes bestie it's under output here, don't @ me, that's what the page says. 🫶
• status — the status object (Status).

---

🔥 THREAD AND INTERRUPT SAFETY 🔥

good news first: this routine is thread-safe. that means multiple threads can use it at the same time, no cap, and you do not need to bring your own user-provided thread locks. she handles herself. 👑

but — and this is the part where I grab your hand — it is not interrupt safe. the reason is typically that it uses memory allocation routines like malloc, or other non-MPICH runtime routines that are themselves not interrupt-safe. so like. threads: yes. interrupts: absolutely not. 💀

---

🌈 NOTES FOR FORTRAN 🌈

• Every MPI routine in Fortran (except for MPI_WTIME and MPI_WTICK) gets an extra argument called ierr tacked onto the end of the argument list. ierr is an integer and it means exactly the same thing as the return value of the routine in C.
• In Fortran, MPI routines are subroutines and they get invoked with the call statement. very retro, very chic.
• All MPI objects (e.g., MPI_Datatype, MPI_Comm) are of type INTEGER in Fortran.

---

😭 ERRORS 😭

so all MPI routines (except MPI_Wtime and MPI_Wtick) return an error value — C routines hand it back as the value of the function, Fortran routines put it in that last argument. and before that value comes back to you, the current MPI error handler gets called. by default, that error handler aborts the MPI job. like, full stop, everybody out. 🙈

you can swap the error handler with:

• MPI_Comm_set_errhandler — for communicators
• MPI_File_set_errhandler — for files
• MPI_Win_set_errhandler — for RMA windows

the MPI-1 routine MPI_Errhandler_set may also be used, but its use is deprecated — so like, it's giving "we don't do that anymore bestie."

if you want error values returned instead of the job getting nuked, use the predefined error handler MPI_ERRORS_RETURN. ✨

heads up: MPI does not guarantee that an MPI program can continue past an error. however, MPI implementations will attempt to continue whenever possible. so it might be fine. it might not. vibe check accordingly.

now the error codes themselves:

• MPI_SUCCESS — no error; the MPI routine completed successfully. we love a clean run. 🎉
• MPI_ERR_ARG — invalid argument. some argument is invalid and it isn't identified by a specific error class (e.g., MPI_ERR_RANK).
• MPI_ERR_BUFFER — invalid buffer pointer. usually a null buffer where one is not valid.
• MPI_ERR_COUNT — invalid count argument. count arguments must be non-negative; a count of zero is often valid.
• MPI_ERR_TYPE — invalid datatype argument. additionally, this error can occur if an uncommitted MPI_Datatype (see MPI_Type_commit) is used in a communication call.
• MPI_ERR_OTHER — other error; use MPI_Error_string to get more information about this error code.

---

that's the whole page bestie, every flag, every error, every Fortran footnote, nothing skipped, no crumbs left behind 💜

sign-off time: this little masterpiece is dated 4/10/2026, it belongs to the MPI collection, and you'd find it filed under MPI_File_read_at(3) — so go read at an explicit offset, stay thread-safe, and do NOT get interrupted. mwah. 🎀🦋✨