MPI Subroutine Reference

MPI_COMM_GET_NAME, MPI_Comm_get_name

Purpose

Returns the name that was last associated with a communicator.

C synopsis

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

C++ synopsis

#include mpi.h
void MPI::Comm::Get_name(char* comm_name, int& resultlen) const;

FORTRAN synopsis

include 'mpif.h' or use mpi
MPI_COMM_GET_NAME(INTEGER COMM, CHARACTER*(*) COMM_NAME, INTEGER RESULTLEN, 
		  INTEGER IERROR)

Parameters

comm

is the communicator with the name to be returned (handle) (IN)

comm_name

is the name previously stored on the communicator, or an empty string if no such name exists (string) (OUT)

resultlen

is the length of the returned name (integer) (OUT)

IERROR

is the FORTRAN return code. It is always the last argument.

Description

This subroutine returns the name that was last associated with the specified communicator. The name can be set and retrieved from any language. The same name is returned independent of the language used. The name should be allocated so it can hold a resulting string that is the length of MPI_MAX_OBJECT_NAME. For PE MPI, the value of MPI_MAX_OBJECT_NAME is 256. MPI_COMM_GET_NAME returns a copy of the set name in comm_name.

Notes

If you did not associate a name with a communicator, or if an error occurs, MPI_COMM_GET_NAME returns an empty string (all spaces in FORTRAN or "" in C and C++). The two predefined communicators have predefined names associated with them. Thus, the names of MPI_COMM_SELF and MPI_COMM_WORLD have the default of MPI_COMM_SELF and MPI_COMM_WORLD. The fact that the system may have assigned a default name to a communicator does not prevent you from setting a name on the same communicator; doing this removes the old name and assigns the new one.

It is safe simply to print the string returned by MPI_COMM_GET_NAME, as it is always a valid string even if there was no name.

Errors

Fatal errors:

Invalid communicator

MPI already finalized

MPI not initialized

Related information

MPI::Comm::Clone

MPI_COMM_DUP

MPI_COMM_SET_NAME