MPI_FILE_IREAD_AT(3)

💅 MPI_FILE_IREAD_AT — Open MPI

Okay bestie, gather round, because this one's a nonblocking read and it's lowkey iconic. MPI_File_iread_at — reads a file at an explicitly specified offset (nonblocking, noncollective). Yes, that's the whole vibe of the page. This is the Open MPI version, from the Open MPI manual, and we're getting into it. 🦋

---

✨ SYNTAX ✨

🎀 C Syntax

#include <mpi.h>

int MPI_File_iread_at(MPI_File fh, MPI_Offset offset,
     void *buf, int count, MPI_Datatype datatype,
     MPI_Request *request)

🎀 Fortran Syntax

USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_FILE_IREAD_AT(FH, OFFSET, BUF, COUNT, DATATYPE, REQUEST, IERROR)
     <type>  BUF(*)
     INTEGER FH, COUNT, DATATYPE, REQUEST, IERROR
     INTEGER(KIND=MPI_OFFSET_KIND)   OFFSET

🎀 Fortran 2008 Syntax

USE mpi_f08
MPI_File_iread_at(fh, offset, buf, count, datatype, request, ierror)
     TYPE(MPI_File), INTENT(IN) :: fh
     INTEGER(KIND=MPI_OFFSET_KIND), INTENT(IN) :: offset
     TYPE(*), DIMENSION(..), ASYNCHRONOUS :: buf
     INTEGER, INTENT(IN) :: count
     TYPE(MPI_Datatype), INTENT(IN) :: datatype
     TYPE(MPI_Request), INTENT(OUT) :: request
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror

---

🌸 INPUT PARAMETERS 🌸

• fh — the file handle, bestie. It's a handle.
• offset — where in the file we're reading from. It's an integer.
• count — how many elements are in the buffer. Integer, periodt.
• datatype — the data type of each element in the buffer. Handle.

---

💖 OUTPUT PARAMETERS 💖

• buf — the initial address of the buffer. It's a choice.
• request — the request object you get back. Handle.
• ierror — Fortran only, gorl: the error status. Integer.

---

🧚 DESCRIPTION 🧚

So MPI_File_iread_at is literally the nonblocking version of MPI_File_read_at. That's the whole relationship. 💫

It's a nonblocking routine that attempts to read from the file associated with fh, at the offset position, a total number of count data items having datatype type — into your buffer buf. 🫶

The offset is measured in etype units relative to the current view. Translation: holes are not counted when locating an offset. So don't come for her about gaps in the file, she's not counting them. 🙈

The data is taken out of those parts of the file specified by the current view. Then MPI_File_iread_at stores the number of datatype elements actually read in status. Every other field of status is undefined — so do not go poking around in there expecting lore, it's giving "nothing to see here". 💀

---

👑 ERRORS 👑

Almost all MPI routines return an error value, bestie. In C routines it's the return result of the function, and in Fortran routines it's in the last argument. ✨

Before that error value comes back, the current MPI error handler associated with the communication object (like a communicator, window, or file) is called. And if no communication object is 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 isn't initialized (i.e., 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. You can change that initial error handler by calling MPI_Comm_set_errhandler on MPI_COMM_SELF when using the World model, or with 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 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 three predefined error handlers you can use, and they are:

• MPI_ERRORS_ARE_FATAL — causes the program to abort all connected MPI processes. Not a drill. 😭
• 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. If it's called on a session, it aborts only the local process. Very "this is between me and my process" energy. 💅
• MPI_ERRORS_RETURN — returns an error code to the application. Chill of it. 🍓

MPI applications can also implement 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

⚠️ Heads up: note that MPI does not guarantee that an MPI program can continue past an error. So like, don't just assume you can walk it off. 🙏

See the MPI man page for a full list of MPI error codes. And see the Error Handling section of the MPI-3.1 standard for more information. 📚

---

🌈 COPYRIGHT 🌈

2003-2026, The Open MPI Community — that's the whole copyright situation, no cap. 🫡

---

And that's the page, bestie! ✨💖✨ This icon of a man page dropped on Sep 11, 2026, in the Open MPI edition, filed under MPI_FILE_IREAD_AT(3) — go forth and read nonblockingly, you absolute main character. 👑🦋💜