This file contains the named document blocks for use in generating the 
documentation.  This is divided into several main blocks:
   Threads and interrups/signals
   Fortran
   Misc MPI (e.g., status null)
   Error classes

-----------------------------------------------------------------------------
Note that only one of ThreadSafe and SignalSafe may be used
/*N ThreadSafe
   Thread and Interrupt Safety:

   This routine is thread-safe.  This means that this routine may be
   safely used by multiple threads without the need for any user-provided 
   thread locks.  However, the routine is not interrupt safe.  Typically, 
   this is due to the use of memory allocation routines such as 'malloc'
   or other non-MPICH runtime routines that are themselves not interrupt-safe.
N*/
/*N SignalSafe
   Thread and Interrupt Safety:

   This routine is both thread- and interrupt-safe. 
   This means that this routine may safely be used by multiple threads and
   from within a signal handler.   
N*/
/*N NotThreadSafe
   Thread and Interrupt Safety:

   The user is responsible for ensuring that multiple threads do not try to
   update the same MPI object from different threads.  This routine should 
   not be used from within a signal handler.

   The MPI standard defined a thread-safe interface but this does not 
   mean that all routines may be called without any thread locks.  For
   example, two threads must not attempt to change the contents of the
   same 'MPI_Info' object concurrently.  The user is responsible in this
   case for using some mechanism, such as thread locks, to ensure that 
   only one thread at a time makes use of this routine.  
N*/

Most of the MPI objects are static enough that it isn't necessary to
lock around the routines (even though some ops require updates).  Info isn't
expected to be as robust (there was discussion on the MPI-Forum list
on this). 

/*N ThreadSafeInfoRead

   Thread and Interrupt Safety:

   This routine is thread and interrupt safe only if no MPI routine that 
   updates or frees the same 'MPI_Info' object may be called concurrently 
   with this routine.

   The MPI standard defined a thread-safe interface but this does not 
   mean that all routines may be called without any thread locks.  For
   example, two threads must not attempt to change the contents of the
   same 'MPI_Info' object concurrently.  The user is responsible in this
   case for using some mechanism, such as thread locks, to ensure that 
   only one thread at a time makes use of this routine.  
N*/

/*N ThreadSafeNoUpdate

    Thread and Interrupt Safety:

   This routine is thread and interrupt safe only if no MPI routine that 
   updates or frees the same MPI object may be called concurrently 
   with this routine.

   The MPI standard defined a thread-safe interface but this does not 
   mean that all routines may be called without any thread locks.  For
   example, two threads must not attempt to change the contents of the
   same 'MPI_Info' object concurrently.  The user is responsible in this
   case for using some mechanism, such as thread locks, to ensure that 
   only one thread at a time makes use of this routine.  

N*/
-----------------------------------------------------------------------------
/*N Fortran
Notes for Fortran:
All MPI routines in Fortran (except for 'MPI_WTIME' and 'MPI_WTICK') have 
an additional argument 'ierr' at the end of the argument list.  'ierr'
is an integer and has the same meaning as the return value of the routine 
in C.  In Fortran, MPI routines are subroutines, and are invoked with the 
'call' statement.  

All MPI objects (e.g., 'MPI_Datatype', 'MPI_Comm') are of type 'INTEGER'
in Fortran.  
N*/

Try this as an alias
/*N fortran
.N Fortran
N*/

/*N FortranStatus
 The 'status' argument must be declared as an array of size 'MPI_STATUS_SIZE',
 as in 'integer status(MPI_STATUS_SIZE)'.
N*/

/*N FortStatusArray
 The 'status' argument must be declared as an array of sise 'MPI_STATUS_SIZE',
 as in 'integer status(MPI_STATUS_SIZE,10)' (assuming no more than 10 
 requests are provided as input).
N*/

/*N FortranString

 The sizes of MPI strings in Fortran are one less than the sizes of that 
 string in C/C++ because the C/C++ versions provide room for the trailing
 null character required by C/C++.  For example, 'MPI_MAX_ERROR_STRING' is 
 'mpif.h' is one smaller than the same value in 'mpi.h'.  See the MPI
 standard, sections 2.6.2 and 4.12.9.

N*/


-----------------------------------------------------------------------------
/*N collops
Notes on collective operations:

The reduction functions ('MPI_Op') do not return an error value.  As a result,
if the functions detect an error, all they can do is either call 'MPI_Abort'
or silently skip the problem.  Thus, if you change the error handler from
'MPI_ERRORS_ARE_FATAL' to something else, for example, 'MPI_ERRORS_RETURN', 
then no error may be indicated.

The reason for this is the performance problems in ensuring that 
all collective routines return the same error value.
N*/

/*N waitstatus
 Notes on the MPI_Status argument:

 The 'MPI_ERROR' field of the status return is only set if 
 the return from the MPI routine is 'MPI_ERR_IN_STATUS'.  That error class
 is only returned by the routines that take an array of status arguments
 ('MPI_Testall', 'MPI_Testsome', 'MPI_Waitall', and 'MPI_Waitsome').  In
 all other cases, the value of the 'MPI_ERROR' field in the status is
 unchanged.  See section 3.2.5 in the MPI-1.1 specification for the 
 exact text.

 For send operations, the only use of status is for 'MPI_Test_cancelled' or
 in the case that there is an error in one of the four routines that 
 may return the error class 'MPI_ERR_IN_STATUS', in which case the 
 'MPI_ERROR' field of status will be set.  In that case, the value 
 will be set to 'MPI_SUCCESS' for any send or receive operation that completed
 successfully, or 'MPI_ERR_PENDING' for any operation which has neither
 failed nor completed.
N*/

-----------------------------------------------------------------------------
MPI-2 deprecated some routines (see 2.6.1)
/*N Deprecated
 Deprecated Function:
 The MPI-2 standard deprecated a number of routines because MPI-2 provides
 better versions.  This routine is one of those that was deprecated.  The
 routine may continue to be used, but new code should use the replacement
 routine.
N*/
-----------------------------------------------------------------------------
/*N Errhandler
    Error handlers:
    The MPI error handler for this routine is taken from 'MPI_COMM_WORLD'.
    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*/
-----------------------------------------------------------------------------

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

/*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_Comm_set_errhandler' (for communicators), 
 'MPI_File_set_errhandler' (for files), and 'MPI_Win_set_errhandler' (for
 RMA windows).  The MPI-1 routine 'MPI_Errhandler_set' may be used but
 its use is deprecated.  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; however, MPI implementations will attempt to continue whenever
 possible.

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.  Additionally, this error can
  occur if an uncommitted MPI_Datatype (see 'MPI_Type_commit') is used
  in a communication call.
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 or invalid 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 - Invalid 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_KEYVAL - Invalid 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 MPI_ERR_INFO
. MPI_ERR_INFO - Invalid Info 
N*/

/*N MPI_ERR_INFO_KEY  
. MPI_ERR_INFO_KEY - Invalid or null key string for info.
N*/

/*N MPI_ERR_INFO_VALUE
. MPI_ERR_INFO_VALUE - Invalid or null value string for info
N*/

/*N MPI_ERR_INFO_NOKEY 
. MPI_ERR_INFO_NOKEY - 
N*/

/*N MPI_ERR_NAME
. MPI_ERR_NAME - 
N*/

/*N MPI_ERR_NO_MEM
. MPI_ERR_NO_MEM - Insufficient memory available for allocation by 
  'MPI_Alloc_mem'
N*/

/*N MPI_ERR_NOT_SAME
. MPI_ERR_NOT_SAME - 
N*/

/*N MPI_ERR_PORT
. MPI_ERR_PORT -
N*/

/*N MPI_ERR_QUOTA
. MPI_ERR_QUOTA - 
N*/

/*N MPI_ERR_SERVICE
. MPI_ERR_SERVICE - 
N*/

/*N MPI_ERR_SPAWN
. MPI_ERR_SPAWN -
N*/

/*N MPI_ERR_UNSUPPORTED_OPERATION
. MPI_ERR_UNSUPPORTED_OPERATION - 
N*/

/*N MPI_ERR_WIN
. MPI_ERR_WIN - Invalid MPI window object
N*/

/*N MPI_ERR_BASE
. MPI_ERR_BASE - 
N*/

/*N MPI_ERR_LOCKTYPE
. MPI_ERR_LOCKTYPE - 
N*/

/*N MPI_ERR_RMA_CONFLICT
. MPI_ERR_RMA_CONFLICT - 
N*/

/*N MPI_ERR_RMA_SYNC
. MPI_ERR_RMA_SYNC -
N*/

/*N MPI_ERR_SIZE
. MPI_ERR_SIZE - 
N*/

/*N MPI_ERR_DISP
. MPI_ERR_DISP - 
N*/

/*N MPI_ERR_ASSERT
. MPI_ERR_ASSERT - 
N*/

/* MPI I/O Information */
/*N MPI_ERR_FILE
. MPI_ERR_FILE - Invalid MPI File handle
N*/

/*N MPI_ERR_ACCESS
. MPI_ERR_ACCESS -
N*/

/*N MPI_ERR_AMODE
. MPI_ERR_AMODE - 
N*/

/*N MPI_ERR_BAD_FILE
. MPI_ERR_BAD_FILE - 
N*/

/*N MPI_ERR_FILE_EXISTS
. MPI_ERR_FILE_EXISTS - 
N*/

/*N MPI_ERR_FILE_IN_USE
. MPI_ERR_FILE_IN_USE - 
N*/

/*N MPI_ERR_NO_SPACE
. MPI_ERR_NO_SPACE - 
N*/

/*N MPI_ERR_NO_SUCH_FILE
. MPI_ERR_NO_SUCH_FILE - 
N*/

/*N MPI_ERR_IO
. MPI_ERR_IO - 
N*/

/*N MPI_ERR_READ_ONLY
. MPI_ERR_READ_ONLY - 
N*/

/*N MPI_ERR_CONVERSION
. MPI_ERR_CONVERSION - 
N*/

/*N MPI_ERR_DUP_DATAREP
. MPI_ERR_DUP_DATAREP - 
N*/

/*N MPI_ERR_UNSUPPORTED_DATAREP
. MPI_ERR_UNSUPPORTED_DATAREP - 
N*/

/*N MPI_T_ERR_NOT_INITIALIZED
. MPI_T_ERR_NOT_INITIALIZED - The MPI tool information interface is not initialized.
N*/

/*N MPI_T_ERR_MEMORY
. MPI_T_ERR_MEMORY - The MPI tool information interface is out of memory.
N*/

/*N MPI_T_ERR_CANNOT_INIT
. MPI_T_ERR_CANNOT_INIT - The MPI tool information interface is not in the state to be initialized.
N*/

/*N MPI_T_ERR_INVALID_INDEX
. MPI_T_ERR_INVALID_INDEX - Index is invalid or has been deleted.
N*/

/*N MPI_T_ERR_INVALID_ITEM
. MPI_T_ERR_INVALID_ITEM - Item index queried is out of range.
N*/

/*N MPI_T_ERR_INVALID_NAME
. MPI_T_ERR_INVALID_NAME - The variable or category name is invalid
N*/

/*N MPI_T_ERR_INVALID_HANDLE
. MPI_T_ERR_INVALID_HANDLE - The handle is invalid.
N*/

/*N MPI_T_ERR_OUT_OF_HANDLES
. MPI_T_ERR_OUT_OF_HANDLES - No more handles available.
N*/

/*N MPI_T_ERR_OUT_OF_SESSIONS
. MPI_T_ERR_OUT_OF_SESSIONS - No more sessions available.
N*/

/*N MPI_T_ERR_INVALID_SESSION
. MPI_T_ERR_INVALID_SESSION - Session argument is not valid.
N*/

/*N MPI_T_ERR_CVAR_SET_NOT_NOW
. MPI_T_ERR_CVAR_SET_NOT_NOW - The control variable can not be set at this moment.
N*/

/*N MPI_T_ERR_CVAR_SET_NEVER
. MPI_T_ERR_CVAR_SET_NEVER -  The control variable can not be set until end of execution.
N*/

/*N MPI_T_ERR_PVAR_NO_STARTSTOP
. MPI_T_ERR_PVAR_NO_STARTSTOP - The performance variable can not be started or stopped.
N*/

/*N MPI_T_ERR_PVAR_NO_WRITE
. MPI_T_ERR_PVAR_NO_WRITE - The performance variable can not be written or reset.
N*/

/*N MPI_T_ERR_PVAR_NO_ATOMIC
. MPI_T_ERR_PVAR_NO_ATOMIC - The performance variable can not be read/write atomically.
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*/

/*N COMMNULL
 Because MPI specifies that null objects (e.g., 'MPI_COMM_NULL') are invalid
 as input to MPI routines unless otherwise specified, using 'MPI_COMM_NULL'
 as input to this routine is an error.
N*/

/*N AttrErrReturn
 
 Return value from attribute callbacks:
 The MPI-2 versions of the attribute callbacks should return either 
 'MPI_SUCCESS' on success or a valid MPI error code or class on failure.
 The MPI standard is ambiguous on this point, but as MPI-2 provides
 the routines 'MPI_Add_error_class' and 'MPI_Add_error_code' that allow the
 user to define and use MPI error codes and classes.
N*/