---
name: "MPI_T_cvar_handle_free.openmpi"
section: "3"
platform: "linux"
package: "openmpi-doc"
version: "5.0.7-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/MPI_T_cvar_handle_free.openmpi"
---

# MPI\_T\_cvar\_handle\_free.openmpi(3)

*MPI\_T\_cvar\_handle\_alloc*, *MPI\_T\_cvar\_handle\_free* - Allocate/free control variable handles

## SYNTAX

### C Syntax

```
#include <mpi.h>
int MPI_T_cvar_handle_alloc(int cvar_index, void *obj_handle,
                            MPI_T_cvar_handle *handle, int *count)
int MPI_T_cvar_handle_free(MPI_T_cvar_handle *handle)
```

## DESCRIPTION

*MPI\_T\_cvar\_handle\_alloc* binds the control variable specified in *cvar\_index* to the MPI object specified in *obj\_handle*. If *MPI\_T\_cvar\_get\_info* returns MPI\_T\_BIND\_NO\_OBJECT as the binding of the variable the *obj\_handle* argument is ignored. The number of values represented by this control variable is returned in the *count* parameter. If the control variable represents a string then *count* will be the maximum length of the string.

*MPI\_T\_cvar\_handle\_free* frees a handle allocated by *MPI\_T\_cvar\_handle\_alloc* and sets the *handle* argument to MPI\_T\_CVAR\_HANDLE\_NULL.

## NOTES

Open MPI does not currently support binding MPI objects to control variables so the *obj\_handle* argument is always ignored.

## ERRORS

*MPI\_T\_cvar\_handle\_alloc* will fail if:

- •

  **MPI\_T\_ERR\_NOT\_INITIALIZED**: The MPI Tools interface not initialized

- •

  **MPI\_T\_ERR\_INVALID\_INDEX**: The control variable index is invalid

- •

  **MPI\_T\_ERR\_OUT\_OF\_HANDLES**: No more handles available

*MPI\_T\_cvar\_handle\_free* will fail if:

- •

  **MPI\_T\_ERR\_NOT\_INITIALIZED**: The MPI Tools interface not initialized

- •

  **MPI\_T\_ERR\_INVALID\_HANDLE**: The handle is invalid

**SEE ALSO:**

- •

  *MPI\_T\_cvar\_get\_info*

## COPYRIGHT

2003-2025, The Open MPI Community