MPI_ERRHANDLER_CREATE(3)			     Open MPI				  MPI_ERRHANDLER_CREATE(3)

MPI_Errhandler_create	—  Creates  an	MPI-style  error  handler  —  this  routine  is	 deprecated  in	 favor	of
MPI_Comm_create_errhandler <#mpi-comm-create-errhandler>.

SYNTAX
   C Syntax
	  #include <mpi.h>

	  int MPI_Errhandler_create(MPI_Handler_function *function,
	       MPI_Errhandler *errhandler)

   Fortran Syntax
	  USE MPI
	  ! or the older form: INCLUDE 'mpif.h'

	  MPI_ERRHANDLER_CREATE(FUNCTION, ERRHANDLER, IERROR)
	       EXTERNAL	       FUNCTION
	       INTEGER ERRHANDLER, IERROR

INPUT PARAMETER
       • function: User-defined error handling procedure.

OUTPUT PARAMETERS
       • errhandler: MPI error handler (handle).

       • ierror: Fortran only: Error status (integer).

DESCRIPTION
       Note that use of this  routine  is  deprecated  as  of  MPI-2.  Please  use  MPI_Comm_create_errhandler	<#
       mpi-comm-create-errhandler> instead.

       Registers the user routine function for use as an MPI error handler.  Returns in errhandler a handle to the
       registered error handler.

       In  the	C language, the user routine should be a C function of type MPI_Handler_function, which is defined
       as

	  typedef void (MPI_Handler_function)(MPI_Comm *, int *, ...);

       The first argument is the communicator in use. The second is the error code  to	be  returned  by  the  MPI
       routine	that  raised the error. If the routine would have returned MPI_ERR_IN_STATUS, it is the error code
       returned in the status for the request that caused the error handler to be invoked. The remaining arguments
       are stdargs arguments whose number  and	meaning	 is  implementation-dependent.	An  implementation  should
       clearly document these arguments. Addresses are used so that the handler may be written in Fortran.

NOTE
       The  MPI Standard <https://www.mpi-forum.org/docs/> states that an implementation may make the output value
       (errhandler)  simply  the  address  of  the  function.  However,	 the  action  of  MPI_Errhandler_free	<#
       mpi-errhandler-free>  makes  this  impossible,  since  it  is  required to set the value of the argument to
       MPI_ERRHANDLER_NULL. In addition, the actual error handler must remain until all communicators that use	it
       are freed.

ERRORS
       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>/MPI_Init_thread <#mpi-init-thread>,
       after MPI_Finalize <#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 <#
       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  <#mpi-comm-spawn>/MPI_Comm_spawn_multiple	<#
       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.

       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 <#mpi-abort> was called on that communicator. If called
	 on  a window or file, acts as if MPI_Abort <#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 by calling:

       • MPI_Comm_create_errhandler	<#mpi-comm-create-errhandler>	  then	   MPI_Comm_set_errhandler	<#
	 mpi-comm-set-errhandler>

       • MPI_File_create_errhandler	 <#mpi-file-create-errhandler>	   then	    MPI_File_set_errhandler	<#
	 mpi-file-set-errhandler>

       • MPI_Session_create_errhandler	 <#mpi-session-create-errhandler>   then   MPI_Session_set_errhandler	<#
	 mpi-session-set-errhandler> or at MPI_Session_init <#mpi-session-init>

       • MPI_Win_create_errhandler	<#mpi-win-create-errhandler>	  then	    MPI_Win_set_errhandler	<#
	 mpi-win-set-errhandler>

       Note that MPI does not guarantee that an MPI program can continue past an error.

       See the MPI man page <#open-mpi> for a full list of MPI error codes <#open-mpi-errors>.

       See the Error Handling section of the MPI-3.1 standard for more information.

       See also:

	  • MPI_Comm_create_errhandler <#mpi-comm-create-errhandler>

	  • MPI_Comm_get_errhandler <#mpi-comm-get-errhandler>

	  • MPI_Comm_set_errhandler <#mpi-comm-set-errhandler>

Copyright
       2003-2026, The Open MPI Community

						   Mar 05, 2026				  MPI_ERRHANDLER_CREATE(3)
