Update man pages to describe error handling in MPI-4

All man pages use a common text file to describe error handling with additional
text for some MPI_Test*, MPI_Wait, and MPI_Grequest* pages.

Fix review comments

Signed-off-by: David Wootton <[email protected]>

Author: David Wootton

docs/man-openmpi/man3/ERRORS.rst

@@ -0,0 +1,53 @@
+Almost all MPI routines return an error value; C routines as the return result
+of the function and Fortran routines in the last argument.
+
+Before the error value is returned, the current MPI error handler associated
+with the communication object (e.g., communicator, window, file) is called.
+If no communication object is associated with the MPI call, then the call is
+considered attached to MPI_COMM_SELF and will call the associated MPI error
+handler. When MPI_COMM_SELF is not initialized (i.e., before
+MPI_INIT / MPI_INIT_THREAD, after MPI_FINALIZE, or when using the Sessions
+Model exclusively) the error raises the initial error handler. The initial
+error handler can be changed by calling MPI_COMM_SET_ERRHANDLER on
+MPI_COMM_SELF when using the World model, or the mpi_initial_errhandler CLI
+argument to mpiexec or info key to MPI_COMM_SPAWN[_MULTIPLE].
+If no other appropriate error handler has been set, then the MPI_ERRORS_RETURN
+error handler is called for MPI I/O functions and the MPI_ERRORS_ABORT error
+handler is called for all other MPI functions.
+
+In the sessions model, the error handler can be set during MPI_Session_init.
+
+Open MPI includes three predefined error handlers that can be used::
+
+ MPI_ERRORS_ARE_FATAL: Causes the program to abort all connected MPI processes.
+ MPI_ERRORS_ABORT:     An error handler that can be invoked on a communicator,
+                       window, file, or session. When called on a communicator, it
+                       acts as if MPI_ABORT was called on that communicator. If
+                       called on a window or file, acts as if MPI_ABORT was called
+                       on a communicator containing the group of processes in the
+                       corresponding window or file. If called on a session,
+                       aborts only the local process.
+ MPI_ERRORS_RETURN:    Returns an error code to the application.
+
+MPI applications can also implement their own error handlers.
+
+Custom MPI error handlers can be created by calling:
+:ref:`MPI_Comm_create_errhandler(3) <MPI_Comm_create_errhandler>`
+:ref:`MPI_File_create_errhandler(3) <MPI_File_create_errhandler>`
+:ref:`MPI_Session_create_errhandler(3) <MPI_Session_create_errhandler>`
+:ref:`MPI_Win_create_errhandler(3) <MPI_Win_create_errhandler>`
+
+Predefined and custom error handlers can be set by calling:
+:ref:`MPI_Comm_set_errhandler(3) <MPI_Comm_set_errhandler>`
+:ref:`MPI_File_set_errhandler(3) <MPI_File_set_errhandler>`
+:ref:`MPI_Session_set_errhandler(3) <MPI_Session_set_errhandler>`
+:ref:`MPI_Win_set_errhandler(3) <MPI_Win_set_errhandler>`
+
+Note that MPI does not guarantee that an MPI program can continue past
+an error.
+
+See the MPI man page for a full list of MPI error codes.
+
+See the Error Handling section of the MPI-|mpi_standard_version| standard for
+more information.
+

docs/man-openmpi/man3/MPI_Abort.3.rst

@@ -74,13 +74,4 @@ Note: All associated processes are sent a SIGTERM.
 
 ERRORS
 ------
-
-Almost all MPI routines return an error value; C routines as the value
-of the function and Fortran routines in the last argument.
-
-Before the error value is returned, the current MPI error handler is
-called. By default, this error handler aborts the MPI job, except for
-I/O function errors. The error handler may be changed with
-:ref:`MPI_Comm_set_errhandler`; 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.
+.. include:: ./ERRORS.rst

docs/man-openmpi/man3/MPI_Accumulate.3.rst

@@ -169,16 +169,7 @@ arguments in the call to the :ref:`MPI_Accumulate` function.
 ERRORS
 ------
 
-Almost all MPI routines return an error value; C routines as the value
-of the function and Fortran routines in the last argument.
-
-Before the error value is returned, the current MPI error handler is
-called. By default, this error handler aborts the MPI job, except for
-I/O function errors. The error handler may be changed with
-:ref:`MPI_Comm_set_errhandler`; 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.
-
+.. include:: ./ERRORS.rst
 
 .. seealso::
    :ref:`MPI_Put` :ref:`MPI_Get_accumulate` :ref:`MPI_Reduce`

docs/man-openmpi/man3/MPI_Add_error_class.3.rst

@@ -80,16 +80,7 @@ The value returned is always greater than or equal to MPI_ERR_LASTCODE.
 ERRORS
 ------
 
-Almost all MPI routines return an error value; C routines as the value
-of the function and Fortran routines in the last argument.
-
-Before the error value is returned, the current MPI error handler is
-called. By default, this error handler aborts the MPI job, except for
-I/O function errors. The error handler may be changed with
-:ref:`MPI_Comm_set_errhandler`; 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.
-
+.. include:: ./ERRORS.rst
 
 .. seealso::
    :ref:`MPI_Add_error_code` :ref:`MPI_Add_error_string` :ref:`MPI_Error_class` :ref:`MPI_Error_string`

docs/man-openmpi/man3/MPI_Add_error_code.3.rst

@@ -75,16 +75,7 @@ The value returned is always greater than or equal to MPI_ERR_LASTCODE.
 ERRORS
 ------
 
-Almost all MPI routines return an error value; C routines as the value
-of the function and Fortran routines in the last argument.
-
-Before the error value is returned, the current MPI error handler is
-called. By default, this error handler aborts the MPI job, except for
-I/O function errors. The error handler may be changed with
-:ref:`MPI_Comm_set_errhandler`; 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.
-
+.. include:: ./ERRORS.rst
 
 .. seealso::
    :ref:`MPI_Add_error_class` :ref:`MPI_Error_class`

docs/man-openmpi/man3/MPI_Add_error_string.3.rst

@@ -72,16 +72,7 @@ code or class with a value not greater than MPI_LAST_ERRCODE).
 ERRORS
 ------
 
-Almost all MPI routines return an error value; C routines as the value
-of the function and Fortran routines in the last argument.
-
-Before the error value is returned, the current MPI error handler is
-called. By default, this error handler aborts the MPI job, except for
-I/O function errors. The error handler may be changed with
-:ref:`MPI_Comm_set_errhandler`; 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.
-
+.. include:: ./ERRORS.rst
 
 .. seealso::
    :ref:`MPI_Add_error_class` :ref:`MPI_Add_error_code` :ref:`MPI_Error_class` :ref:`MPI_Error_string`

docs/man-openmpi/man3/MPI_Address.3.rst

@@ -89,16 +89,7 @@ variables guarantees portability to such machines as well.
 ERRORS
 ------
 
-Almost all MPI routines return an error value; C routines as the value
-of the function and Fortran routines in the last argument.
-
-Before the error value is returned, the current MPI error handler is
-called. By default, this error handler aborts the MPI job, except for
-I/O function errors. The error handler may be changed with
-:ref:`MPI_Comm_set_errhandler`; 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.
-
+.. include:: ./ERRORS.rst
 
 .. seealso::
    :ref:`MPI_Get_address`

docs/man-openmpi/man3/MPI_Allgather.3.rst

@@ -199,16 +199,7 @@ in the second group. You can move data in only one direction by giving
 ERRORS
 ------
 
-Almost all MPI routines return an error value; C routines as the value
-of the function and Fortran routines in the last argument.
-
-Before the error value is returned, the current MPI error handler is
-called. By default, this error handler aborts the MPI job, except for
-I/O function errors. The error handler may be changed with
-:ref:`MPI_Comm_set_errhandler`; 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.
-
+.. include:: ./ERRORS.rst
 
 .. seealso::
    :ref:`MPI_Allgatherv` :ref:`MPI_Gather`

docs/man-openmpi/man3/MPI_Allgatherv.3.rst

@@ -186,16 +186,7 @@ operation must exhibit symmetric, full-duplex behavior.
 ERRORS
 ------
 
-Almost all MPI routines return an error value; C routines as the value
-of the function and Fortran routines in the last argument.
-
-Before the error value is returned, the current MPI error handler is
-called. By default, this error handler aborts the MPI job, except for
-I/O function errors. The error handler may be changed with
-:ref:`MPI_Comm_set_errhandler`; 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.
-
+.. include:: ./ERRORS.rst
 
 .. seealso::
    :ref:`MPI_Gatherv` :ref:`MPI_Allgather`

docs/man-openmpi/man3/MPI_Alloc_mem.3.rst

@@ -112,16 +112,7 @@ User's Guide and are supported by many Fortran compilers. For example,
 ERRORS
 ------
 
-Almost all MPI routines return an error value; C routines as the value
-of the function and Fortran routines in the last argument.
-
-Before the error value is returned, the current MPI error handler is
-called. By default, this error handler aborts the MPI job, except for
-I/O function errors. The error handler may be changed with
-:ref:`MPI_Comm_set_errhandler`; 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.
-
+.. include:: ./ERRORS.rst
 
 .. seealso::
    :ref:`MPI_Free_mem`

docs/man-openmpi/man3/MPI_Allreduce.3.rst

@@ -209,12 +209,4 @@ MPI_ERRORS_RETURN , then no error may be indicated.
 ERRORS
 ------
 
-Almost all MPI routines return an error value; C routines as the value
-of the function and Fortran routines in the last argument.
-
-Before the error value is returned, the current MPI error handler is
-called. By default, this error handler aborts the MPI job, except for
-I/O function errors. The error handler may be changed with
-:ref:`MPI_Comm_set_errhandler`; 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.
+.. include:: ./ERRORS.rst

docs/man-openmpi/man3/MPI_Alltoall.3.rst

@@ -193,16 +193,7 @@ functionality to allow the exchange of data with different datatypes.
 ERRORS
 ------
 
-Almost all MPI routines return an error value; C routines as the value
-of the function and Fortran routines in the last argument.
-
-Before the error value is returned, the current MPI error handler is
-called. By default, this error handler aborts the MPI job, except for
-I/O function errors. The error handler may be changed with
-:ref:`MPI_Comm_set_errhandler`; 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.
-
+.. include:: ./ERRORS.rst
 
 .. seealso::
    :ref:`MPI_Alltoallv` :ref:`MPI_Alltoallw`

docs/man-openmpi/man3/MPI_Alltoallv.3.rst

@@ -213,16 +213,7 @@ where these offsets are measured in 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.
-
-Before the error value is returned, the current MPI error handler is
-called. By default, this error handler aborts the MPI job, except for
-I/O function errors. The error handler may be changed with
-:ref:`MPI_Comm_set_errhandler`; 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.
-
+.. include:: ./ERRORS.rst
 
 .. seealso::
    :ref:`MPI_Alltoall` :ref:`MPI_Alltoallw`

docs/man-openmpi/man3/MPI_Alltoallw.3.rst

@@ -217,16 +217,7 @@ this to :ref:`MPI_Alltoallv`, where these offsets are measured in units of
 ERRORS
 ------
 
-Almost all MPI routines return an error value; C routines as the value
-of the function and Fortran routines in the last argument.
-
-Before the error value is returned, the current MPI error handler is
-called. By default, this error handler aborts the MPI job, except for
-I/O function errors. The error handler may be changed with
-:ref:`MPI_Comm_set_errhandler`; 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.
-
+.. include:: ./ERRORS.rst
 
 .. seealso::
    :ref:`MPI_Alltoall` :ref:`MPI_Alltoallv`

docs/man-openmpi/man3/MPI_Attr_delete.3.rst

@@ -75,16 +75,7 @@ being invoked.
 ERRORS
 ------
 
-Almost all MPI routines return an error value; C routines as the value
-of the function and Fortran routines in the last argument.
-
-Before the error value is returned, the current MPI error handler is
-called. By default, this error handler aborts the MPI job, except for
-I/O function errors. The error handler may be changed with
-:ref:`MPI_Comm_set_errhandler`; 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.
-
+.. include:: ./ERRORS.rst
 
 .. seealso::
    :ref:`MPI_Comm_delete_attr`

docs/man-openmpi/man3/MPI_Attr_get.3.rst

@@ -64,16 +64,7 @@ an erroneous key value.
 ERRORS
 ------
 
-Almost all MPI routines return an error value; C routines as the value
-of the function and Fortran routines in the last argument.
-
-Before the error value is returned, the current MPI error handler is
-called. By default, this error handler aborts the MPI job, except for
-I/O function errors. The error handler may be changed with
-:ref:`MPI_Comm_set_errhandler`; 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.
-
+.. include:: ./ERRORS.rst
 
 .. seealso::
    :ref:`MPI_Comm_get_attr`

docs/man-openmpi/man3/MPI_Attr_put.3.rst

@@ -80,16 +80,7 @@ the corresponding keyval was created) will be called.
 ERRORS
 ------
 
-Almost all MPI routines return an error value; C routines as the value
-of the function and Fortran routines in the last argument.
-
-Before the error value is returned, the current MPI error handler is
-called. By default, this error handler aborts the MPI job, except for
-I/O function errors. The error handler may be changed with
-:ref:`MPI_Comm_set_errhandler`; 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.
-
+.. include:: ./ERRORS.rst
 
 .. seealso::
    :ref:`MPI_Comm_set_attr`

docs/man-openmpi/man3/MPI_Barrier.3.rst

@@ -84,14 +84,6 @@ have entered the barrier.
 Errors
 ------
 
-Almost all MPI routines return an error value; C routines as the value
-of the function and Fortran routines in the last argument. Before the
-error value is returned, the current MPI error handler is called. By
-default, this error handler aborts the MPI job, except for I/O function
-errors. The error handler may be changed with :ref:`MPI_Comm_set_errhandler`;
-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.
-
+.. include:: ./ERRORS.rst
 
 .. seealso:: :ref:`MPI_Bcast`

docs/man-openmpi/man3/MPI_Bcast.3.rst

@@ -127,14 +127,4 @@ This function does not support the in-place option.
 
 ERRORS
 ------
-
-Almost all MPI routines return an error value; C routines as the value
-of the function and Fortran routines in the last argument.
-
-Before the error value is returned, the current MPI error handler is
-called. By default, this error handler aborts the MPI job, except for
-I/O function errors. The error handler may be changed with
-:ref:`MPI_Comm_set_errhandler`; 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.
+.. include:: ./ERRORS.rst

docs/man-openmpi/man3/MPI_Bsend.3.rst

@@ -97,14 +97,4 @@ delivered.)
 Errors
 ------
 
-Almost all MPI routines return an error value; C routines as the value;
-C routines as the value of the function and Fortran routines in the last
-argument.
-
-Before the error value is returned, the current MPI error handler is
-called. By default, this error handler aborts the MPI job, except for
-I/O function errors. The error handler may be changed with
-:ref:`MPI_Comm_set_errhandler`; 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.
+.. include:: ./ERRORS.rst

docs/man-openmpi/man3/MPI_Bsend_init.3.rst

@@ -76,15 +76,6 @@ initiated by the function :ref:`MPI_Start`.
 Errors
 ------
 
-Almost all MPI routines return an error value; C routines as the value
-of the function and Fortran routines in the last argument.
-
-Before the error value is returned, the current MPI error handler is
-called. By default, this error handler aborts the MPI job, except for
-I/O function errors. The error handler may be changed with
-:ref:`MPI_Comm_set_errhandler`; 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.
-
+.. include:: ./ERRORS.rst
 
 .. seealso:: :ref:`MPI_Send_init` :ref:`MPI_Start`