-*- text -*-
This file contains definitions of the MPI error CLASSES for inclusion in the
man pages.  Use .N err_name

/*N WEB
More Information:

For more information, please see the official MPI Forum web site,
which contains the text of both the MPI-1 and MPI-2 standards.  These
documents contain detailed information about each MPI function (most
of which is not duplicated in these man pages).

'http://www.mpi-forum.org/'
N*/

/*N ACK
More Information:

For more information, please see the official MPI Forum web site,
which contains the text of both the MPI-1 and MPI-2 standards.  These
documents contain detailed information about each MPI function (most
of which is not duplicated in these man pages).

'http://www.mpi-forum.org/'

Acknowledgements:

The LAM Team would like the thank the MPICH Team for the handy program
to generate man pages ("doctext" from
'ftp://ftp.mcs.anl.gov/pub/sowing/sowing.tar.gz'), the initial
formatting, and some initial text for most of the MPI-1 man pages.
N*/

/*N Wrapper 
Notes:

This function is deprecated.  It has been replaced with an MPI-2
function (see the "See also" section, below), which provides the same
functionality.  This function is (or effectively is) a wrapper to the
replacement function, anyway.  User programs should use the MPI-2
replacement function instead of this function.

Some functions are deprecated because their names did not conform to
the stricter naming conventions of MPI-2; others are deprecated
because they have been replaced with more flexible functionality.

.seealso
N*/

/*N IMPI_YES
Usage with IMPI Extensions:

This function has had the IMPI extensions implemented.  It is legal to
call this function on IMPI communicators.
N*/

/*N IMPI
Usage with IMPI Extensions:

LAM/MPI does not yet support invoking this function on a communicator
that contains ranks that are non-local IMPI procs.
N*/

/*N IMPI_MPI2
Usage with IMPI Extensions:

The IMPI standard only supports MPI-1 functions.  Hence, this function
is currently not designed to operate within an IMPI job.
N*/

/*N CONVERSION_FUNCTIONS
Errors:

This function does not return the normal 'MPI_SUCCESS' integer value
upon success.  Instead, it returns a handle to the converted object.
If an error occurs, the appropriate NULL handle will be returned.
N*/

/*N Errors
Errors:

 If an error occurs in an MPI function, the current MPI error handler
 is called to handle it.  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 (in C and Fortran; this error handler is
 less useful in with the C++ MPI bindings.  The predefined error
 handler 'MPI::ERRORS_THROW_EXCEPTIONS' should be used in C++ if the
 error value needs to be recovered).  Note that MPI does `not`
 guarantee that an MPI program can continue past an error.

 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.  The C++ bindings for MPI do not return error
 values; instead, error values are communicated by throwing exceptions
 of type 'MPI::Exception' (but not by default).  Exceptions are only
 thrown if the error value is not 'MPI::SUCCESS'.

 Note that if the 'MPI::ERRORS_RETURN' handler is set in C++, while
 MPI functions will return upon an error, there will be no way to
 recover what the actual error value was.
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_FLAGS
. MPI_ERR_FLAGS - Mismatch of run-time flags.  For example, an MPI
  process that is running in lamd mode cannot spawn or be connected to a
  process that is running in c2c mode.
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_WIN
. MPI_ERR_WIN - Invalid window.  A common error is to use a
  null window in a call.
N*/

/*N MPI_ERR_INTERCOMM
. MPI_ERR_COMM - Invalid communicator.  LAM/MPI does not yet support
  invoking collectives on intercommunicators.
N*/

/*N MPI_ERR_IMPI
. MPI_ERR_COMM - A communicator that contains some non-local IMPI
  procs was used for some function which has not yet had the IMPI
  extensions implemented yet.  For example, most collectives on IMPI
  communicators have not been implemented yet.
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'.  Additionally, only
  certain datatypes are alloed with given predefined operations.  See
  MPI-1, section 4.9.2.
N*/

/*N MPI_ERR_TYPENOTSUP
. MPI_ERR_TYPENOTSUP - Type not supported for this operation.  This
  typically applies to either reduction operations (for which only a
  limited combination of datatypes and operations are defined, see
  MPI-1, section 4.9.2) or one-sided operations where the actions on
  specific datatpyes have not been implemented yet.
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.  This is typically a NULL
  pointer or other such error.
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 the LAM mailing list (see
  'http://www.lam-mpi.org/contact.php')
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 LAM/MPI implementation.
N*/

/*N MPI_ERR_SPAWN
. MPI_ERR_SPAWN - Spawn error; one or more of the applications
  attempting to be launched failed.  Check the returned error code
  array.  
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 the LAM mailing list (see
   'http://www.lam-mpi.org/contact.php'). 
N*/

/*N MPI_ERR_EXHAUSTED
.  MPI_ERR_OTHER - This error is returned when some part of the
   LAM/MPI implementation is unable to acquire memory.
N*/

/*N MPI_ERR_EPOCH
.  MPI_ERR_EPOCH - This error indicates than an operation has been
   attempted on a "closed" window. Certain one-sided operations can
   only be performed on windows whose epoch has been started with
   MPI_Win_start.
N*/

/*N MPI_ERR_IN_STATUS

. MPI_ERR_IN_STATUS - The actual error value is in the 'MPI_Status'
  argument.  Note that if this error occurs and 'MPI_STATUS_IGNORE' or
  'MPI_STATUSES_IGNORE' was used as the status argument, the actual
  error will be lost. 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)?  LAM/MPI 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,
  'MPI_REQUEST_NULL', 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_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 MPI_ERR_INFO_KEY
. MPI_INFO_KEY - This error class is associated with an error code
  that indicates that a null key, empty key, or key that was longer
  than 'MPI_MAX_INFO_KEY' characters was passed as an argument to an
  MPI function where it was not allowed.
N*/

/*N MPI_ERR_INFO_VALUE
. MPI_INFO_VALUE - This error class is associated with an error code
  that indicates that a null key, empty key, or key that was longer
  than 'MPI_MAX_INFO_VAL' characters was passed as an argument to an
  MPI function where it was not allowed.
N*/

/*N MPI_ERR_INFO_NOKEY
. MPI_INFO_NOKEY - This error class is associated with an error code
  that indicates that a key that was looked up on an 'MPI_Info' object
  and was not found.
N*/

/*N MPI_ERR_NO_MEM
. MPI_ERR_NO_MEM - This error class is associated with an error code
  that indicates that free space is exhausted.
N*/

/*N MPI_ERR_NAME
. MPI_ERR_NAME - This error class is associated with an error code
  that indicates that the name looked up has not been published, and
  was therefore not found.
N*/

/*N MPI_ERR_SERVICE
. MPI_ERR_SERVICE - This error class is associated with an error code
  that indicates that there was a problem with the service name that
  was used.  Depending on the context, this can indicate that the
  service name was already published or that the service name was not
  yet published.
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*/