# std::inout_ptr_t

> C++ Atlas: `cppatlas.com/w/cpp/memory/inout_ptr_t` | Source: https://en.cppreference.com/w/cpp/memory/inout_ptr_t | Domain: Memory management | Standards: C++11, C++23

inout_ptr_t is used to adapt types such as smart pointers for foreign functions that reset ownership via a Pointer* (usually T** for some object type T) or void** parameter.

## Official Specification Summary (cppreference)

```cpp
// Defined in header <memory>

template< class Smart, class Pointer, class... Args >
class inout_ptr_t; // (since C++23)
```

`inout_ptr_t` is used to adapt types such as smart pointers for foreign functions that reset ownership via a `Pointer*` (usually `T**` for some object type `T`) or `void**` parameter.

`inout_ptr_t` captures additional arguments on construction, provides a storage for the result which such an aforementioned foreign function accesses, releases the ownership held by the adapted `Smart` object, and finally resets the adapted `Smart` object with the result and the captured arguments when it is destroyed.

`inout_ptr_t` behaves as if it holds following non-static data members:

- a `Smart&` reference, which is bound to the adapted object on construction,
- for every `T` in `Args...`, a member of type `T`, which is an argument captured on construction and used for resetting while destruction, and
- a member subobject that suitable for storing a `Pointer` within it and providing a `void*` object, where the `Pointer` or `void*` object is generally exposed to a foreign function for ownership resetting.

If `Smart` is not a pointer type, `release()` is called at most once on the adapted object. Implementations may call `release()` within constructor, or before resetting within destructor if the `Pointer` value is not null.

Users can control whether each argument for resetting is captured by copy or by reference, by specifying an object type or a reference type in `Args...` respectively.

### Template parameters

- `Smart` - the type of the object (typically a smart pointer) to adapt
- `Pointer` - type of the object (typically a raw pointer) to which a foreign function accesses for ownership resetting
- `Args...` - type of captured arguments used for resetting the adapted object

**Type requirements**

- `Pointer` must meet the requirements of *NullablePointer*.
- The program is ill-formed if `Smart` is a `std::shared_ptr` specialization.

### Specializations

Unlike most class templates in the standard library, program-defined specializations of `inout_ptr_t` that depend on at least one program-defined type need not meet the requirements for the primary template.

This license allows a program-defined specialization to expose the raw pointer stored within a non-standard smart pointer to foreign functions.

### Member functions

- (constructor) (C++23): constructs an `inout_ptr_t` (public member function)
- `operator=` [deleted](C++23): `inout_ptr_t` is not assignable (public member function)
- (destructor) (C++23): resets the adapted smart pointer after releasing its ownership (public member function)
- `operator Pointer*` (C++23), `operator void**`: converts the `inout_ptr_t` to the address of the storage for output (public member function)

### Non-member functions

- `inout_ptr` (C++23): creates an `inout_ptr_t` with an associated smart pointer and resetting arguments (function template)

### Notes

`inout_ptr_t` expects that the foreign functions release the ownership represented by the value of the pointed-to `Pointer`, and then re-initialize it. As such operation requires unique ownership, the usage with `std::shared_ptr` is forbidden.

The typical usage of `inout_ptr_t` is creating its temporary objects by `std::inout_ptr`, which resets the adapted smart pointer immediately. E.g. given a setter function and a smart pointer of appropriate type declared with `int foreign_resetter(T**);` and `std::unique_ptr<T, D> up;` respectively,

```cpp
if (int ec = foreign_resetter(std::inout_ptr(up)))
    return ec;
```

is roughly equivalent to

```cpp
T *raw_p = up.get();
up.release();
int ec = foreign_resetter(&raw_p);
up.reset(raw_p);
if (ec != 0)
    return ec;
```

It is not recommended to create an `inout_ptr_t` object of a storage duration other than automatic storage duration, because such code is likely to produce dangling references and result in undefined behavior on destruction.

Captured arguments are typically packed into a `std::tuple<Args...>`. Implementations may use different mechanism to provide the `Pointer` or `void*` object they need hold.

| Feature-test macro | Value | Std | Feature |
| --- | --- | --- | --- |
| `__cpp_lib_out_ptr` | `202106L` | (C++23) | `std::out_ptr`, `std::inout_ptr` |
| `__cpp_lib_out_ptr` | `202311L` | (C++26) | freestanding `std::out_ptr` and `std::inout_ptr` |

### Example

> Note: This section is incomplete Reason: no example

### See also

- [`out_ptr_t`](https://en.cppreference.com/w/cpp/memory/out_ptr_t) (C++23): interoperates with foreign pointer setters and resets a smart pointer on destruction (class template)
- [`unique_ptr`](https://en.cppreference.com/w/cpp/memory/unique_ptr) (C++11): smart pointer with unique object ownership semantics (class template)
- [`shared_ptr`](https://en.cppreference.com/w/cpp/memory/shared_ptr) (C++11): smart pointer with shared object ownership semantics (class template)

---
Attribution: content from https://en.cppreference.com/w/cpp/memory/inout_ptr_t (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.