MPI\_T\_CVAR\_HANDLE\_FREE(3) Open MPI MPI\_T\_CVAR\_HANDLE\_FREE(3)

MPI\_T\_cvar\_handle\_alloc <#mpi-t-cvar-handle-alloc>, MPI\_T\_cvar\_handle\_free - Allocate/free control variable handles

# [SYNTAX](#SYNTAX)

## [C 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](#DESCRIPTION)

MPI\_T\_cvar\_handle\_alloc &lt;#mpi-t-cvar-handle-alloc&gt; binds the control variable specified in *cvar\_index* to the MPI object specified in *obj\_handle*. If MPI\_T\_cvar\_get\_info &lt;#mpi-t-cvar-get-info&gt; 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 &lt;#mpi-t-cvar-handle-alloc&gt; and sets the *handle* argument to MPI\_T\_CVAR\_HANDLE\_NULL.

# [NOTES](#NOTES)

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

# [ERRORS](#ERRORS)

MPI\_T\_cvar\_handle\_alloc &lt;#mpi-t-cvar-handle-alloc&gt; 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 &lt;#mpi-t-cvar-get-info&gt;

# [Copyright](#Copyright)

2003-2026, The Open MPI Community

September 16, 2026

---

Document: MPI_T_cvar_handle_free(3) from openmpi 5.0.11-r1 (Chainguard OS)
Source: https://github.com/open-mpi/ompi