MPI_File_open - Opens a file


SYNOPSIS

       C:

            #include "mpi.h"

            int MPI_File_open(MPI_Comm comm, char *filename, int amode,
            MPI_Info info, MPI_File *fh)

       Fortran:

            INCLUDE "mpif.h" (or USE MPI)

            CHARACTER*(*) filename
            INTEGER comm, amode, info, fh, ierror

            CALL MPI_FILE_OPEN(comm, filename, amode, info,
            fh, ierror)


DESCRIPTION

       MPI_File_open opens the file identified by filename on all
       processes in the comm communicator group.

       MPI_File_open accepts the following arguments:

       comm      Specifies the communicator (handle)

       filename  Specifies the name of the file to open (string)

       amode     Specifies the file access mode (integer)

       info      Specifies the information object handle that
                 provides hints. Hints can include such
                 information as file access patterns and file
                 system specifics to direct optimization.  For
                 more details, see the section titled "Reserved
                 File Hints."

       fh         Returns the file handle (handle)

       ierror    Specifies the return code value for successful
                 completion, which is in MPI_SUCCESS.
                 MPI_SUCCESS is defined in the mpif.h file.

       MPI_File_open is a collective routine.  All processes must
       provide the same value for amode, and all processes must
       provide file names that reference the same file.  (Values
       for info can vary).  comm must be an intracommunicator;
       you must not pass an intercommunicator to MPI_File_open.
       The default file error handler is used to raise errors in

       other processes by using the MPI_COMM_SELF communicator.
       When the file handle is returned, fh can be used to access
       the file until the file is closed by the use of the
       MPI_File_close routine.  Before calling MPI_Finalize, the
       user is required to use MPI_File_close to close all files
       that were opened by using MPI_File_open.  Note that the
       communicator, comm, is unaffected by MPI_File_open and
       continues to be usable in all MPI routines (for example,
       MPI_Send).  Furthermore, the use of comm does not
       interfere with I/O behavior.

   Specifying the File Name
       The file name is an ordinary UNIX path name.  This name
       might be different from process to process, but it must
       resolve to the same file on all processes.

       Initially, all processes view the file as a linear byte
       stream, and each process views data in its own native
       representation (no data representation conversion is
       performed). (POSIX files are linear byte streams in the
       native representation.) You can use the MPI_File_set_view
       routine to change the file view.

   Reserved File Hints
       Hints specified through the info argument can enable an
       implementation to deliver increased I/O performance or
       minimize the use of system resources.  However, hints do
       not change the semantics of any of the I/O interfaces.  In
       other words, an implementation is free to ignore all
       hints. The opaque info object specifies hints on a per
       file basis, in the following commands: MPI_FILE_OPEN,
       MPI_FILE_DELETE, MPI_FILE_SET_VIEW, and MPI_FILE_SET_INFO.

       This section provides some potentially useful hints (info
       key values).  These key values are reserved. An
       implementation is not required to interpret these key
       values, but if it does interpret a key value, it must
       provide the functionality described.

       The following hints mainly affect access patterns and the
       layout of data on parallel I/O devices. For each hint name
       introduced, the purpose of the hint and the type of the
       hint value are provided. The "[SAME]" annotation specifies
       that the hint values provided by all participating
       processes must be identical; otherwise the program is
       erroneous. In addition, some hints are context dependent,
       and are used by an implementation only at specific times
       (for example, file_perm is useful only during file
       creation).

       access_style (comma separated list of strings)
                                Specifies the manner in which the
                                file will be accessed until the

                                access_style key value is
                                altered. The hint value is a
                                comma separated list of the
                                following: read_once, write_once,
                                read_mostly, write_mostly,
                                sequential, reverse_sequential,
                                and random.

       collective_buffering (boolean) [SAME]
                                Specifies whether the application
                                can benefit from collective
                                buffering. Collective buffering
                                is an optimization performed on
                                collective accesses. Accesses to
                                the file are performed on behalf
                                of all processes in the group by
                                a number of target nodes.  These
                                target nodes coalesce small
                                requests into large disk
                                accesses.  Legal values for this
                                key are true and false.
                                Collective buffering parameters
                                are further directed by using the
                                following additional hints:
                                cb_block_size, cb_buffer_size,
                                and cb_nodes.

       cb_block_size (integer) [SAME]
                                Specifies the block size to be
                                used for collective buffering
                                file access. Target nodes access
                                data in chunks of this size. The
                                chunks are distributed among
                                target nodes in a round-robin
                                (cyclic) pattern.

       cb_buffer_size (integer) [SAME]
                                Specifies the total buffer space
                                that can be used for collective
                                buffering on each target node,
                                usually a multiple of
                                cb_block_size.

       cb_nodes (integer) [SAME]
                                Specifies the number of target
                                nodes to be used for collective
                                buffering.

       chunked (comma separated list of integers) [SAME]
                                Specifies that the file consists
                                of a multidimensional array that
                                is often accessed by subarrays.
                                The value for this hint is a

                                dimensions, starting from the
                                most significant one (for an
                                array stored in row-major order,
                                as in C, the most significant
                                dimension is the first one; for
                                an array stored in column-major
                                order, as in Fortran, the most
                                significant dimension is the last
                                one, and array dimensions should
                                be reversed).

       chunked_item (comma separated list of integers) [SAME]
                                Specifies the size of each array
                                entry, in bytes.

       chunked_size (comma separated list of integers) [SAME]
                                Specifies the dimensions of the
                                subarrays. This is a comma
                                separated list of array
                                dimensions, starting from the
                                most significant one.

       filename (string)        Specifies the file name used when
                                the file was opened. If the
                                implementation is capable of
                                returning the file name of an
                                open file, MPI_FILE_GET_INFO uses
                                this key to return the file name.
                                This key is ignored when passed
                                to MPI_FILE_OPEN,
                                MPI_FILE_SET_VIEW,
                                MPI_FILE_SET_INFO, and
                                MPI_FILE_DELETE.

       file_perm (string) [SAME]
                                Specifies the file permissions to
                                use for file creation.  Setting
                                this hint is useful only when the
                                hint is passed to MPI_FILE_OPEN
                                with an amode that includes
                                MPI_MODE_CREATE. The set of legal
                                values for this key is
                                implementation dependent.

       io_node_list (comma separated list of strings) [SAME]
                                Specifies the list of I/O devices
                                that should be used to store the
                                file. This hint is most relevant
                                when the file is created.

       nb_proc (integer) [SAME] Specifies the number of parallel
                                processes that will typically be
                                assigned to run programs that

                                most relevant when the file is
                                created.

       num_io_nodes (integer) [SAME]
                                Specifies the number of I/O
                                devices in the system. This hint
                                is most relevant when the file is
                                created.

       striping_factor (integer) [SAME]
                                Specifies the number of I/O
                                devices across which the file
                                should be striped, and is
                                relevant only when the file is
                                created.

       striping_unit (integer) [SAME]
                                Specifies the suggested striping
                                unit to be used for this file.
                                The striping unit is the amount
                                of consecutive data assigned to
                                one I/O device before progressing
                                to the next device, when striping
                                across a number of devices. It is
                                expressed in bytes. This hint is
                                relevant only when the file is
                                created.

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

       MPI_MODE_RDONLY             Specifies read only.

       MPI_MODE_RDWR               Specifies read and write.

       MPI_MODE_WRONLY             Specifies write only.

       MPI_MODE_CREATE             Creates the file if it does
                                   not exist.

       MPI_MODE_EXCL               Specifies error if creating a
                                   file that already exists.

       MPI_MODE_DELETE_ON_CLOSE    Deletes the file on close
                                   (equivalent to performing an
                                   MPI_File_delete command).

       MPI_MODE_UNIQUE_OPEN        Specifies that the file will
                                   not be concurrently opened
                                   elsewhere. This mode allows an
                                   implementation to optimize

                                   overhead of file locking.  You
                                   must not open a file in this
                                   mode unless the file will not
                                   be concurrently opened
                                   elsewhere, inside or outside
                                   of the MPI environment.  In
                                   particular, one needs to be
                                   aware of potential external
                                   events that might open files
                                   (for example, automated backup
                                   facilities). When
                                   MPI_MODE_UNIQUE_OPEN is
                                   specified, the user is
                                   responsible for ensuring that
                                   no such external events occur.

       MPI_MODE_SEQUENTIAL         NOTE:  This mode is not
                                   supported in the MPT 1.3
                                   release.

                                   Specifies that the file will
                                   be accessed only sequentially.
                                   This mode allows an
                                   implementation to optimize
                                   access to some sequential
                                   devices (tapes and network
                                   streams).  You must not
                                   attempt nonsequential access
                                   to a file that has been opened
                                   in this mode.

       MPI_MODE_APPEND             Sets initial position of all
                                   file pointers to end of file.
                                   Specifying this mode only
                                   guarantees that all shared and
                                   individual file pointers are
                                   positioned at the initial end
                                   of file when MPI_File_open
                                   returns.  Subsequent
                                   positioning of file pointers
                                   is application dependent.  In
                                   particular, the implementation
                                   does not ensure that all write
                                   operations are appended.

       C/C++ users can use bit vector OR ( ) to combine these
       constants; Fortran 90 users can use the bit vector IOR
       intrinsic.  Fortran 77 users can use (nonportably) bit
       vector IOR on systems that support it. Alternatively,
       Fortran users can use (portably) integer addition to OR
       the constants. (Each constant should appear at most once
       in the addition).

       the bitwise OR and the sum of any distinct set of these
       constants is equivalent.

       The modes MPI_MODE_RDONLY, MPI_MODE_RDWR, MPI_MODE_WRONLY,
       MPI_MODE_CREATE, and MPI_MODE_EXCL have identical
       semantics to their POSIX counterparts.  You must specify
       exactly one of MPI_MODE_RDONLY, MPI_MODE_RDWR, or
       MPI_MODE_WRONLY.  You must not specify MPI_MODE_CREATE or
       MPI_MODE_EXCL in conjunction with MPI_MODE_RDONLY.

       Errors related to the access mode are raised in the
       MPI_ERR_AMODE class.

       The info argument provides information regarding file
       access patterns and file system specifics. The
       MPI_INFO_NULL constant can be used when no information
       needs to be specified.

       Some file attributes are inherently implementation
       dependent (for example, file permissions).  To set these
       attributes, use either the info argument or facilities
       outside of the scope of MPI.

       By default, files are opened by the use of nonatomic mode
       file consistency semantics.  The more stringent atomic
       mode consistency semantics, required for atomicity of
       conflicting accesses, can be set by the use of
       MPI_FILE_SET_ATOMICITY.

   Notes for Fortran
       All MPI objects (for example, MPI_Datatype, MPI_Comm,
       MPI_File) are of type INTEGER.


SEE ALSO

       MPI_File_close(3), MPI_File_delete(3),
       MPI_File_set_atomicity(3), MPI_File_set_view(3), MPI_IO(3)


Man(1) output converted with man2html