MEMCACHED_FETCH_RESULT(3)

💖 NAME 💖

memcached_fetch_result — retrieving data from the server, bestie. That's it, that's the whole job. ✨

---

🎀 SYNOPSIS 🎀

first things first, you gotta grab the header, no cap:

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

then here's the whole squad of functions you're working with, all of them, every single one:

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 🌸

okay so let's go one by one because there is a lot here and honestly? it all slays once you get it. 🫶

💅 memcached_get()

memcached_get() is how you fetch a single individual value from the server. you pass in a key and its length to grab the object, and you have to hand over three pointer variables so you can find out what state the returned object is in, periodt:

• a uint32_t pointer — it holds whatever flags you stored alongside the value
• a size_t pointer — it gets filled in with the size of the object
• a memcached_return_t pointer — it holds any error

on success you get the object back. on failure you get NULL. and listen — any object that memcached_get() hands you? you, the caller, have to release it. it's yours now, you're responsible for it. 🙈

🌈 memcached_mget()

memcached_mget() is for selecting multiple keys at once. for multi-key operations it is always faster to use this one, like genuinely, use it. and it always works asynchronously, that's just its whole energy.

🦋 memcached_fetch_result() — the retrieval arc

to actually get your data after a successful memcached_mget(), you call memcached_fetch_result(). and you keep calling it until it returns a NULL (aka, no more values, we're done here). if you need to bail out in the middle of a memcached_mget() call, you can run a memcached_quit() — though ngl, this is not required. 💁

memcached_fetch_result() fetches an individual value from the server. memcached_mget() must always be called before you use this method — no skipping steps, bestie. you pass in a key and its length to fetch the object, and again you supply three pointer variables that tell you the state of the returned object:

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

success → you get the object. failure → you get NULL. and when all the objects that were found have been returned, MEMCACHED_END is what shows up in that *error value. the final value upon MEMCACHED_END is null. 🌟

also! memcached_fetch_result() is what returns a memcached_result_st structure from a memcached server. that result object is forward compatible with changes to the server — iconic, honestly. for more info go look at the memcached_result_st help. and if you don't pass a result structure in, this function will dynamically allocate one for you. so generous. 💖

🎀 memcached_fetch_execute()

memcached_fetch_execute() is a callback function for result sets. instead of handing the results back to you for processing, it passes each result set straight to the list of functions you provide. here's what gets passed to each of those functions:

• a memcached_st that can be cloned for use inside the called function — it cannot be used directly, okay? clone it. 🙅
• a result set, which does not need to be freed
• a "context" — just a pointer to a memory reference that 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. 🔮

⭐ memcached_mget_execute() and memcached_mget_execute_by_key()

these two are similar to memcached_mget(), except they may trigger the callbacks you supplied with result sets while they're still sending out the queries.

why would you want that? because if you try to perform a really large multiget with memcached_mget(), you may hit a deadlock in the OS kernel 😭 — it will fail to write data to the socket because the input buffer is full. memcached_mget_execute() solves this by processing some of the results before continuing to send out requests. the way that it just... fixes that? obsessed.

heads up: this function is only available in the binary protocol. no binary protocol, no memcached_mget_execute(). 🫡

💜 memcached_get_by_key() and memcached_mget_by_key()

these behave in a similar nature to memcached_get() and memcached_mget(). the difference? they take a master key that's used to determine which server an object was stored on — that's the move when key partitioning was used for storage. 🔑

🚨 the UDP warning 🚨

all of the above functions are not tested when MEMCACHED_BEHAVIOR_USE_UDP has been set. run any of these with that behavior turned on and you'll get MEMCACHED_NOT_SUPPORTED back — or, for the functions that don't return a memcached_return_t, that error function parameter will be set to MEMCACHED_NOT_SUPPORTED. so like... don't. 💀

---

✨ RETURN VALUE ✨

every object you retrieve via memcached_get() or memcached_get_by_key() must be freed with free(3). that's not optional, bestie, that's your civic duty. 🧚

memcached_get() returns NULL on error. and you must look at the value of error to figure out what the actual error was — don't just stare at the NULL and hope for the best. 👑

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

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

---

🌈 SEE ALSO 🌈

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

---

and that's the whole page, bestie!! this one's from libmemcached-awesome, version 1.1, dated Jul 24, 2025 — go forth and fetch responsibly 💖✨🎀🦋