What is double star (eg. NSError **)?

So, I saw this:

error:(NSError **)error

in the apple doc's. Why two stars? What is the significance?

A "double star" is a pointer to a pointer. So NSError ** is a pointer to a pointer to an object of type NSError. It basically allows you to return an error object from the function. You can create a pointer to an NSError object in your function (call it *myError), and then do something like this:

*error = myError;

to "return" that error to the caller.

---

In reply to a comment posted below:

You can't simply use an NSError * because in C, function parameters are passed by value—that is, the values are copied when passed to a function. To illustrate, consider this snippet of C code:

void f(int x)
{
    x = 4;
}

void g(void)
{
    int y = 10;
    f(y);
    printf("%d\n", y);    // Will output "10"
}

The reassignment of x in f() does not affect the argument's value outside of f() (in g(), for example).

Likewise, when a pointer is passed into a function, its value is copied, and re-assigning will not affect the value outside of the function.

void f(int *x)
{
    x = 10;
}

void g(void)
{
    int y = 10;
    int *z = &y;
    printf("%p\n", z);    // Will print the value of z, which is the address of y
    f(z);
    printf("%p\n", z);    // The value of z has not changed!
}

Of course, we know that we can change the value of what z points to fairly easily:

void f(int *x)
{
    *x = 20;
}

void g(void)
{
    int y = 10;
    int *z = &y;
    printf("%d\n", y);    // Will print "10"
    f(z);
    printf("%d\n", y);    // Will print "20"
}

So it stands to reason that, to change the value of what an NSError * points to, we also have to pass a pointer to the pointer.