Pointer declaration

Declares a variable of a pointer or pointer-to-member type.

Syntax

A pointer declaration is any simple declaration whose declarator has the form

There are no pointers to references and there are no pointers to bit-fields

Pointers

Every value of pointer type is one of the following:

• a pointer to an object or function (in which case the pointer is said to point to the object or function), or
• a pointer past the end of an object, or
• the null pointer value for that type, or
• an invalid pointer value.

A pointer that points to an object represents the address of the first byte in memory occupied by the object. A pointer past the end of an object represents the address

Note that two pointers that represent the same address may nonetheless have different values.

struct C
{
    int x, y;
} c;
 
int* px = &c.x;   // value of px is "pointer to c.x"
int* pxe= px + 1; // value of pxe is "pointer past the end of c.x"
int* py = &c.y;   // value of py is "pointer to c.y"
 
assert(pxe == py); // == tests if two pointers represent the same address
                   // may or may not fire
 
*pxe = 1; // undefined behavior even if the assertion does not fire

Indirection through an invalid pointer value and passing an invalid pointer value to a deallocation function have undefined behavior. Any other use of an invalid pointer value has implementation-defined behavior. Some implementations might define that copying an invalid pointer value causes a system-generated runtime fault.

Pointers to objects

A pointer to object can be initialized with the return value of the address-of operator

int n;
int* np = &n;          // pointer to int
int* const* npp = &np; // non-const pointer to const pointer to non-const int
 
int a[2];
int (*ap)[2] = &a;     // pointer to array of int
 
struct S { int n; };
 
S s = {1};
int* sp = &s.n;        // pointer to the int that is a member of s

Pointers may appear as operands to the built-in indirection operator (unary operator*), which returns the lvalue expression

int n;
int* p = &n;     // pointer to n
int& r = *p;     // reference is bound to the lvalue expression that identifies n
r = 7;           // stores the int 7 in n
std::cout << *p; // lvalue-to-rvalue implicit conversion reads the value from n

Pointers to class objects may also appear as the left-hand operands of the member access operators operator-> and operator->*

Because of the array-to-pointer implicit conversion, pointer to the first element of an array can be initialized with an expression of array type:

int a[2];
int* p1 = a; // pointer to the first element a[0] (an int) of the array a
 
int b[6][3][8];
int (*p2)[3][8] = b; // pointer to the first element b[0] of the array b,
                     // which is an array of 3 arrays of 8 ints

Because of the derived-to-base implicit conversion for pointers, pointer to a base class can be initialized with the address of a derived class:

struct Base {};
struct Derived : Base {};
 
Derived d;
Base* p = &d;

If Derived is polymorphic, such a pointer may be used to make virtual function calls.

Certain addition, subtraction, increment, and decrement operators are defined for pointers to elements of arrays: such pointers satisfy the LegacyRandomAccessIterator requirements and allow the C++ library algorithms

Comparison operators member access

Many implementations also provide strict total ordering std::less for pointers that has that guarantee. This makes it possible to use all pointers of random origin as keys in standard associative containers such as std::set or std::map

Pointers to void

Pointer to object of any type can be implicitly converted to pointer to (possibly cv-qualified) void; the pointer value is unchanged. The reverse conversion, which requires static_cast or explicit cast

int n = 1;
int* p1 = &n;
void* pv = p1;
int* p2 = static_cast<int*>(pv);
std::cout << *p2 << '\n'; // prints 1

If the original pointer is pointing to a base class subobject within an object of some polymorphic type, dynamic_cast may be used to obtain a void*

Pointers to void have the same size, representation and alignment as pointers to char.

Pointers to void are used to pass objects of unknown type, which is common in C interfaces: std::malloc returns void*, std::qsort expects a user-provided callback that accepts two const void* arguments. pthread_create expects a user-provided callback that accepts and returns void*

Pointers to functions

A pointer to function can be initialized with an address of a non-member function or a static member function. Because of the function-to-pointer

void f(int);
void (*p1)(int) = &f;
void (*p2)(int) = f; // same as &f

Unlike functions or references to functions, pointers to functions are objects and thus can be stored in arrays, copied, assigned, etc.

void (a[10])(int);  // Error: array of functions
void (&a[10])(int); // Error: array of references
void (*a[10])(int); // OK: array of pointers to functions

Note: declarations involving pointers to functions can often be simplified with type aliases:

using F = void(int); // named type alias to simplify declarations
F a[10];  // Error: array of functions
F& a[10]; // Error: array of references
F* a[10]; // OK: array of pointers to functions

A pointer to function can be used as the left-hand operand of the function call operator, this invokes the pointed-to function:

int f(int n)
{
    std::cout << n << '\n';
    return n * n;
}
 
int main()
{
    int (*p)(int) = f;
    int x = p(7);
}

Dereferencing a function pointer yields the lvalue identifying the pointed-to function:

int f();
int (*p)() = f;  // pointer p is pointing to f
int (&r)() = *p; // the lvalue that identifies f is bound to a reference
r();             // function f invoked through lvalue reference
(*p)();          // function f invoked through the function lvalue
p();             // function f invoked directly through the pointer

A pointer to function may be initialized from an overload set which may include functions, function template specializations, and function templates, if only one overload matches the type of the pointer (see address of an overloaded function

template<typename T>
T f(T n) { return n; }
 
double f(double n) { return n; }
 
int main()
{
    int (*p)(int) = f; // instantiates and selects f<int>
}

Equality comparison operators are defined for pointers to functions (they compare equal if pointing to the same function).

Pointers to members

Pointers to data members

A pointer to non-static member object m which is a member of class C can be initialized with the expression &C::m exactly. Expressions such as &(C::m) or &m inside C

Such a pointer may be used as the right-hand operand of the pointer-to-member access operators operator.* and operator->*

struct C { int m; };
 
int main()
{
    int C::* p = &C::m;          // pointer to data member m of class C
    C c = {7};
    std::cout << c.*p << '\n';   // prints 7
    C* cp = &c;
    cp->m = 10;
    std::cout << cp->*p << '\n'; // prints 10
}

Pointer to data member of an accessible unambiguous non-virtual base class can be implicitly converted

struct Base { int m; };
struct Derived : Base {};
 
int main()
{
    int Base::* bp = &Base::m;
    int Derived::* dp = bp;
    Derived d;
    d.m = 1;
    std::cout << d.*dp << ' ' << d.*bp << '\n'; // prints 1 1
}

Conversion in the opposite direction, from a pointer to data member of a derived class to a pointer to data member of an unambiguous non-virtual base class, is allowed with static_cast and explicit cast

struct Base {};
struct Derived : Base { int m; };
 
int main()
{
    int Derived::* dp = &Derived::m;
    int Base::* bp = static_cast<int Base::*>(dp);
 
    Derived d;
    d.m = 7;
    std::cout << d.*bp << '\n'; // okay: prints 7
 
    Base b;
    std::cout << b.*bp << '\n'; // undefined behavior
}

The pointed-to type of a pointer-to-member may be a pointer-to-member itself: pointers to members can be multilevel, and can be cv-qualified differently at every level. Mixed multi-level combinations of pointers and pointers-to-members are also allowed:

struct A
{
    int m;
    // const pointer to non-const member
    int A::* const p;
};
 
int main()
{
    // non-const pointer to data member which is a const pointer to non-const member
    int A::* const A::* p1 = &A::p;
 
    const A a = {1, &A::m};
    std::cout << a.*(a.*p1) << '\n'; // prints 1
 
    // regular non-const pointer to a const pointer-to-member
    int A::* const* p2 = &a.p;
    std::cout << a.**p2 << '\n'; // prints 1
}

Pointers to member functions

A pointer to non-static member function f which is a member of class C can be initialized with the expression &C::f exactly. Expressions such as &(C::f) or &f inside C

Such a pointer may be used as the right-hand operand of the pointer-to-member access operators operator.* and operator->*. The resulting expression

struct C
{
    void f(int n) { std::cout << n << '\n'; }
};
 
int main()
{
    void (C::* p)(int) = &C::f; // pointer to member function f of class C
    C c;
    (c.*p)(1);                  // prints 1
    C* cp = &c;
    (cp->*p)(2);                // prints 2
}

Pointer to member function of a base class can be implicitly converted to pointer to the same member function of a derived class:

struct Base
{
    void f(int n) { std::cout << n << '\n'; }
};
struct Derived : Base {};
 
int main()
{
    void (Base::* bp)(int) = &Base::f;
    void (Derived::* dp)(int) = bp;
    Derived d;
    (d.*dp)(1);
    (d.*bp)(2);
}

Conversion in the opposite direction, from a pointer to member function of a derived class to a pointer to member function of an unambiguous non-virtual base class, is allowed with static_cast and explicit cast

struct Base {};
struct Derived : Base
{
    void f(int n) { std::cout << n << '\n'; }
};
 
int main()
{
    void (Derived::* dp)(int) = &Derived::f;
    void (Base::* bp)(int) = static_cast<void (Base::*)(int)>(dp);
 
    Derived d;
    (d.*bp)(1); // okay: prints 1
 
    Base b;
    (b.*bp)(2); // undefined behavior
}

Pointers to member functions may be used as callbacks or as function objects, often after applying std::mem_fn or std::bind

#include <algorithm>
#include <cstddef>
#include <functional>
#include <iostream>
#include <string>
 
int main()
{
    std::vector<std::string> v = {"a", "ab", "abc"};
    std::vector<std::size_t> l;
    transform(v.begin(), v.end(), std::back_inserter(l),
              std::mem_fn(&std::string::size));
    for (std::size_t n : l)
        std::cout << n << ' ';
    std::cout << '\n';
}

1 2 3

Null pointers

Pointers of every type have a special value known as null pointer value of that type. A pointer whose value is null does not point to an object or a function (the behavior of dereferencing a null pointer is undefined), and compares equal to all pointers of the same type whose value is also null

A null pointer constant can be used to initialize a pointer to null or to assign the null value to an existing pointer, it is one of the following values:

• An integer literal with value zero.

The macro NULL can also be used, it expands to an implementation-defined null pointer constant.

Zero-initialization and value-initialization

Null pointers can be used to indicate the absence of an object (e.g. std::function::target()), or as other error condition indicators (e.g. dynamic_cast). In general, a function that receives a pointer argument almost always needs to check if the value is null and handle that case differently (for example, the delete expression

Invalid pointers

A pointer value p is valid in the context of an evaluation e

• p is a null pointer value.
• p is a pointer to function.
• p it is a pointer to or past the end of an object o, and e is in the duration of the region of storage for o

If a pointer value p is used in an evaluation e, and p is not valid in the context of e

• If e is an indirection or an invocation of a deallocation function
• Otherwise, the behavior is implementation-defined.

int* f()
{
    int obj;
    int* local_ptr = new (&obj) int;
 
    *local_ptr = 1; // OK, the evaluation “*local_ptr” is
                    // in the storage duration of “obj”
 
    return local_ptr;
}
 
int* ptr = f();  // the storage duration of “obj” is expired,
                 // therefore “ptr” is an invalid pointer in the following contexts
 
int* copy = ptr; // implementation-defined behavior
*ptr = 2;        // undefined behavior: indirection of an invalid pointer
delete ptr;      // undefined behavior: deallocating storage from an invalid pointer

Constness

• If cv appears before * in the pointer declaration, it is part of the declaration specifier sequence and applies to the pointed-to object.
• If cv appears after * in the pointer declaration, it is part of the declarator

// pc is a non-const pointer to const int
// cpc is a const pointer to const int
// ppc is a non-const pointer to non-const pointer to const int
const int ci = 10, *pc = &ci, *const cpc = pc, **ppc;
// p is a non-const pointer to non-const int
// cp is a const pointer to non-const int
int i, *p, *const cp = &i;
 
i = ci;    // okay: value of const int copied into non-const int
*cp = ci;  // okay: non-const int (pointed-to by const pointer) can be changed
pc++;      // okay: non-const pointer (to const int) can be changed
pc = cpc;  // okay: non-const pointer (to const int) can be changed
pc = p;    // okay: non-const pointer (to const int) can be changed
ppc = &pc; // okay: address of pointer to const int is pointer to pointer to const int
 
ci = 1;    // error: const int cannot be changed
ci++;      // error: const int cannot be changed
*pc = 2;   // error: pointed-to const int cannot be changed
cp = &ci;  // error: const pointer (to non-const int) cannot be changed
cpc++;     // error: const pointer (to const int) cannot be changed
p = pc;    // error: pointer to non-const int cannot point to const int
ppc = &p;  // error: pointer to pointer to const int cannot point to
           // pointer to non-const int

In general, implicit conversion from one multi-level pointer to another follows the rules described in qualification conversions

Composite pointer type

When an operand of a comparison operator or any of the second and third operands of a conditional operator

Given two operands p1 and p2 having types T1 and T2, respectively, p1 and p2

The composite pointer type C of p1 and p2 is determined as follows:

• Otherwise, if all following conditions are satisfied:

• T1 or T2 is “pointer to cv1 void”.
• The other type is “pointer to cv2 T”, where T is an object type or void.

C is “pointer to cv12 void”, where cv12 is the union of cv1 and cv2.

• Otherwise, if all following conditions are satisfied:

• T1 is “pointer to C1”.
• T2 is “pointer to C2”.
• One of C1 and C2 is reference-related to the other.

C is

• the qualification-combined type of T1 and T2, if C1 is reference-related to C2, or
• the qualification-combined type of T2 and T1, if C2 is reference-related to C1.

• Otherwise, if all following conditions are satisfied:

• T1 is “pointer to member of C1 of non-function type M1”.
• T2 is “pointer to member of C2 of non-function type M2”
• M1 and M2 are the same except top-level cv-qualifications.
• One of C1 and C2 is reference-related to the other.

C is

• the qualification-combined type of T2 and T1, if C1 is reference-related to C2, or
• the qualification-combined type of T1 and T2, if C2 is reference-related to C1.

• Otherwise, if T1 and T2 are similar types, C is the qualification-combined type of T1 and T2
• Otherwise, p1 and p2 do not have a composite pointer type, a program that necessitates the determination of C

using p = void*;
using q = const int*;
// The determination of the composite pointer type of “p” and “q”
// falls into the [“pointer to cv1 void” and “pointer to cv2 T”] case:
// cv1 = empty, cv2 = const, cv12 = const
// substitute “cv12 = const” into “pointer to cv12 void”:
// the composite pointer type is “const void*”
 
using pi = int**;
using pci = const int**;
// The determination of the composite pointer type of “pi” and “pci”
// falls into the [pointers to similar types “C1” and “C2”] case:
// C1 = int*, C2 = const int*
// they are reference-related types (in both direction) because they are similar
// the composite pointer type is the qualification-combined type
// of “p1” and “pc1” (or that of “pci” and “pi”): “const void* const *”

Defect reports

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

See also