Open MPI logo

MPI_File_preallocate(3) man page (version 1.3.4)

  |   Home   |   Support   |   FAQ   |  

« Return to documentation listing



NAME

       MPI_File_preallocate - Preallocates a specified amount of storage space
       at the beginning of a file (collective).

SYNTAX

       C Syntax
           #include <mpi.h>
           int MPI_File_preallocate(MPI_File fh, MPI_Offset size)

       Fortran Syntax (see FORTRAN 77 NOTES)
           INCLUDE 'mpif.h'
           MPI_FILE_PREALLOCATE(FH, SIZE, IERROR)
                  INTEGER FH, IERROR
                  INTEGER(KIND=MPI_OFFSET_KIND) SIZE

C++ Syntax

       #include <mpi.h>
       void MPI::File::Preallocate(MPI::Offset size)

INPUT/OUTPUT PARAMETER

       fh        File handle (handle).

INPUT PARAMETER

       size      Size to preallocate file, in bytes (integer).

OUTPUT PARAMETER

       IERROR    Fortran only: Error status (integer).

DESCRIPTION

       MPI_File_preallocate ensures that storage space is  allocated  for  the
       first  size  bytes of the file associated with fh. MPI_File_preallocate
       can be a very time-consuming operation.

       MPI_File_preallocate is collective; all processes  in  the  group  must
       pass  identical  values  for size. Regions of the file that have previ-
       ously been written are unaffected. For newly allocated regions  of  the
       file,  MPI_File_preallocate  has  the  same effect as writing undefined
       data. If size is larger than the  current  file  size,  the  file  size
       increases  to  size.  If size is less than or equal to the current file
       size, the file size is unchanged.

       The treatment of file pointers, pending nonblocking accesses, and  file
       consistency  is the same as with MPI_File_set_size. If MPI_MODE_SEQUEN-
       TIAL mode was specified when the file was opened, it  is  erroneous  to
       call this routine.

FORTRAN 77 NOTES

       The  MPI standard prescribes portable Fortran syntax for the SIZE argu-
       ment only for Fortran 90.  FORTRAN 77 users may  use  the  non-portable
       syntax

       the size that is set is smaller than the current file size, the file is
       truncated at the position defined by size. If the size  is  set  to  be
       larger  than the current file size, the file size becomes the set size.
       When the file size is increased this way  with  MPI_File_set_size,  new
       regions are created in the file with displacements between the old file
       size and the larger, newly set file size.

       Sun MPI I/O does not necessarily  allocate  file  space  for  such  new
       regions.  You  may reserve file space either by using MPI_File_preallo-
       cate or by performing a read or write to certain bytes.

ERRORS

       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::ERRORS_THROW_EXCEPTIONS, 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  MPI_ERRORS_RETURN.  The  error  handler   may   be   changed   with
       MPI_File_set_errhandler;      the      predefined     error     handler
       MPI_ERRORS_ARE_FATAL may be used to make I/O errors  fatal.  Note  that
       MPI  does not guarantee that an MPI program can continue past an error.

1.3.4                            Nov 11, 2009          MPI_File_preallocate(3)

« Return to documentation listing