Sun Java System Directory Server Enterprise Edition 6.0 Developer's Guide

Memory Concerns

The void *value argument should always be a pointer to the type of value you are retrieving:

int connid = 0;
retval = slapi_pblock_get(pb, SLAPI_CONN_ID, &connid);

SLAPI_CONN_ID is an integer value, so you will pass in a pointer to/address of an integer to get the value. Similarly, for a char * value (a string), pass in a pointer to/address of the value. For example:

char *binddn = NULL;
retval = slapi_pblock_get(pb, SLAPI_CONN_DN, &binddn);

With certain compilers on some platforms, you may have to cast the value to (void *).

We recommend that you set the value to 0 or NULL before calling slapi_pblock_get() to avoid reading from uninitialized memory, in case the call to slapi_pblock_get() fails.

In most instances, the caller should not free the returned value. The value will usually be freed internally or through the call to slapi_pblock_destroy() . The exception is if the value is explicitly set by the caller through slapi_pblock_set(). In this case, the caller is responsible for memory management. If the value is freed, it is strongly recommended that the free is followed by a call to slapi_pblock_set() with a value of NULL. For example:

char *someparam = NULL;
someparam = slapi_ch_strdup(somestring);
slapi_pblock_set(pb, SOME_PARAM, someparam);
someparam = NULL; /* avoid dangling reference */
slapi_pblock_get(pb, SOME_PARAM, &someparam);
slapi_pblock_set(pb, SOME_PARAM, NULL); /* Make sure no one else
                                              references this. */

Some internal functions may change the value passed in, so it is recommended to use slapi_pblock_get() to retrieve the value again, rather than relying on a potential dangling pointer. This is shown in the previous example, which sets someparam to NULL after setting it in the parameter block.