# std::out_ptr

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

Returns an std::out_ptr_t with deduced template arguments that captures arguments for resetting by reference.

## Official Specification Summary (cppreference)

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

template< class Pointer = void, class Smart, class... Args >
auto out_ptr( Smart& s, Args&&... args ); // (since C++23)
```

Returns an `std::out_ptr_t` with deduced template arguments that captures arguments for resetting by reference.

The program is ill-formed if construction of the return value (see below) is ill-formed.

### Parameters

- `s` - the object (typically a smart pointer) to adapt
- `args...` - the arguments for resetting to capture

### Return value

`std::out_ptr_t<Smart, P, Args&&>(s, std::forward<Args>(args)...)`, where `P` is

- `Pointer`, if `Pointer` is not same as `void`. Otherwise,
- `Smart::pointer`, if it is valid and denotes a type. Otherwise,
- `Smart::element_type*`, if `Smart::element_type` is valid and denotes a type. Otherwise,
- `std::pointer_traits<Smart>::element_type*`.

### Notes

Users may specify the template argument for the template parameter `Pointer`, in order to interoperate with foreign functions that take a `Pointer*`.

As all arguments for resetting are captured by reference, the returned `out_ptr_t` should be a temporary object destroyed at the end of the full-expression containing the call to the foreign function, in order to avoid dangling references.

| 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

Use `std::out_ptr` to adapt a smart pointer for `sqlite3_open`, which expects a `sqlite3**` as an out parameter.

```cpp
#include <memory>
#include <sqlite3.h>

int main()
{
    auto close_db = [](sqlite3* db) { sqlite3_close(db); };

    {
        // open an in-memory database, and manage its lifetime with std::unique_ptr
        std::unique_ptr<sqlite3, decltype(close_db)> up;
        sqlite3_open(":memory:", std::out_ptr(up));

        sqlite3* db = up.get();
        // do something with db ...
    }
    {
        // same as above, but use a std::shared_ptr
        std::shared_ptr<sqlite3> sp;
        sqlite3_open(":memory:", std::out_ptr(sp, close_db));

        sqlite3* db = sp.get();
        // do something with db ...
    }
}
```

### See also

- [`inout_ptr`](https://en.cppreference.com/w/cpp/memory/inout_ptr_t/inout_ptr) (C++23): creates an `inout_ptr_t` with an associated smart pointer and resetting arguments (function template)
- [`make_unique`](https://en.cppreference.com/w/cpp/memory/unique_ptr/make_unique) (C++14), [`make_unique_for_overwrite`](https://en.cppreference.com/w/cpp/memory/unique_ptr/make_unique) (C++20): creates a unique pointer that manages a new object (function template)
- [`make_shared`](https://en.cppreference.com/w/cpp/memory/shared_ptr/make_shared), [`make_shared_for_overwrite`](https://en.cppreference.com/w/cpp/memory/shared_ptr/make_shared) (C++20): creates a shared pointer that manages a new object (function template)

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