MPIFilepreallocate(3OpenMPI) MPIFilepreallocate(3OpenMPI)

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


SSYYNNTTAAXX
       C Syntax
           #include 
           int MPIFilepreallocate(MPIFile fh, MPIOffset size)

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


CC++++ SSyynnttaaxx
       #include 
       void MPI::File::Preallocate(MPI::Offset size)


IINNPPUUTT//OOUUTTPPUUTT PPAARRAAMMEETTEERR
       fh        File handle (handle).


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


OOUUTTPPUUTT PPAARRAAMMEETTEERR
       IERROR    Fortran only: Error status (integer).


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

       MPIFilepreallocate 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,  MPIFilepreallocate  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 MPIFilesetsize. If MPIMODESEQUEN-
       TIAL mode was specified when the file was opened, it  is  erroneous  to
       call this routine.


FFOORRTTRRAANN 7777 NNOOTTEESS
       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

            INTEGER*MPIOFFSETKIND SIZE

       where  MPIOFFSETKIND  is  a  constant defined in mpif.h and gives the
       length of the declared integer in bytes.


NNOOTTEESS
       When using the collective routine MPIFilesetsize on a UNIX file,  if
       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  MPIFilesetsize,  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 MPIFilepreallo-
       cate or by performing a read or write to certain bytes.


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  MPIFilepreallocate(3OpenMPI)