MEMCACHED_GET_BY_KEY(3)

💖 MEMCACHED_GET_BY_KEY 💖

okay bestie, come sit with me, because this is the MEMCACHED_GET_BY_KEY(3) page from libmemcached-awesome and it's literally the whole "get stuff back out of memcached" saga. grab a boba, we're doing this together 🧋✨

---

🌸 NAME 🌸

memcached_get_by_key — Retrieving data from the server 👑 (yes that's the whole name section, it's giving minimalist icon)

---

✨ SYNOPSIS ✨

first things first, you gotta pull in the header and link the lib:

#include <libmemcached/memcached.h>

Compile and link with -lmemcached

and here's the whole friend group of functions, 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() is your go-to for grabbing one single value off the server. you hand it a key and the key's length, that's the vibe check. but here's the thing — you also gotta pass in three pointer variables so you can see the state of whatever comes back:

• a uint32_t pointer that holds whatever flags you stored along with the value 🏷️
• a size_t pointer that gets filled with the size of the object 📏
• a memcached_return_t pointer to hold any error 🚨

on success you get the object back, on failure you get NULL. and the caller application MUST release any object returned by memcached_get() — that's on you, bestie, don't leak it 💀

memcached_mget() is the girl who does multiple keys at once. for multi-key operations it's always faster to use this one, periodt. and she always works asynchronously — that's just her nature ✨

so after memcached_mget() succeeds, to actually get the data you have to call memcached_fetch_result(). keep calling it until it returns a NULL (that's the "no more values" signal 🚫). and if you need to bail out in the middle of a memcached_mget() call, you can run a memcached_quit() — though tbh this is not required. do it for the drama if you want 💅

memcached_fetch_result() fetches an individual value from the server. memcached_mget() must always be called before you use this method — no skipping steps. you pass in a key and its length to fetch the object. and yeah, same three pointer variables situation:

• a uint32_t pointer for the flags you stored with the value 🏷️
• a size_t pointer that gets filled with the size of the object 📏
• a memcached_return_t pointer to hold any error 🚨

object comes back on success, NULL on failure. MEMCACHED_END is returned by the *error value when 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. this result object is forward compatible with changes to the server 🌈 — for more info please refer to the memcached_result_st help. and fun fact: if you don't pass one in, this function will dynamically allocate a result structure for you 🎁

memcached_fetch_execute() is a callback function for result sets. instead of handing results back to you to process, it passes each result set to the list of functions you provide 👯‍♀️. what it hands your function:

• a memcached_st that can be cloned for use in the called function — it cannot be used directly 🚫
• a result set that does not need to be freed (love that for us)
• a "context" — just a pointer to a memory reference you supply 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 👀 (future icon behaviour)

memcached_mget_execute() and memcached_mget_execute_by_key() 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 perform a really large multiget with memcached_mget() you may encounter 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 problem by processing some of the results before continuing to send out requests. 🫶

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

memcached_get_by_key() and memcached_mget_by_key() behave in a similar nature as memcached_get() and memcached_mget(). the difference? they take a master key 🔑 that's used for determining which server an object was stored on, if key partitioning was used for storage. it's the "which locker did I put this in" energy.

💀 all of the above functions are not tested when MEMCACHED_BEHAVIOR_USE_UDP has been set. executing any of these functions with this behavior on will result in MEMCACHED_NOT_SUPPORTED being returned — or, for those functions which do not return a memcached_return_t, the error function parameter will be set to MEMCACHED_NOT_SUPPORTED. so like, don't 🙈

---

💅 RETURN VALUE 💅

all objects retrieved via memcached_get() or memcached_get_by_key() must be freed with free(3). no exceptions, bestie, that's the law 🧹

memcached_get() will return NULL on error. you must look at the value of error to determine what the actual error was — NULL alone is not telling you the tea 🔍

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)

---

and that's the whole page, you ate that 🍓✨ this was libmemcached-awesome, version 1.1, dated Jul 24, 2025 — mwah, go forth and cache responsibly 💖🦋🎀