Data Access with Individual File Pointers

262. 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 , page 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)

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) (binding deprecated, see Section Deprecated since MPI-2.2 ) }
{ void MPI::File::Read(void* buf, int count, const MPI::Datatype& datatype) (binding deprecated, see Section Deprecated since MPI-2.2 ) }

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) (binding deprecated, see Section Deprecated since MPI-2.2 ) }
{ void MPI::File::Read_all(void* buf, int count, const MPI::Datatype& datatype) (binding deprecated, see Section Deprecated since MPI-2.2 ) }

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) (binding deprecated, see Section Deprecated since MPI-2.2 ) }
{ void MPI::File::Write(const void* buf, int count, const MPI::Datatype& datatype) (binding deprecated, see Section Deprecated since MPI-2.2 ) }

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) (binding deprecated, see Section Deprecated since MPI-2.2 ) }
{ void MPI::File::Write_all(const void* buf, int count, const MPI::Datatype& datatype) (binding deprecated, see Section Deprecated since MPI-2.2 ) }

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) (binding deprecated, see Section Deprecated since MPI-2.2 ) }

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) (binding deprecated, see Section Deprecated since MPI-2.2 ) }

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) (binding deprecated, see Section Deprecated since MPI-2.2 ) }

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)

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 (binding deprecated, see Section Deprecated since MPI-2.2 ) }

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 (binding deprecated, see Section Deprecated since MPI-2.2 ) }

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-2.2 Standard Index
Return to MPI Forum Home Page

(Unofficial) MPI-2.2 of September 4, 2009
HTML Generated on September 10, 2009

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)

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

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

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)