Data Access with Individual File Pointers

15.4.3. Data Access with Individual File Pointers

Up: Data Access Next: Data Access with Shared File Pointers Previous: Data Access with Explicit Offsets

MPI maintains one individual file pointer per process per file handle. The current value of this pointer implicitly specifies the offset in the data access routines described in this section. These routines only use and update the individual file pointers maintained by MPI. The shared file pointer is not used nor updated.

The individual file pointer routines have the same semantics as the data access with explicit offset routines described in Section Data Access with Explicit Offsets, with the following modification:

the offset is defined to be the current value of the MPI-maintained individual file pointer.

After an individual file pointer operation is initiated, the individual file pointer is updated to point to the next etype after the last one that will be accessed. The file pointer is updated relative to the current view of the file.

If MPI_MODE_SEQUENTIAL mode was specified when the file was opened, it is erroneous to call the routines in this section, with the exception of MPI_FILE_GET_BYTE_OFFSET.

MPI_FILE_READ(fh, buf, count, datatype, status)
INOUT fh	file handle (handle)
OUT buf	initial address of buffer (choice)
IN count	number of elements in buffer (integer)
IN datatype	datatype of each buffer element (handle)
OUT status	status object (status)

C binding
int MPI_File_read(MPI_File fh, void *buf, int count, MPI_Datatype datatype, MPI_Status *status) int MPI_File_read_c(MPI_File fh, void *buf, MPI_Count count, MPI_Datatype datatype, MPI_Status *status) Fortran 2008 binding
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 MPI_File_read(fh, buf, count, datatype, status, ierror) !(_c) TYPE(MPI_File), INTENT(IN) :: fh TYPE(*), DIMENSION(..) :: buf INTEGER(KIND=MPI_COUNT_KIND), INTENT(IN) :: count TYPE(MPI_Datatype), INTENT(IN) :: datatype TYPE(MPI_Status) :: status INTEGER, OPTIONAL, INTENT(OUT) :: ierror Fortran binding
MPI_FILE_READ(FH, BUF, COUNT, DATATYPE, STATUS, IERROR) INTEGER FH, COUNT, DATATYPE, STATUS(MPI_STATUS_SIZE), IERROR <type> BUF(*)

MPI_FILE_READ reads a file using the individual file pointer.

Example The following Fortran code fragment is an example of reading a file until the end of file is reached:

!   Read a pre-existing input file until all data has been read. 
!   Call routine "process_input" if all requested data is read. 
!   The Fortran 90 "exit" statement exits the loop. 
 
integer   bufsize, numread, totprocessed, status(MPI_STATUS_SIZE) 
parameter (bufsize=100) 
real      localbuffer(bufsize) 
integer(kind=MPI_OFFSET_KIND) zero 
 
zero = 0 
 
call MPI_FILE_OPEN(MPI_COMM_WORLD, "myoldfile", & 
                   MPI_MODE_RDONLY, MPI_INFO_NULL, myfh, ierr) 
call MPI_FILE_SET_VIEW(myfh, zero, MPI_REAL, MPI_REAL, 'native', & 
                       MPI_INFO_NULL, ierr) 
totprocessed = 0 
do 
   call MPI_FILE_READ(myfh, localbuffer, bufsize, MPI_REAL, & 
                      status, ierr) 
   call MPI_GET_COUNT(status, MPI_REAL, numread, ierr) 
   call process_input(localbuffer, numread) 
   totprocessed = totprocessed + numread 
   if (numread < bufsize) exit 
end do 
 
write(6, 1001) numread, bufsize, totprocessed 
1001  format("No more data:  read", I3, "and expected", I3, & 
             "Processed total of", I6, "before terminating job.") 
 
call MPI_FILE_CLOSE(myfh, ierr)

MPI_FILE_READ_ALL(fh, buf, count, datatype, status)
INOUT fh	file handle (handle)
OUT buf	initial address of buffer (choice)
IN count	number of elements in buffer (integer)
IN datatype	datatype of each buffer element (handle)
OUT status	status object (status)

C binding
int MPI_File_read_all(MPI_File fh, void *buf, int count, MPI_Datatype datatype, MPI_Status *status) int MPI_File_read_all_c(MPI_File fh, void *buf, MPI_Count count, MPI_Datatype datatype, MPI_Status *status) Fortran 2008 binding
MPI_File_read_all(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 MPI_File_read_all(fh, buf, count, datatype, status, ierror) !(_c) TYPE(MPI_File), INTENT(IN) :: fh TYPE(*), DIMENSION(..) :: buf INTEGER(KIND=MPI_COUNT_KIND), INTENT(IN) :: count TYPE(MPI_Datatype), INTENT(IN) :: datatype TYPE(MPI_Status) :: status INTEGER, OPTIONAL, INTENT(OUT) :: ierror Fortran binding
MPI_FILE_READ_ALL(FH, BUF, COUNT, DATATYPE, STATUS, IERROR) INTEGER FH, COUNT, DATATYPE, STATUS(MPI_STATUS_SIZE), IERROR <type> BUF(*)

MPI_FILE_READ_ALL is a collective version of the blocking MPI_FILE_READ interface.

MPI_FILE_WRITE(fh, buf, count, datatype, status)
INOUT fh	file handle (handle)
IN buf	initial address of buffer (choice)
IN count	number of elements in buffer (integer)
IN datatype	datatype of each buffer element (handle)
OUT status	status object (status)

C binding
int MPI_File_write(MPI_File fh, const void *buf, int count, MPI_Datatype datatype, MPI_Status *status) int MPI_File_write_c(MPI_File fh, const void *buf, MPI_Count count, MPI_Datatype datatype, MPI_Status *status) Fortran 2008 binding
MPI_File_write(fh, buf, count, datatype, status, ierror) TYPE(MPI_File), INTENT(IN) :: fh TYPE(*), DIMENSION(..), INTENT(IN) :: buf INTEGER, INTENT(IN) :: count TYPE(MPI_Datatype), INTENT(IN) :: datatype TYPE(MPI_Status) :: status INTEGER, OPTIONAL, INTENT(OUT) :: ierror MPI_File_write(fh, buf, count, datatype, status, ierror) !(_c) TYPE(MPI_File), INTENT(IN) :: fh TYPE(*), DIMENSION(..), INTENT(IN) :: buf INTEGER(KIND=MPI_COUNT_KIND), INTENT(IN) :: count TYPE(MPI_Datatype), INTENT(IN) :: datatype TYPE(MPI_Status) :: status INTEGER, OPTIONAL, INTENT(OUT) :: ierror Fortran binding
MPI_FILE_WRITE(FH, BUF, COUNT, DATATYPE, STATUS, IERROR) INTEGER FH, COUNT, DATATYPE, STATUS(MPI_STATUS_SIZE), IERROR <type> BUF(*)

MPI_FILE_WRITE writes a file using the individual file pointer.

MPI_FILE_WRITE_ALL(fh, buf, count, datatype, status)
INOUT fh	file handle (handle)
IN buf	initial address of buffer (choice)
IN count	number of elements in buffer (integer)
IN datatype	datatype of each buffer element (handle)
OUT status	status object (status)

C binding
int MPI_File_write_all(MPI_File fh, const void *buf, int count, MPI_Datatype datatype, MPI_Status *status) int MPI_File_write_all_c(MPI_File fh, const void *buf, MPI_Count count, MPI_Datatype datatype, MPI_Status *status) Fortran 2008 binding
MPI_File_write_all(fh, buf, count, datatype, status, ierror) TYPE(MPI_File), INTENT(IN) :: fh TYPE(*), DIMENSION(..), INTENT(IN) :: buf INTEGER, INTENT(IN) :: count TYPE(MPI_Datatype), INTENT(IN) :: datatype TYPE(MPI_Status) :: status INTEGER, OPTIONAL, INTENT(OUT) :: ierror MPI_File_write_all(fh, buf, count, datatype, status, ierror) !(_c) TYPE(MPI_File), INTENT(IN) :: fh TYPE(*), DIMENSION(..), INTENT(IN) :: buf INTEGER(KIND=MPI_COUNT_KIND), INTENT(IN) :: count TYPE(MPI_Datatype), INTENT(IN) :: datatype TYPE(MPI_Status) :: status INTEGER, OPTIONAL, INTENT(OUT) :: ierror Fortran binding
MPI_FILE_WRITE_ALL(FH, BUF, COUNT, DATATYPE, STATUS, IERROR) INTEGER FH, COUNT, DATATYPE, STATUS(MPI_STATUS_SIZE), IERROR <type> BUF(*)

MPI_FILE_WRITE_ALL is a collective version of the blocking MPI_FILE_WRITE interface.

MPI_FILE_IREAD(fh, buf, count, datatype, request)
INOUT fh	file handle (handle)
OUT buf	initial address of buffer (choice)
IN count	number of elements in buffer (integer)
IN datatype	datatype of each buffer element (handle)
OUT request	request object (handle)

C binding
int MPI_File_iread(MPI_File fh, void *buf, int count, MPI_Datatype datatype, MPI_Request *request) int MPI_File_iread_c(MPI_File fh, void *buf, MPI_Count count, MPI_Datatype datatype, MPI_Request *request) Fortran 2008 binding
MPI_File_iread(fh, buf, count, datatype, request, ierror) TYPE(MPI_File), INTENT(IN) :: fh 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 MPI_File_iread(fh, buf, count, datatype, request, ierror) !(_c) TYPE(MPI_File), INTENT(IN) :: fh TYPE(*), DIMENSION(..), ASYNCHRONOUS :: buf INTEGER(KIND=MPI_COUNT_KIND), INTENT(IN) :: count TYPE(MPI_Datatype), INTENT(IN) :: datatype TYPE(MPI_Request), INTENT(OUT) :: request INTEGER, OPTIONAL, INTENT(OUT) :: ierror Fortran binding
MPI_FILE_IREAD(FH, BUF, COUNT, DATATYPE, REQUEST, IERROR) INTEGER FH, COUNT, DATATYPE, REQUEST, IERROR <type> BUF(*)

MPI_FILE_IREAD is a nonblocking version of the MPI_FILE_READ interface.

Example The following Fortran code fragment illustrates file pointer update semantics:

!   Read the first twenty reals in a file into two local 
!   buffers.  Note that when the first MPI_FILE_IREAD returns, 
!   the file pointer has been updated to point to the 
!   eleventh real in the file. 
 
integer   bufsize, req1, req2 
integer, dimension(MPI_STATUS_SIZE) :: status1, status2 
parameter (bufsize=10) 
real      buf1(bufsize), buf2(bufsize) 
integer(kind=MPI_OFFSET_KIND) zero 
 
zero = 0 
call MPI_FILE_OPEN(MPI_COMM_WORLD, 'myoldfile', & 
                   MPI_MODE_RDONLY, MPI_INFO_NULL, myfh, ierr) 
call MPI_FILE_SET_VIEW(myfh, zero, MPI_REAL, MPI_REAL, 'native', & 
                       MPI_INFO_NULL, ierr) 
call MPI_FILE_IREAD(myfh, buf1, bufsize, MPI_REAL, & 
                    req1, ierr) 
call MPI_FILE_IREAD(myfh, buf2, bufsize, MPI_REAL, & 
                    req2, ierr) 
 
call MPI_WAIT(req1, status1, ierr) 
call MPI_WAIT(req2, status2, ierr) 
 
call MPI_FILE_CLOSE(myfh, ierr)

MPI_FILE_IREAD_ALL(fh, buf, count, datatype, request)
INOUT fh	file handle (handle)
OUT buf	initial address of buffer (choice)
IN count	number of elements in buffer (integer)
IN datatype	datatype of each buffer element (handle)
OUT request	request object (handle)

C binding
int MPI_File_iread_all(MPI_File fh, void *buf, int count, MPI_Datatype datatype, MPI_Request *request) int MPI_File_iread_all_c(MPI_File fh, void *buf, MPI_Count count, MPI_Datatype datatype, MPI_Request *request) Fortran 2008 binding
MPI_File_iread_all(fh, buf, count, datatype, request, ierror) TYPE(MPI_File), INTENT(IN) :: fh 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 MPI_File_iread_all(fh, buf, count, datatype, request, ierror) !(_c) TYPE(MPI_File), INTENT(IN) :: fh TYPE(*), DIMENSION(..), ASYNCHRONOUS :: buf INTEGER(KIND=MPI_COUNT_KIND), INTENT(IN) :: count TYPE(MPI_Datatype), INTENT(IN) :: datatype TYPE(MPI_Request), INTENT(OUT) :: request INTEGER, OPTIONAL, INTENT(OUT) :: ierror Fortran binding
MPI_FILE_IREAD_ALL(FH, BUF, COUNT, DATATYPE, REQUEST, IERROR) INTEGER FH, COUNT, DATATYPE, REQUEST, IERROR <type> BUF(*)

MPI_FILE_IREAD_ALL is a nonblocking version of MPI_FILE_READ_ALL.

MPI_FILE_IWRITE(fh, buf, count, datatype, request)
INOUT fh	file handle (handle)
IN buf	initial address of buffer (choice)
IN count	number of elements in buffer (integer)
IN datatype	datatype of each buffer element (handle)
OUT request	request object (handle)

C binding
int MPI_File_iwrite(MPI_File fh, const void *buf, int count, MPI_Datatype datatype, MPI_Request *request) int MPI_File_iwrite_c(MPI_File fh, const void *buf, MPI_Count count, MPI_Datatype datatype, MPI_Request *request) Fortran 2008 binding
MPI_File_iwrite(fh, buf, count, datatype, request, ierror) TYPE(MPI_File), INTENT(IN) :: fh TYPE(*), DIMENSION(..), INTENT(IN), ASYNCHRONOUS :: buf INTEGER, INTENT(IN) :: count TYPE(MPI_Datatype), INTENT(IN) :: datatype TYPE(MPI_Request), INTENT(OUT) :: request INTEGER, OPTIONAL, INTENT(OUT) :: ierror MPI_File_iwrite(fh, buf, count, datatype, request, ierror) !(_c) TYPE(MPI_File), INTENT(IN) :: fh TYPE(*), DIMENSION(..), INTENT(IN), ASYNCHRONOUS :: buf INTEGER(KIND=MPI_COUNT_KIND), INTENT(IN) :: count TYPE(MPI_Datatype), INTENT(IN) :: datatype TYPE(MPI_Request), INTENT(OUT) :: request INTEGER, OPTIONAL, INTENT(OUT) :: ierror Fortran binding
MPI_FILE_IWRITE(FH, BUF, COUNT, DATATYPE, REQUEST, IERROR) INTEGER FH, COUNT, DATATYPE, REQUEST, IERROR <type> BUF(*)

MPI_FILE_IWRITE is a nonblocking version of MPI_FILE_WRITE.

MPI_FILE_IWRITE_ALL(fh, buf, count, datatype, request)
INOUT fh	file handle (handle)
IN buf	initial address of buffer (choice)
IN count	number of elements in buffer (integer)
IN datatype	datatype of each buffer element (handle)
OUT request	request object (handle)

C binding
int MPI_File_iwrite_all(MPI_File fh, const void *buf, int count, MPI_Datatype datatype, MPI_Request *request) int MPI_File_iwrite_all_c(MPI_File fh, const void *buf, MPI_Count count, MPI_Datatype datatype, MPI_Request *request) Fortran 2008 binding
MPI_File_iwrite_all(fh, buf, count, datatype, request, ierror) TYPE(MPI_File), INTENT(IN) :: fh TYPE(*), DIMENSION(..), INTENT(IN), ASYNCHRONOUS :: buf INTEGER, INTENT(IN) :: count TYPE(MPI_Datatype), INTENT(IN) :: datatype TYPE(MPI_Request), INTENT(OUT) :: request INTEGER, OPTIONAL, INTENT(OUT) :: ierror MPI_File_iwrite_all(fh, buf, count, datatype, request, ierror) !(_c) TYPE(MPI_File), INTENT(IN) :: fh TYPE(*), DIMENSION(..), INTENT(IN), ASYNCHRONOUS :: buf INTEGER(KIND=MPI_COUNT_KIND), INTENT(IN) :: count TYPE(MPI_Datatype), INTENT(IN) :: datatype TYPE(MPI_Request), INTENT(OUT) :: request INTEGER, OPTIONAL, INTENT(OUT) :: ierror Fortran binding
MPI_FILE_IWRITE_ALL(FH, BUF, COUNT, DATATYPE, REQUEST, IERROR) INTEGER FH, COUNT, DATATYPE, REQUEST, IERROR <type> BUF(*)

MPI_FILE_IWRITE_ALL is a nonblocking version of MPI_FILE_WRITE_ALL.

MPI_FILE_SEEK(fh, offset, whence)
INOUT fh	file handle (handle)
IN offset	file offset (integer)
IN whence	update mode (state)

C binding
int MPI_File_seek(MPI_File fh, MPI_Offset offset, int whence) Fortran 2008 binding
MPI_File_seek(fh, offset, whence, ierror) TYPE(MPI_File), INTENT(IN) :: fh INTEGER(KIND=MPI_OFFSET_KIND), INTENT(IN) :: offset INTEGER, INTENT(IN) :: whence INTEGER, OPTIONAL, INTENT(OUT) :: ierror Fortran binding
MPI_FILE_SEEK(FH, OFFSET, WHENCE, IERROR) INTEGER FH, WHENCE, IERROR INTEGER(KIND=MPI_OFFSET_KIND) OFFSET

MPI_FILE_SEEK updates the individual file pointer according to whence, which has the following possible values:

MPI_SEEK_SET	the pointer is set to offset
MPI_SEEK_CUR	the pointer is set to the current pointer position plus offset
MPI_SEEK_END	the pointer is set to the end of file plus offset

The offset can be negative, which allows seeking backwards. It is erroneous to seek to a negative position in the view.

MPI_FILE_GET_POSITION(fh, offset)
IN fh	file handle (handle)
OUT offset	offset of individual pointer (integer)

C binding
int MPI_File_get_position(MPI_File fh, MPI_Offset *offset) Fortran 2008 binding
MPI_File_get_position(fh, offset, ierror) TYPE(MPI_File), INTENT(IN) :: fh INTEGER(KIND=MPI_OFFSET_KIND), INTENT(OUT) :: offset INTEGER, OPTIONAL, INTENT(OUT) :: ierror Fortran binding
MPI_FILE_GET_POSITION(FH, OFFSET, IERROR) INTEGER FH, IERROR INTEGER(KIND=MPI_OFFSET_KIND) OFFSET

MPI_FILE_GET_POSITION returns, in offset, the current position of the individual file pointer in etype units relative to the current view.

Advice to users.

The offset can be used in a future call to MPI_FILE_SEEK using whence = MPI_SEEK_SET to return to the current position. To set the displacement to the current file pointer position, first convert offset into an absolute byte position using MPI_FILE_GET_BYTE_OFFSET, then call MPI_FILE_SET_VIEW with the resulting displacement. ( End of advice to users.)

MPI_FILE_GET_BYTE_OFFSET(fh, offset, disp)
IN fh	file handle (handle)
IN offset	offset (integer)
OUT disp	absolute byte position of offset (integer)

C binding
int MPI_File_get_byte_offset(MPI_File fh, MPI_Offset offset, MPI_Offset *disp) Fortran 2008 binding
MPI_File_get_byte_offset(fh, offset, disp, ierror) TYPE(MPI_File), INTENT(IN) :: fh INTEGER(KIND=MPI_OFFSET_KIND), INTENT(IN) :: offset INTEGER(KIND=MPI_OFFSET_KIND), INTENT(OUT) :: disp INTEGER, OPTIONAL, INTENT(OUT) :: ierror Fortran binding
MPI_FILE_GET_BYTE_OFFSET(FH, OFFSET, DISP, IERROR) INTEGER FH, IERROR INTEGER(KIND=MPI_OFFSET_KIND) OFFSET, DISP

MPI_FILE_GET_BYTE_OFFSET converts a view-relative offset into an absolute byte position. The absolute byte position (from the beginning of the file) of offset relative to the current view of fh is returned in disp.

Up: Data Access Next: Data Access with Shared File Pointers Previous: Data Access with Explicit Offsets

Return to MPI-5.0 Standard Index
Return to MPI Forum Home Page

(Unofficial) MPI-5.0 of June 9, 2025
HTML Generated on March 2, 2025