MPI_FILE_GET_INFO(3)

📦
version 5.0.10 · 7 versions
, in ubuntu stonking

💖 NAME 💖

ok so this is MPI_File_get_info — from the Open MPI manual, section 3 (that's the library-calls girlies, iykyk). It hands you back a brand new info object stuffed with all the values for the hints that are currently chillin' with a file. fr fr, that's the whole plot.

✨ SYNTAX ✨

🫶 C Syntax

#include <mpi.h>

int MPI_File_get_info(MPI_File fh, MPI_Info *info_used)

🌸 Fortran Syntax

USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_FILE_GET_INFO(FH, INFO_USED, IERROR)
     INTEGER FH, INFO_USED, IERROR

🦋 Fortran 2008 Syntax

USE mpi_f08
MPI_File_get_info(fh, info_used, ierror)
     TYPE(MPI_File), INTENT(IN) :: fh
     TYPE(MPI_Info), INTENT(OUT) :: info_used
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror

🌈 INPUT PARAMETER 🌈

  • fh — the file handle (a handle, bestie, that's the whole personality).

🎀 OUTPUT PARAMETERS 🎀

  • info_used — a whole new info object, freshly made (handle).
  • ierror — Fortran only: error status, and it's an integer.

💅 DESCRIPTION 💅

MPI_File_get_info returns a new info object containing all the hints that the system currently associates with the file fh. Like, the current setting of every hint the system is actually using in relation to this open file — that's what lands in info_used. And here's the thing: you are the one responsible for freeing info_used, via MPI_Info_free. Don't forget. She's your responsibility now. 😭

Also lowkey important: the set of hints you get back in info_used may be greater or smaller than the set you passed in to MPI_File_open, MPI_File_set_view, and MPI_File_set_info — because the system might not recognize some hints you set, and it might just automatically set other hints you never even asked for. Main character system behavior, honestly. If you wanna know which hints can be set, go look at the HINTS section below. 👇

🔥 HINTS 🔥

These are the hints that can be used as values for the info_used argument. Slay.

⭐ SETTABLE HINTS ⭐

  • shared_file_timeout — how much time, in seconds, to wait for access to the shared file pointer before it gives up and exits with MPI_ERR_TIMEDOUT.
  • rwlock_timeout — how much time, in seconds, to wait while trying to get a read or write lock on a contiguous chunk of a UNIX file before exiting with MPI_ERR_TIMEDOUT.
  • noncoll_read_bufsize — the maximum size of the buffer that MPI I/O uses to satisfy read requests in the noncollective data-access routines.
Note, and this one matters: if the buffer size is smaller than the distance (in bytes) in a UNIX file between the first byte and the last byte of the access request, MPI I/O ends up iterating and doing multiple UNIX read() or write() calls. And if the request includes multiple noncontiguous chunks of data and the buffer size is greater than the size of those chunks, then the UNIX read() or write() — the one made at the MPI I/O level — will access data that this process did not request, just to reduce the total number of write() calls being made. If that is not the behavior you want, then reduce this buffer size so it equals the size of the contiguous chunks within the aggregate request. No cap.
  • noncoll_write_bufsize — the maximum size of the buffer MPI I/O uses to satisfy write requests in the noncollective data-access routines.

See the note above in noncoll_read_bufsize. Same energy, just write-y.

  • coll_read_bufsize — the maximum size of the buffer MPI I/O uses to satisfy read requests in the collective data-access routines.

See the note above in noncoll_read_bufsize. 👀

  • coll_write_bufsize — the maximum size of the buffer MPI I/O uses to satisfy write requests in the collective data-access routines.

See the note above in noncoll_read_bufsize. You get it.

  • mpiio_concurrency — (boolean) controls whether nonblocking I/O routines can bind an extra thread to an LWP.
  • mpiio_coll_contiguous — (boolean) controls whether subsequent collective data accesses will request collectively contiguous regions of the file.

💜 NON-SETTABLE HINTS 💜

  • filename — access this hint to get the name of the file.

💀 ERRORS 💀

Almost all MPI routines return an error value, bestie — C routines give it back as the return result of the function, and Fortran routines stick it in the last argument.

Before that error value 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, then the call is considered attached to MPI_COMM_SELF and will call the associated MPI error handler. When MPI_COMM_SELF is not 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. That initial error handler can be changed by calling MPI_Comm_set_errhandler on MPI_COMM_SELF when you're using the World model, or by the mpi_initial_errhandler CLI argument to mpiexec, or by 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, while MPI_ERRORS_ABORT gets called for all other MPI functions. That's just how it is.

Open MPI ships three predefined error handlers you can use:

  • MPI_ERRORS_ARE_FATAL — causes the program to abort all connected MPI processes. yes, 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 back to the application. Respectful. 🫶

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

  • MPI_Comm_create_errhandler and then MPI_Comm_set_errhandler
  • MPI_File_create_errhandler and then MPI_File_set_errhandler
  • MPI_Session_create_errhandler and then MPI_Session_set_errhandler, or at MPI_Session_init
  • MPI_Win_create_errhandler and then MPI_Win_set_errhandler
Important, no joke: note that MPI does not guarantee that an MPI program can continue past an error. Like, at all. That's not a vibe, that's a warning. 😭

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.

2003-2026, The Open MPI Community

okay that's the whole page, bestie!! 🎀 this was written up in the Open MPI docs and the page is dated Sep 10, 2026 — so go forth, get those file hints, and don't forget to MPI_Info_free your info_used or she will haunt you. love u, bye!! 💖✨🦋

📦 where this page comes from