MEMCACHED_GET(3)

💖 MEMCACHED_GET(3) — bestie's guide to pulling your data back out 💖

okay so this is a page from libmemcached-awesome, and it's all about getting stuff back out of your memcached server. it's giving "retrieval era" ✨

---

🌸 NAME 🌸

memcached_get — retrieving data from the server. that's the whole vibe. you put a value in, now you want it back. slay.

---

✨ SYNOPSIS ✨

first things first, you gotta include the header and link the lib:

#include <libmemcached/memcached.h>
       Compile and link with -lmemcached

and here's the whole squad of function signatures, verbatim, no cap:

memcached_result_st *memcached_fetch_result(memcached_st *ptr,
memcached_result_st *result, memcached_return_t *error)

char *memcached_get(memcached_st *ptr, const char *key, size_t
key_length, size_t *value_length, uint32_t *flags, memcached_return_t
*error)

memcached_return_t memcached_mget(memcached_st *ptr, const char *const
*keys, const size_t *key_length, size_t number_of_keys)

char *memcached_get_by_key(memcached_st *ptr, const char *group_key,
size_t group_key_length, const char *key, size_t key_length, size_t
*value_length, uint32_t *flags, memcached_return_t *error)

memcached_return_t memcached_mget_by_key(memcached_st *ptr, const char
*group_key, size_t group_key_length, const char *const *keys, const
size_t *key_length, size_t number_of_keys)

memcached_return_t memcached_fetch_execute(memcached_st *ptr,
memcached_execute_fn *callback, void *context, uint32_t
number_of_callbacks)

memcached_return_t memcached_mget_execute(memcached_st *ptr, const char
*const *keys, const size_t *key_length, size_t number_of_keys,
memcached_execute_fn *callback, void *context, uint32_t
number_of_callbacks)

memcached_return_t memcached_mget_execute_by_key(memcached_st *ptr,
const char *group_key, size_t group_key_length, const char *const *keys,
const size_t *key_length, size_t number_of_keys, memcached_execute_fn
*callback, void *context, uint32_t number_of_callbacks)

typedef memcached_return_t (*memcached_execute_fn)(const memcached_st
*ptr, memcached_result_st *result, void *context)

---

🦋 DESCRIPTION 🦋

memcached_get() — the one-at-a-time girly 🎀

memcached_get() is your girl for grabbing one single value off the server. you hand her a key and the key's length, and she goes and fetches that object for you.

but bestie, you also have to pass in three pointer variables that tell you the state of the returned object:

• a uint32_t pointer that holds whatever flags you originally stored with the value
• a size_t pointer that gets filled with the size of the object
• a memcached_return_t pointer that holds any error

if it works, you get the object back. if it doesn't, you get NULL. and listen: any object that memcached_get() hands you must be released by the caller application. you freed it? good. you didn't? that's a leak, and that's not the vibe. 💀

memcached_mget() — the multiget queen 👑

memcached_mget() lets you select multiple keys at once. and lowkey this is the move, because for multiple key operations it is always faster to use this function. always. no debate.

also important: this function always works asynchronously. periodt.

fetching after a multiget 🔥

so you did a memcached_mget() and it succeeded. now what? you call memcached_fetch_result() to actually retrieve the data. keep calling it until it returns NULL — that means there are no more values, you're done, you ate. 🍓

if you need to bail out in the middle of a memcached_mget() call, you can run a memcached_quit(), though this is not required.

memcached_fetch_result() — the detail dump 💅

memcached_fetch_result() fetches an individual value from the server. memcached_mget() must always be called before using this method — don't skip steps, bestie.

you must pass in a key and its length to fetch the object. you must supply three pointer variables which will give you the state of the returned object:

• a uint32_t pointer to contain whatever flags you stored with the value
• a size_t pointer which will be filled with the size of the object
• a memcached_return_t pointer to hold any error

the object comes back on success, NULL comes back on failure. and here's the important bit: MEMCACHED_END is returned by the *error value once all the objects that have been found have been returned. the final value upon MEMCACHED_END is null.

memcached_fetch_result() is also the one that returns a memcached_result_st structure from a memcached server. that result object is forward compatible with changes to the server — so it won't ghost you when the server updates. for more info, go read the memcached_result_st help. and if you don't pass it one, this function will dynamically allocate a result structure for you. she's thoughtful like that. 🫶

memcached_fetch_execute() — the callback girlie 🌈

memcached_fetch_execute() is a callback function for result sets. instead of handing results back to you for processing, it passes each of the result sets straight to the list of functions you provide.

what does it pass to your function, you ask?

• a memcached_st that can be cloned for use in the called function — note: it cannot be used directly
• a result set which does not need to be freed
• a "context" — which is just a pointer to a memory reference you supply to the calling function

currently only one value is being passed to each function call. in the future there will be an option to allow this to be an array. foreshadowing ✨

memcached_mget_execute() and memcached_mget_execute_by_key() — the deadlock solvers 😭

these two are similar to memcached_mget(), but they may trigger the supplied callbacks with result sets while sending out the queries.

why do you care? because if you try to do a really large multiget with memcached_mget(), you may hit a deadlock in the OS kernel — it'll fail to write data to the socket because the input buffer is full. not cute. 🙈

memcached_mget_execute() solves this by processing some of the results before continuing to send out requests. iconic behaviour honestly.

⚠️ please note: this function is only available in the binary protocol.

memcached_get_by_key() and memcached_mget_by_key() — the master key duo 🗝️

these two behave in a similar nature to memcached_get() and memcached_mget(). the difference? they take a master key that's used for determining which server an object was stored on, in case key partitioning was used for storage.

the UDP disclaimer ⚠️

all of the functions above are not tested when MEMCACHED_BEHAVIOR_USE_UDP has been set. if you execute any of them with this behavior on, you'll get MEMCACHED_NOT_SUPPORTED back — or, for those functions which don't return a memcached_return_t, the error function parameter will be set to MEMCACHED_NOT_SUPPORTED.

so. don't. 💀

---

👑 RETURN VALUE 👑

all objects retrieved via memcached_get() or memcached_get_by_key() must be freed with free(3).

memcached_get() will return NULL on error. you must look at the value of error to determine what the actual error was — don't just stare at the NULL and cry, bestie, the info is right there.

memcached_fetch_execute() returns MEMCACHED_SUCCESS if all keys were successful. MEMCACHED_NOTFOUND will be returned if no keys at all were found.

memcached_fetch_result() sets error to MEMCACHED_END upon successful conclusion. MEMCACHED_NOTFOUND will be returned if no keys at all were found.

---

🧚 SEE ALSO 🧚

• memcached(1)
• libmemcached(3)
• memcached_strerror(3)

go read those too, iykyk 💜

---

and that's the whole page, bestie!! this one's from libmemcached-awesome, version 1.1, dated Jul 24, 2025 — so you know it's fresh. now go free your pointers, hydrate, and multiget responsibly 🌸💅✨