Open MPI logo

MPI_Comm_set_name(3) man page (version 1.2.9)

  |   Home   |   Support   |   FAQ   |  

« Return to documentation listing



NAME

       MPI_Comm_set_name - Associates a name with a communicator.

SYNTAX


C Syntax

       #include <mpi.h>
       int MPI_Comm_set_name(MPI_Comm comm, char *comm_name)

Fortran Syntax

       INCLUDE 'mpif.h'
       MPI_COMM_SET_NAME(COMM, COMM_NAME, IERROR)
            INTEGER   COMM, IERROR
            CHARACTER*(*) COMM_NAME

C++ Syntax

       #include <mpi.h>
       void MPI::Comm::Set_name(const char* comm_name)

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 commu-
                 nicator (string).

OUTPUT PARAMETER

       IERROR    Fortran only: Error status (integer).

DESCRIPTION

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

       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
       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 is limited to the value of
       MPI_MAX_OBJECT_NAME in Fortran and MPI_MAX_OBJECT_NAME-1 in C  and  C++
       (to  allow  for the null terminator). Attempts to set names longer than
       this will result in truncation of the  name.  MPI_MAX_OBJECT_NAME  must
       have a value of at least 64.

NOTES

       Since  MPI_Comm_set_name is provided to help debug code, it is sensible

ERRORS

       Almost  all MPI routines return an error value; C routines as the value
       of the function and Fortran routines in the last  argument.  C++  func-
       tions  do  not  return  errors.  If the default error handler is set to
       MPI::ERRORS_THROW_EXCEPTIONS, then on error the C++ exception mechanism
       will be used to throw an MPI:Exception object.

       Before  the  error  value is returned, the current MPI error handler is
       called. By default, this error handler aborts the MPI job,  except  for
       I/O   function   errors.   The   error  handler  may  be  changed  with
       MPI_Comm_set_errhandler; the predefined error handler MPI_ERRORS_RETURN
       may  be  used  to cause error values to be returned. Note that MPI does
       not guarantee that an MPI program can continue past an error.

SEE ALSO

       MPI_Comm_get_name

Open MPI 1.2                    September 2006     MPI_Comm_set_name(3OpenMPI)

« Return to documentation listing