Synopsis

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

Input Parameters

comm

communicator (handle)

filename

name of file to open (string)

amode

file access mode (integer)

info

info object (handle)

Output Parameters

fh

new file handle (handle)

Description

MPI_File_open collectively opens a file identified by filename on all processes in the comm communicator group and returns a file handle in fh.

This is a collective routine requiring all processes to provide the same value for amode and filenames that reference the same file; comm must be an intra-communicator. The returned file handle can be used to access the file until it is closed with MPI_FILE_CLOSE, and all files opened with MPI_FILE_OPEN must be closed before calling MPI_FINALIZE. Initially, all processes view the file as a linear byte stream with displacement zero and etype and filetype equal to MPI_BYTE, and files are opened using nonatomic mode file consistency semantics by default. Errors are raised using the default file error handler, and errors related to access mode are raised in the class MPI_ERR_AMODE. It is erroneous to specify MPI_MODE_CREATE or MPI_MODE_EXCL with MPI_MODE_RDONLY, and erroneous to specify MPI_MODE_SEQUENTIAL with MPI_MODE_RDWR. Specifying MPI_MODE_APPEND only guarantees that all shared and individual file pointers are positioned at the initial end of file when MPI_FILE_OPEN returns. In multithreaded programs, any split collective begin and end operation called by a process on a file handle must be called from the same thread. On some implementations the file namespace may not be identical from all processes, so users are responsible for ensuring that a single file is referenced by the filename argument.

Thread and Interrupt Safety

This routine is thread-safe. This means that this routine may be safely used by multiple threads without the need for any user-provided thread locks. However, the routine is not interrupt safe. Typically, this is due to the use of memory allocation routines such as 'malloc' or other non-MPICH runtime routines that are themselves not interrupt-safe.

Notes for Fortran

All MPI routines in Fortran (except for 'MPI_WTIME' and 'MPI_WTICK') have an additional argument 'ierr' at the end of the argument list. 'ierr' is an integer and has the same meaning as the return value of the routine in C. In Fortran, MPI routines are subroutines, and are invoked with the 'call' statement.

All MPI objects (e.g., 'MPI_Datatype', 'MPI_Comm') are of type 'INTEGER' in Fortran.

Errors

All MPI routines (except 'MPI_Wtime' and 'MPI_Wtick') return an error value; C routines as the value of the function and Fortran routines in the last argument. Before the value is returned, the current MPI error handler is called. By default, this error handler aborts the MPI job. The error handler may be changed with 'MPI_Comm_set_errhandler' (for communicators), 'MPI_File_set_errhandler' (for files), and 'MPI_Win_set_errhandler' (for RMA windows). The MPI-1 routine 'MPI_Errhandler_set' may be used but its use is deprecated. The predefined error handler 'MPI_ERRORS_RETURN' may be used to cause error values to be returned. Note that MPI does not guarantee that an MPI program can continue past an error; however, MPI implementations will attempt to continue whenever possible.

  • MPI_SUCCESS - No error; MPI routine completed successfully.

  • MPI_ERR_ARG - Invalid argument. Some argument is invalid and is not identified by a specific error class (e.g., 'MPI_ERR_RANK').

  • MPI_ERR_OTHER - Other error; use 'MPI_Error_string' to get more information about this error code.