Merge pull request open-mpi#11015 from drwootton/manpage_error_text

Update man pages to clarify MPI-4 error handlers

Author: jjhursey

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`