.. _mpi_comm_set_name:


MPI_Comm_set_name
=================

.. include_body

:ref:`MPI_Comm_set_name` |mdash| Associates a name with a communicator.

.. The following file was automatically generated
.. include:: ./bindings/mpi_comm_set_name.rst

INPUT/OUTPUT PARAMETER
----------------------
* ``comm``: Communicator whose identifier is to be set (handle).

INPUT PARAMETER
---------------
* ``comm_name``: Character string to be used as the identifier for the communicator (string).

OUTPUT PARAMETER
----------------
* ``ierror``: Fortran only: Error status (integer).

DESCRIPTION
-----------

:ref:`MPI_Comm_set_name` allows a user to associate a name string with a
communicator. The character string that is passed to :ref:`MPI_Comm_set_name`
is saved inside the MPI library (so it can be freed by the caller
immediately after the call, or allocated on the stack). Leading spaces
in *name* are significant, but trailing ones are not.

:ref:`MPI_Comm_set_name` is a local (noncollective) operation, which affects
only the name of the communicator as seen in the process that made the
:ref:`MPI_Comm_set_name` call. There is no requirement that the same (or any)
name be assigned to a communicator in every process where it exists.

The length of the name that can be stored depends on which Open MPI
interface the application uses.  The traditional Open MPI interface limits
names to |ompi_max_object_name| bytes (the value of ``MPI_MAX_OBJECT_NAME``
in ``mpi.h``, which Open MPI has used for many years), while the MPI Forum
standard ABI limits names to |mpi_abi_max_object_name| bytes (the value
required by the MPI standard).  Open MPI honors whichever limit corresponds
to the interface the application was compiled against.  A name longer than
the applicable limit (including its terminating null character) is silently
truncated; setting an over-long name is not an error.


NOTES
-----

Since :ref:`MPI_Comm_set_name` is provided to help debug code, it is sensible
to give the same name to a communicator in all of the processes where it
exists, to avoid confusion.

Regarding name length, under circumstances of store exhaustion, an
attempt to set a name of any length could fail; therefore, the value of
MPI_MAX_OBJECT_NAME should be viewed only as a strict upper bound on the
name length, not a guarantee that setting names of less than this length
will always succeed.


ERRORS
------

.. include:: ./ERRORS.rst

.. seealso::
   * :ref:`MPI_Comm_get_name`
