What is a good definition of a “userdata pointer”?

Question

I have searched for a good explanation but can't find one.

I could try to write one myself but I'd prefer if someone with better english could help me explain this for Zan Lynx in the comment here.

...and it seems like there should be a good explanation somewhere, why not here?

Answer 1

When a library manages some data structures on behalf of a program (e.g. windows in a GUI application are managed by the OS), it usually keeps the contents of those structures private. However, it is typically useful for the program to maintain some additional data specific to the program's use of those structures. Therefore, a library will often provide access to a field (often called user data) which it stores with each structure.

A common use of the user data field by a program is to allocate some memory each time the program requests the library to create a structure, and to store the pointer to that memory in the user data field provided by the library, hence the term userdata pointer.

Answer 2

Look at sqlite3_exec() – it calls a callback (third parameter) for each retrieved row and passes a pointer you provide (fourth parameter) into this callback. This can be a pointer to whatever object you wish – you have to cast it appropriately before you can access the pointed object. This object is called a userdata object and a pointer to it is called a userdata pointer.

In case of sqlite3_exec() you can pass a pointer to a container which is to store all the retrieved table rows upon the request completion.