9.4.3. Data Access with Individual File Pointers

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.

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

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)

int MPI_File_read(MPI_File fh, void *buf, int count, MPI_Datatype datatype, MPI_Status *status)
MPI_FILE_READ(FH, BUF, COUNT, DATATYPE, STATUS, IERROR)
<type> BUF(*)
INTEGER FH, COUNT, DATATYPE, STATUS(MPI_STATUS_SIZE), IERROR
void MPI::File::Read(void* buf, int count, const MPI::Datatype& datatype, MPI::Status& status)
void MPI::File::Read(void* buf, int count, const MPI::Datatype& datatype)

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 preexisting 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) 
 
      call MPI_FILE_OPEN( MPI_COMM_WORLD, 'myoldfile', & 
                          MPI_MODE_RDONLY, MPI_INFO_NULL, myfh, ierr ) 
      call MPI_FILE_SET_VIEW( myfh, 0, 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 
      enddo 
 
      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)

int MPI_File_read_all(MPI_File fh, void *buf, int count, MPI_Datatype datatype, MPI_Status *status)
MPI_FILE_READ_ALL(FH, BUF, COUNT, DATATYPE, STATUS, IERROR)
<type> BUF(*)
INTEGER FH, COUNT, DATATYPE, STATUS(MPI_STATUS_SIZE), IERROR
void MPI::File::Read_all(void* buf, int count, const MPI::Datatype& datatype, MPI::Status& status)
void MPI::File::Read_all(void* buf, int count, const MPI::Datatype& datatype)

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)

int MPI_File_write(MPI_File fh, void *buf, int count, MPI_Datatype datatype, MPI_Status *status)
MPI_FILE_WRITE(FH, BUF, COUNT, DATATYPE, STATUS, IERROR)
<type> BUF(*)
INTEGER FH, COUNT, DATATYPE, STATUS(MPI_STATUS_SIZE), IERROR
void MPI::File::Write(const void* buf, int count, const MPI::Datatype& datatype, MPI::Status& status)
void MPI::File::Write(const void* buf, int count, const MPI::Datatype& datatype)

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)

int MPI_File_write_all(MPI_File fh, void *buf, int count, MPI_Datatype datatype, MPI_Status *status)
MPI_FILE_WRITE_ALL(FH, BUF, COUNT, DATATYPE, STATUS, IERROR)
<type> BUF(*)
INTEGER FH, COUNT, DATATYPE, STATUS(MPI_STATUS_SIZE), IERROR
void MPI::File::Write_all(const void* buf, int count, const MPI::Datatype& datatype, MPI::Status& status)
void MPI::File::Write_all(const void* buf, int count, const MPI::Datatype& datatype)

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)

int MPI_File_iread(MPI_File fh, void *buf, int count, MPI_Datatype datatype, MPI_Request *request)
MPI_FILE_IREAD(FH, BUF, COUNT, DATATYPE, REQUEST, IERROR)
<type> BUF(*)
INTEGER FH, COUNT, DATATYPE, REQUEST, IERROR
MPI::Request MPI::File::Iread(void* buf, int count, const MPI::Datatype& datatype)

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 real words 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 word in the file. 
 
      integer   bufsize, req1, req2 
      integer, dimension(MPI_STATUS_SIZE) :: status1, status2 
      parameter (bufsize=10) 
      real      buf1(bufsize), buf2(bufsize) 
 
      call MPI_FILE_OPEN( MPI_COMM_WORLD, 'myoldfile', & 
                          MPI_MODE_RDONLY, MPI_INFO_NULL, myfh, ierr ) 
      call MPI_FILE_SET_VIEW( myfh, 0, 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_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)

int MPI_File_iwrite(MPI_File fh, void *buf, int count, MPI_Datatype datatype, MPI_Request *request)
MPI_FILE_IWRITE(FH, BUF, COUNT, DATATYPE, REQUEST, IERROR)
<type> BUF(*)
INTEGER FH, COUNT, DATATYPE, REQUEST, IERROR
MPI::Request MPI::File::Iwrite(const void* buf, int count, const MPI::Datatype& datatype)

MPI_FILE_IWRITE is a nonblocking version of the MPI_FILE_WRITE interface.

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

int MPI_File_seek(MPI_File fh, MPI_Offset offset, int whence)
MPI_FILE_SEEK(FH, OFFSET, WHENCE, IERROR)
INTEGER FH, WHENCE, IERROR
INTEGER(KIND=MPI_OFFSET_KIND) OFFSET
void MPI::File::Seek(MPI::Offset offset, int whence)

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

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

int MPI_File_get_position(MPI_File fh, MPI_Offset *offset)
MPI_FILE_GET_POSITION(FH, OFFSET, IERROR)
INTEGER FH, IERROR
INTEGER(KIND=MPI_OFFSET_KIND) OFFSET
MPI::Offset MPI::File::Get_position() const

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)

int MPI_File_get_byte_offset(MPI_File fh, MPI_Offset offset, MPI_Offset *disp)
MPI_FILE_GET_BYTE_OFFSET(FH, OFFSET, DISP, IERROR)
INTEGER FH, IERROR
INTEGER(KIND=MPI_OFFSET_KIND) OFFSET, DISP
MPI::Offset MPI::File::Get_byte_offset(const MPI::Offset disp) const

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.