This file contains definitions of the MPI error CLASSES for inclusion in the
man pages.  Use .N err name

/*N errhandler

    Error handlers:
    For MPI routines that do not have an obvious communicator, file, or
    window object, the MPI standard specifies that the error handler 
    attached to 'MPI_COMM_WORLD' be used.
N*/

/*N Errors
Errors:

 All MPI routines (except 'MPI_Wtime' and 'MPI_Wtick') return an error value; 
 C routines as the value of the function and Fortran routines in the last 
 argument.  Before the value is returned, the current MPI error handler is
 called.  By default, this error handler aborts the MPI job.  The error handler
 may be changed with 'MPI_Errhandler_set'; the predefined error handler 
 'MPI_ERRORS_RETURN' may be used to cause error values to be returned.
 Note that MPI does `not` guarentee that an MPI program can continue past
 an error.

N*/
/*N MPI_SUCCESS
. MPI_SUCCESS - No error; MPI routine completed successfully.
N*/
/*N MPI_ERR_BUFFER
. MPI_ERR_BUFFER - Invalid buffer pointer.  Usually a null buffer where
  one is not valid.
N*/
/*N MPI_ERR_COUNT
. MPI_ERR_COUNT - Invalid count argument.  Count arguments must be 
  non-negative; a count of zero is often valid.
N*/
/*N MPI_ERR_TYPE
. MPI_ERR_TYPE - Invalid datatype argument.  May be an uncommitted 
  MPI_Datatype (see 'MPI_Type_commit').
N*/
/*N MPI_ERR_TAG
.  MPI_ERR_TAG - Invalid tag argument.  Tags must be non-negative; tags
   in a receive ('MPI_Recv', 'MPI_Irecv', 'MPI_Sendrecv', etc.) may
   also be 'MPI_ANY_TAG'.  The largest tag value is available through the 
   the attribute 'MPI_TAG_UB'.
N*/
/*N MPI_ERR_COMM
. MPI_ERR_COMM - Invalid communicator.  A common error is to use a null
  communicator in a call (not even allowed in 'MPI_Comm_rank').
N*/
/*N MPI_ERR_RANK
. MPI_ERR_RANK - Invalid source or destination rank.  Ranks must be between
  zero and the size of the communicator minus one; ranks in a receive
  ('MPI_Recv', 'MPI_Irecv', 'MPI_Sendrecv', etc.) may also be 'MPI_ANY_SOURCE'.
N*/
/*N MPI_ERR_ROOT
. MPI_ERR_ROOT - Invalid root.  The root must be specified as a rank in the
  communicator.  Ranks must be between zero and the size of the communicator 
  minus one.
N*/
/*N MPI_ERR_GROUP
. MPI_ERR_GROUP - Null group passed to function.  
N*/
/*N MPI_ERR_OP
. MPI_ERR_OP - Invalid operation.  MPI operations (objects of type 'MPI_Op')
  must either be one of the predefined operations (e.g., 'MPI_SUM') or
  created with 'MPI_Op_create'.
N*/
/*N MPI_ERR_TOPOLOGY
. MPI_ERR_TOPOLOGY - Invalid topology.  Either there is no topology 
  associated with this communicator, or it is not the correct type (e.g.,
  'MPI_CART' when expecting 'MPI_GRAPH').
N*/
/*N MPI_ERR_DIMS
. MPI_ERR_DIMS - Illegal dimension argument.  A dimension argument
  is null or its length is less than or equal to zero.
N*/
/*N MPI_ERR_ARG
. MPI_ERR_ARG - Invalid argument.  Some argument is invalid and is not
  identified by a specific error class (e.g., 'MPI_ERR_RANK').
N*/
/*N MPI_ERR_PERM_OP
. MPI_ERR_ARG - Invalid argument; the error code associated with this
  error indicates an attempt to free an MPI permanent operation (e.g., 
  'MPI_SUM').
*N/
/*N MPI_ERR_PERM_KEY
. MPI_ERR_ARG - Invalid argument; the error code associated with this
  error indicates an attempt to free or chnage an MPI permanent keyval (e.g., 
  'MPI_TAG_UB').
*N/
/*N MPI_ERR_UNKNOWN
. MPI_ERR_UNKNOWN - Unknown error.  You should never see this.  If you
  do, report it to 'mpi-bugs@mcs.anl.gov'.
N*/
/*N MPI_ERR_TRUNCATE
. MPI_ERR_TRUNCATE - Message truncated on receive.  The buffer size specified
  was too small for the received message.  This is a recoverable error in
  the MPICH implementation.
N*/
/*N MPI_ERR_OTHER
. MPI_ERR_OTHER - Other error; use 'MPI_Error_string' to get more information
  about this error code. 
N*/
/*N MPI_ERR_KEYVAL
. MPI_ERR_OTHER - Other error; the error code associated with this error 
  indicates an attempt to use an invalue keyval.
N*/
/*N MPI_ERR_INTERN
.  MPI_ERR_INTERN - An internal error has been detected.  This is fatal.
   Please send a bug report to 'mpi-bugs@mcs.anl.gov'.
N*/
/*N MPI_ERR_EXHAUSTED
.   MPI_ERR_INTERN - This error is returned when some part of the MPICH 
    implementation is unable to acquire memory.  
N*/
/*N MPI_ERR_IN_STATUS
. MPI_ERR_IN_STATUS - The actual error value is in the 'MPI_Status' argument.
  This error class is returned only from the multiple-completion routines
  ('MPI_Testall', 'MPI_Testany', 'MPI_Testsome', 'MPI_Waitall', 'MPI_Waitany',
  and 'MPI_Waitsome').  The field 'MPI_ERROR' in the status argument
  contains the error value or 'MPI_SUCCESS' (no error and complete) or
  'MPI_ERR_PENDING' to indicate that the request has not completed.
  
  The MPI Standard does not specify what the result of the multiple 
  completion routines is when an error occurs.  For example, in an 
  'MPI_WAITALL', does the routine wait for all requests to either fail or
  complete, or does it return immediately (with the MPI definition of 
  immediately, which means independent of actions of other MPI processes)?
  MPICH has chosen to make the return immediate (alternately, local in MPI 
  terms), and to use the error class 'MPI_ERR_PENDING' (introduced in MPI 1.1)
  to indicate which requests have not completed.  In most cases, only
  one request with an error will be detected in each call to an MPI routine
  that tests multiple requests.  The requests that have not been processed
  (because an error occured in one of the requests) will have their
  'MPI_ERROR' field marked with 'MPI_ERR_PENDING'.
N*/
/*N MPI_ERR_PENDING
. MPI_ERR_PENDING - Pending request (not an error).  See 'MPI_ERR_IN_STATUS'. 
  This value indicates that the request is not complete nor has a encountered
  a detected error.  
N*/
/*N MPI_ERR_REQUEST
. MPI_ERR_REQUEST - Invalid 'MPI_Request'.  Either null or, in the case of a
  'MPI_Start' or 'MPI_Startall', not a persistent request.
N*/
/*N MPI_ERR_BUFFER_ALIAS
.   MPI_ERR_BUFFER - This error class is associcated with an error code that
    indicates that two buffer arguments are `aliased`; that is, the 
    describe overlapping storage (often the exact same storage).  This
    is prohibited in MPI (because it is prohibited by the Fortran 
    standard, and rather than have a separate case for C and Fortran, the
    MPI Forum adopted the more restrictive requirements of Fortran).
N*/

/*N MPI_ERR_PERM_KEY
. MPI_ERR_ARG - This error class is associated with an error code that 
  indicates that an attempt was made to free one of the permanent keys.
N*/

/*N MPI_ERR_PERM_GROUP
. MPI_ERR_ARG - This error class is associated with an error code that 
  indicates that an attempt was made to free one of the permanent groups.
N*/

/*N MPI_ERR_INIT
. MPI_ERR_OTHER - This error class is associated with an error code that 
  indicates that an attempt was made to call 'MPI_INIT' a second time.
  'MPI_INIT' may only be called once in a program.
N*/

/*N NULL
Null Handles:
The MPI 1.1 specification, in the section on opaque objects, explicitly
disallows freeing a null communicator.  The text from the standard is:
.vb
 A null handle argument is an erroneous IN argument in MPI calls, unless an
 exception is explicitly stated in the text that defines the function. Such
 exception is allowed for handles to request objects in Wait and Test calls
 (sections Communication Completion and Multiple Completions ). Otherwise, a
 null handle can only be passed to a function that allocates a new object and
 returns a reference to it in the handle.
.ve
N*/
