Manual Pages for UNIX Darwin command on man MPI_File_open

MPIFileopen(3OpenMPI)                                MPIFileopen(3OpenMPI)



NAME
       MMPPIIFFiilleeooppeenn - Opens a file (collective).

SSYYNNTTAAXX
       C Syntax
           #include 
           int MPIFileopen(MPIComm comm, char *filename,
                  int amode, MPIInfo info,
                  MPIFile *fh)

       Fortran Syntax
           INCLUDE 'mpif.h'
           MPIFILEOPEN(COMM, FILENAME, AMODE, INFO, FH, IERROR)
             CHARACTER*(*)    FILENAME
             INTEGER      COMM, AMODE, INFO, FH, IERROR


CC++++ SSyynnttaaxx
       #include 
       static MPI::File MPI::File::Open(const MPI::Intracomm& comm,
            const char* filename, int amode, const MPI::Info& info)


IINNPPUUTT PPAARRAAMMEETTEERRSS
       comm      Communicator (handle).

       filename  Name of file to open (string).

       amode     File access mode (integer).

       info      Info object (handle).


OOUUTTPPUUTT PPAARRAAMMEETTEERRSS
       fh        New file handle (handle).

       IERROR    Fortran only: Error status (integer).


DESCRIPTION
       MPIFileopen opens the file identified by the filename filename on all
       processes in the comm communicator group. MPIFileopen is a collective
       routine;  all  processes must provide the same value for amode, and all
       processes must provide filenames that reference the same file and which
       are  textually  identical.  A  process can open a file independently of
       other processes by using the MPICOMMSELF communicator. The file  han-
       dle returned, fh, can be subsequently used to access the file until the
       file is closed using MPIFileclose. Before calling  MPIFinalize,  the
       user  is  required  to  close  (via MPIFileclose) all files that were
       opened with MPIFileopen. Note that the  communicator  comm  is  unaf-
       fected by MPIFileopen and continues to be usable in all MPI routines.
       Furthermore, use of comm will not interfere with I/O behavior.

       Initially, all processes view the file as a linear  byte  stream;  that
       is,  the  etype  and  filetype  are both MPIBYTE. The file view can be
       changed via the MPIFilesetview routine.

       The following access modes are supported (specified in amode, in a bit-
       vector OR in one of the following integer constants):

         o  MPIMODEAPPEND

         o  MPIMODECREATE - Create the file if it does not exist.

         o  MPIMODEDELETEONCLOSE

         o  MPIMODEEXCL - Error creating a file that already exists.

         o  MPIMODERDONLY - Read only.

         o  MPIMODERDWR - Reading and writing.

         o  MPIMODESEQUENTIAL

         o  MPIMODEWRONLY - Write only.

         o  MPIMODEUNIQUEOPEN

The modes MPIMODERDONLY, MPIMODERDWR, MPIMODEWRONLY, and MPIMODECREATE
have identical semantics to their POSIX counterparts. It is erroneous to spec-
ify MPIMODECREATE in conjunction with MPIMODERDONLY. Errors related to the
access mode are raised in the class MPIERRAMODE.

On single-node clusters, files are opened by default using nonatomic mode file
consistency  semantics.  The more stringent atomic-mode consistency semantics,
required for atomicity of overlapping accesses, are the default  when  proces-
sors  in  a communicator group reside on more than one node.  This setting can
be changed using MPIFilesetatomicity.

The MPIFileopen interface allows the user to pass information via  the  info
argument.  It can be set to MPIINFONULL. See the HINTS section for a list of
hints that can be set.


HHIINNTTSS
       The following hints can be used as values for the info argument.

       SETTABLE HINTS:

       - MPIINFONULL

       - sharedfiletimeout: Amount of time (in seconds) to wait  for  access
       to the shared file pointer before exiting with MPIERRTIMEDOUT.

       -  rwlocktimeout:  Amount of time (in seconds) to wait for obtaining a
       read or write lock on a contiguous chunk of a UNIX file before  exiting
       with MPIERRTIMEDOUT.

       -  noncollreadbufsize:  Maximum size of the buffer used by MPI I/O to
       satisfy multiple noncontiguous read requests in the noncollective data-
       access routines. (See NOTE, below.)

       -  noncollwritebufsize: Maximum size of the buffer used by MPI I/O to
       satisfy multiple noncontiguous  write  requests  in  the  noncollective
       data-access routines. (See NOTE, below.)

       -  collreadbufsize:   Maximum  size  of the buffer used by MPI I/O to
       satisfy multiple noncontiguous read requests in  the  collective  data-
       access routines. (See NOTE, below.)

       -  collwritebufsize:   Maximum  size of the buffer used by MPI I/O to
       satisfy multiple noncontiguous write requests in the  collective  data-
       access routines. (See NOTE, below.)

       NOTE: A buffer size smaller than the distance (in bytes) in a UNIX file
       between the first byte and the last byte of the access  request  causes
       MPI  I/O  to iterate and perform multiple UNIX read() or write() calls.
       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() (made at the MPI I/O  level)  will  access  data  not
       requested  by  this  process  in  order  to  reduce the total number of
       write() calls made. If this  is  not  desirable  behavior,  you  should
       reduce  this  buffer  size  to  equal the size of the contiguous chunks
       within the aggregate request.

       - mpiioconcurrency: (boolean) controls whether  nonblocking  I/O  rou-
       tines can bind an extra thread to an LWP.

       -  mpiiocollcontiguous: (boolean) controls whether subsequent collec-
       tive data accesses will request collectively contiguous regions of  the
       file.

       NON-SETTABLE HINTS:

       - filename: Access this hint to get the name of the file.


EERRRROORRSS
       Almost  all MPI routines return an error value; C routines as the value
       of the function and Fortran routines in the last  argument.  C++  func-
       tions  do  not  return  errors.  If the default error handler is set to
       MPI::ERRORSTHROWEXCEPTIONS, then on error the C++ exception mechanism
       will be used to throw an MPI:Exception object.

       Before  the  error  value is returned, the current MPI error handler is
       called. For MPI I/O function errors, the default error handler  is  set
       to   MPIERRORSRETURN.   The   error   handler  may  be  changed  with
       MPIFileseterrhandler;     the     predefined      error      handler
       MPIERRORSAREFATAL  may  be  used to make I/O errors fatal. Note that
       MPI does not guarantee that an MPI program can continue past an  error.




Open MPI 1.2                    September 2006         MPIFileopen(3OpenMPI)