From 601e5efca8cae2fa61618c866b7119bfc797df46 Mon Sep 17 00:00:00 2001 From: Edgar Gabriel Date: Wed, 8 Jul 2015 13:27:05 -0500 Subject: [PATCH] add the manpages for the new MPI-3.1 non-blocking collective I/O operations. --- ompi/mpi/man/man3/MPI_File_iread_all.3in | 86 ++++++++++++++ ompi/mpi/man/man3/MPI_File_iread_at_all.3in | 112 ++++++++++++++++++ ompi/mpi/man/man3/MPI_File_iwrite_all.3in | 91 +++++++++++++++ ompi/mpi/man/man3/MPI_File_iwrite_at_all.3in | 114 +++++++++++++++++++ ompi/mpi/man/man3/Makefile.extra | 4 + 5 files changed, 407 insertions(+) create mode 100644 ompi/mpi/man/man3/MPI_File_iread_all.3in create mode 100644 ompi/mpi/man/man3/MPI_File_iread_at_all.3in create mode 100644 ompi/mpi/man/man3/MPI_File_iwrite_all.3in create mode 100644 ompi/mpi/man/man3/MPI_File_iwrite_at_all.3in diff --git a/ompi/mpi/man/man3/MPI_File_iread_all.3in b/ompi/mpi/man/man3/MPI_File_iread_all.3in new file mode 100644 index 0000000000..79df566711 --- /dev/null +++ b/ompi/mpi/man/man3/MPI_File_iread_all.3in @@ -0,0 +1,86 @@ +.\" -*- nroff -*- +.\" Copyright 2010 Cisco Systems, Inc. All rights reserved. +.\" Copyright 2006-2008 Sun Microsystems, Inc. +.\" Copyright (c) 1996 Thinking Machines Corporation +.\" $COPYRIGHT$ +.TH MPI_File_iread_all 3 "#OMPI_DATE#" "#PACKAGE_VERSION#" "#PACKAGE_NAME#" +.SH NAME +\fBMPI_File_iread_all\fP \- Reads a file starting at the location specified by the individual file pointer (nonblocking, collective). + +.SH SYNTAX +.ft R +.nf +C Syntax + #include + int MPI_File_iread_all(MPI_File \fIfh\fP, void \fI*buf\fP, int \fIcount\fP, + MPI_Datatype \fIdatatype\fP, MPI_Request \fI*request\fP) + +.fi +.SH Fortran Syntax +.nf + INCLUDE 'mpif.h' + MPI_FILE_IREAD_ALL(\fIFH\fP, \fIBUF\fP, \fICOUNT\fP, \fIDATATYPE\fP, \fIREQUEST\fP,\fI IERROR\fP) + BUF(*) + INTEGER FH, COUNT, DATATYPE, REQUEST, IERROR + +.fi +.SH C++ Syntax +.nf +#include +MPI::Request MPI::File::Iread(void* \fIbuf\fP, int \fIcount\fP, + const MPI::Datatype& \fIdatatype\fP) + +.fi +.SH INPUT/OUTPUT PARAMETER +.ft R +.TP 1i +fh +File handle (handle). + +.SH INPUT PARAMETERS +.ft R +.TP 1i +count +Number of elements in the buffer (integer). +.ft R +.TP 1i +datatype +Data type of each buffer element (handle). + +.SH OUTPUT PARAMETERS +.ft R +.TP 1i +buf +Initial address of buffer (choice). +.ft R +.TP 1i +request +Request object (handle). +.TP 1i +IERROR +Fortran only: Error status (integer). + +.SH DESCRIPTION +.ft R +MPI_File_iread_all is a nonblocking version of MPI_File_read_all. It attempts to read from the file associated with +.I fh +at the current individual file pointer position maintained by the system in which a total number of +.I count +data items having +.I datatype +type are read into the user's buffer +.I buf. +The data is taken out of those parts of the +file specified by the current view. MPI_File_iread_all stores the +number of data-type elements actually read in +.I status. +All other fields of +.I status +are undefined. It is erroneous to call this function if MPI_MODE_SEQUENTIAL mode was specified when the file was opened. + +.SH 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++ functions 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. +.sp +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. + diff --git a/ompi/mpi/man/man3/MPI_File_iread_at_all.3in b/ompi/mpi/man/man3/MPI_File_iread_at_all.3in new file mode 100644 index 0000000000..0a6891e7b7 --- /dev/null +++ b/ompi/mpi/man/man3/MPI_File_iread_at_all.3in @@ -0,0 +1,112 @@ +.\" -*- nroff -*- +.\" Copyright 2010 Cisco Systems, Inc. All rights reserved. +.\" Copyright 2006-2008 Sun Microsystems, Inc. +.\" Copyright (c) 1996 Thinking Machines Corporation +.\" $COPYRIGHT$ +.TH MPI_File_iread_at_all 3 "#OMPI_DATE#" "#PACKAGE_VERSION#" "#PACKAGE_NAME#" +.SH NAME +\fBMPI_File_iread_at_all\fP \- Reads a file at an explicitly specified offset (nonblocking, collective). + +.SH SYNTAX +.ft R +.nf +C Syntax + #include + int MPI_File_iread_at_all(MPI_File \fIfh\fP, MPI_Offset \fIoffset\fP, + void \fI*buf\fP, int \fIcount\fP, MPI_Datatype \fIdatatype\fP, + MPI_Request \fI*request\fP) + +.fi +.SH Fortran Syntax (see FORTRAN 77 NOTES) +.nf + INCLUDE 'mpif.h' + MPI_FILE_IREAD_AT_ALL(\fIFH\fP, \fIOFFSET\fP, \fIBUF\fP, \fICOUNT\fP, \fIDATATYPE\fP, \fIREQUEST\fP, \fIIERROR\fP) + \fIBUF\fP(*) + INTEGER \fIFH, COUNT, DATATYPE, REQUEST, IERROR\fP + INTEGER(KIND=MPI_OFFSET_KIND) \fIOFFSET\fP + +.fi +.SH C++ Syntax +.nf +#include +MPI::Request MPI::File::Iread_at(MPI::Offset \fIoffset\fP, void* \fIbuf\fP, + int \fIcount\fP, const MPI::Datatype& \fIdatatype\fP) + +.fi +.SH INPUT PARAMETERS +.ft R +.TP 1i +fh +File handle (handle). +.ft R +.TP 1i +offset +File offset (integer). +.ft R +.TP 1i +count +Number of elements in the buffer (integer). +.ft R +.TP 1i +datatype +Data type of each buffer element (handle). + +.SH OUTPUT PARAMETERS +.ft R +.TP 1i +buf +Initial address of the buffer (choice). +.ft R +.TP 1i +request +Request object (handle). +.TP 1i +IERROR +Fortran only: Error status (integer). + +.SH DESCRIPTION +.ft R +MPI_File_iread_at_all is the nonblocking version of MPI_File_read_at_all. + +MPI_File_iread_at_all is a nonblocking routine that attempts to read from the file associated with +.I fh +at the +.I offset +position a total number of +.I count +data items having +.I datatype +type into the user's buffer +.I buf. +The +.I offset +is in etype units relative to the current view. That is, holes are not counted +when locating an offset. The data is taken out of those parts of the +file specified by the current view. MPI_File_iread_at_all stores the +number of +.I datatype +elements actually read in +.I status. +All other fields of +.I status +are undefined. + +.SH FORTRAN 77 NOTES +.ft R +The MPI standard prescribes portable Fortran syntax for +the \fIOFFSET\fP argument only for Fortran 90. Sun FORTRAN 77 +users may use the non-portable syntax +.sp +.nf + INTEGER*MPI_OFFSET_KIND \fIOFFSET\fP +.fi +.sp +where MPI_OFFSET_KIND is a constant defined in mpif.h +and gives the length of the declared integer in bytes. + +.SH 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++ functions 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. +.sp +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. + diff --git a/ompi/mpi/man/man3/MPI_File_iwrite_all.3in b/ompi/mpi/man/man3/MPI_File_iwrite_all.3in new file mode 100644 index 0000000000..c5310cea34 --- /dev/null +++ b/ompi/mpi/man/man3/MPI_File_iwrite_all.3in @@ -0,0 +1,91 @@ +.\" -*- nroff -*- +.\" Copyright 2013 Los Alamos National Security, LLC. All rights reserved. +.\" Copyright 2010 Cisco Systems, Inc. All rights reserved. +.\" Copyright 2006-2008 Sun Microsystems, Inc. +.\" Copyright (c) 1996 Thinking Machines Corporation +.\" $COPYRIGHT$ +.TH MPI_File_iwrite_all 3 "#OMPI_DATE#" "#PACKAGE_VERSION#" "#PACKAGE_NAME#" +.SH NAME +\fBMPI_File_iwrite_all\fP \- Writes a file starting at the location specified by the individual file pointer (nonblocking, collective). + +.SH SYNTAX +.ft R +.nf +C Syntax + #include + int MPI_File_iwrite_all(MPI_File \fIfh\fP, const void \fI*buf\fP, int \fIcount\fP, + MPI_Datatype \fIdatatype\fP, MPI_Request \fI*request\fP) + +.fi +.SH Fortran Syntax +.nf + INCLUDE 'mpif.h' + MPI_FILE_IWRITE_ALL(\fIFH\fP, \fIBUF\fP, \fICOUNT\fP, \fIDATATYPE\fP, \fIREQUEST\fP,\fI IERROR\fP) + BUF(*) + INTEGER FH, COUNT, DATATYPE, REQUEST, IERROR + +.fi +.SH C++ Syntax +.nf +#include +MPI::Request MPI::File::Iwrite(const void* \fIbuf\fP, int \fIcount\fP, + const MPI::Datatype& \fIdatatype\fP) + +.fi +.SH INPUT/OUTPUT PARAMETER +.ft R +.TP 1i +fh +File handle (handle). + +.SH INPUT PARAMETERS +.ft R +.TP 1i +buf +Initial address of buffer (choice). +.ft R +.TP 1i +count +Number of elements in buffer (integer). +.ft R +.TP 1i +datatype +Data type of each buffer element (handle). + +.SH OUTPUT PARAMETER +.ft R +.TP 1i +request +Request object (handle). +.TP 1i +IERROR +Fortran only: Error status (integer). + +.SH DESCRIPTION +.ft R +MPI_File_iwrite_all is a nonblocking version of the MPI_File_write_all interface. It attempts to write into the file associated with +.I fh +(at the current individual file pointer position maintained by the system) a total number of +.I count +data items having +.I datatype +type from the user's buffer +.I buf. +The data is written into those parts of the +file specified by the current view. MPI_File_iwrite_all stores the +number of +.I datatype +elements actually written in +.I status. +All other fields of +.I status +are undefined. +.sp +It is erroneous to call this function if MPI_MODE_SEQUENTIAL mode was specified when the file was open. + +.SH 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++ functions 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. +.sp +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. + diff --git a/ompi/mpi/man/man3/MPI_File_iwrite_at_all.3in b/ompi/mpi/man/man3/MPI_File_iwrite_at_all.3in new file mode 100644 index 0000000000..4fc63814f3 --- /dev/null +++ b/ompi/mpi/man/man3/MPI_File_iwrite_at_all.3in @@ -0,0 +1,114 @@ +.\" -*- nroff -*- +.\" Copyright 2013 Los Alamos National Security, LLC. All rights reserved. +.\" Copyright 2010 Cisco Systems, Inc. All rights reserved. +.\" Copyright 2006-2008 Sun Microsystems, Inc. +.\" Copyright (c) 1996 Thinking Machines Corporation +.\" $COPYRIGHT$ +.TH MPI_File_iwrite_at_all 3 "#OMPI_DATE#" "#PACKAGE_VERSION#" "#PACKAGE_NAME#" +.SH NAME +\fBMPI_File_iwrite_at_all\fP \- Writes a file at an explicitly specified offset (nonblocking, collective). + +.SH SYNTAX +.ft R +.nf +C Syntax + #include + int MPI_File_iwrite_at_all(MPI_File \fIfh\fP, MPI_Offset \fIoffset\fP, + const void \fI*buf\fP, int \fIcount\fP, MPI_Datatype \fIdatatype\fP, MPI_Request \fI*request\fP) + +.fi +.SH Fortran Syntax (see FORTRAN 77 NOTES) +.nf + INCLUDE 'mpif.h' + MPI_FILE_IWRITE_AT_ALL(\fIFH\fP, \fIOFFSET\fP, \fIBUF\fP, \fICOUNT\fP, \fIDATATYPE\fP, \fIREQUEST\fP, \fIIERROR\fP) + \fIBUF\fP(*) + INTEGER \fIFH, COUNT, DATATYPE, REQUEST, IERROR\fP + INTEGER(KIND=MPI_OFFSET_KIND) \fIOFFSET\fP + +.fi +.SH C++ Syntax +.nf +#include +MPI::Request MPI::File::Iwrite_at(MPI::Offset \fIoffset\fP, const void* \fIbuf\fP, + int \fIcount\fP, const MPI::Datatype& \fIdatatype\fP) + +.fi +.SH INPUT/OUTPUT PARAMETER +.ft R +.TP 1i +fh +File handle (handle). + +.SH INPUT PARAMETERS +.ft R +.TP 1i +offset +File offset (integer). +.ft R +.TP 1i +buf +Initial address of buffer (choice). +.ft R +.TP 1i +count +Number of elements in buffer (integer). +.ft R +.TP 1i +datatype +Data type of each buffer element (handle). + +.SH OUTPUT PARAMETERS +.ft R +.TP 1i +request +Request object (handle). +.TP 1i +IERROR +Fortran only: Error status (integer). + +.SH DESCRIPTION +.ft R +MPI_File_iwrite_at_all is a nonblocking version of MPI_File_write_at_all. It attempts to write into the file associated with +.I fh +(at the +.I offset +position) a total number of +.I count +data items having +.I datatype +type from the user's buffer +.I buf. +The offset is in +.I etype +units relative to the current view. That is, holes are not counted +when locating an offset. The data is written into those parts of the +file specified by the current view. MPI_File_iwrite_at_all stores the +number of +.I datatype +elements actually written in +.I status. +All other fields of +.I status +are undefined. The request structure can be passed to MPI_Wait or MPI_Test, which will return a status with the number of bytes actually accessed. +.sp +It is erroneous to call this function if MPI_MODE_SEQUENTIAL mode was specified when the file was open. + +.SH FORTRAN 77 NOTES +.ft R +The MPI standard prescribes portable Fortran syntax for +the \fIOFFSET\fP argument only for Fortran 90. FORTRAN 77 +users may use the non-portable syntax +.sp +.nf + INTEGER*MPI_OFFSET_KIND \fIOFFSET\fP +.fi +.sp +where MPI_OFFSET_KIND is a constant defined in mpif.h +and gives the length of the declared integer in bytes. + +.SH 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++ functions 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. +.sp +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. + diff --git a/ompi/mpi/man/man3/Makefile.extra b/ompi/mpi/man/man3/Makefile.extra index c15e674777..a6152f7e8e 100644 --- a/ompi/mpi/man/man3/Makefile.extra +++ b/ompi/mpi/man/man3/Makefile.extra @@ -126,9 +126,13 @@ mpi_api_man_pages = \ mpi/man/man3/MPI_File_get_view.3 \ mpi/man/man3/MPI_File_iread.3 \ mpi/man/man3/MPI_File_iread_at.3 \ + mpi/man/man3/MPI_File_iread_all.3 \ + mpi/man/man3/MPI_File_iread_at_all.3 \ mpi/man/man3/MPI_File_iread_shared.3 \ mpi/man/man3/MPI_File_iwrite.3 \ mpi/man/man3/MPI_File_iwrite_at.3 \ + mpi/man/man3/MPI_File_iwrite_all.3 \ + mpi/man/man3/MPI_File_iwrite_at_all.3 \ mpi/man/man3/MPI_File_iwrite_shared.3 \ mpi/man/man3/MPI_File_open.3 \ mpi/man/man3/MPI_File_preallocate.3 \