# std::ios_base::xalloc

> C++ Atlas: `cppatlas.com/w/cpp/io/ios_base/xalloc` | Source: https://en.cppreference.com/w/cpp/io/ios_base/xalloc | Domain: Input/output | Standards: C++11

Returns a unique (program-wide) index value that can be used to access one long and one void* elements in the private storage of std::ios_base by calling iword() and pword().

## Official Specification Summary (cppreference)

```cpp
static int xalloc();
```

Returns a unique (program-wide) index value that can be used to access one `long` and one `void*` elements in the private storage of `std::ios_base` by calling `iword()` and `pword()`. The call to `xalloc` does not allocate memory.

This function is thread-safe: concurrent access by multiple threads does not result in a data race. (since C++11)

Effectively increments the next available unique index.

### Return value

Unique integer for use as pword/iword index.

### Example

Uses base class pword storage for runtime type identification of derived stream objects.

```cpp
#include <iostream>

template<class CharT, class Traits = std::char_traits<CharT>>
class mystream : public std::basic_ostream<CharT, Traits>
{
public:
    static const int xindex;

    mystream(std::basic_ostream<CharT, Traits>& ostr) :
        std::basic_ostream<CharT, Traits>(ostr.rdbuf())
    {
        this->pword(xindex) = this;
    }

    void myfn()
    {
        *this << "[special handling for mystream]";
    }
};

// Each specialization of mystream obtains a unique index from xalloc()
template<class CharT, class Traits>
const int mystream<CharT, Traits>::xindex = std::ios_base::xalloc();

// This I/O manipulator will be able to recognize ostreams that are mystreams
// by looking up the pointer stored in pword
template<class CharT, class Traits>
std::basic_ostream<CharT, Traits>& mymanip(std::basic_ostream<CharT, Traits>& os)
{
    if (os.pword(mystream<CharT, Traits>::xindex) == &os)
        static_cast<mystream<CharT, Traits>&>(os).myfn();
    return os;
}

int main()
{
    std::cout << "cout, narrow-character test " << mymanip << '\n';

    mystream<char> myout(std::cout);
    myout << "myout, narrow-character test " << mymanip << '\n';

    std::wcout << "wcout, wide-character test " << mymanip << '\n';

    mystream<wchar_t> mywout(std::wcout);
    mywout << "mywout, wide-character test " << mymanip << '\n';
}
```

Output:

```text
cout, narrow-character test
myout, narrow-character test [special handling for mystream]
wcout, wide-character test
mywout, wide-character test [special handling for mystream]
```

### Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

| DR | Applied to | Behavior as published | Correct behavior |
| --- | --- | --- | --- |
| LWG 2143 | C++11 | `xalloc` was not thread-safe | made thread-safe |

### See also

- [`pword`](https://en.cppreference.com/w/cpp/io/ios_base/pword): resizes the private storage if necessary and access to the `void*` element at the given index (public member function)
- [`iword`](https://en.cppreference.com/w/cpp/io/ios_base/iword): resizes the private storage if necessary and access to the `long` element at the given index (public member function)

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