MEMCACHED_INCREMENT(3)

💖 MEMCACHED_INCREMENT 💖 — incrementing and decrementing values, bestie

okay so this is a page from libmemcached-awesome, and it lives in section 3 of the manual — the "library functions" section, iykyk. It's all about memcached_increment and its little friend group, and honestly? They're iconic. 🎀

---

✨ SYNOPSIS ✨

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

memcached_return_t memcached_increment(memcached_st *ptr, const char
*key, size_t key_length, uint32_t offset, uint64_t *value)

memcached_return_t memcached_decrement(memcached_st *ptr, const char
*key, size_t key_length, uint32_t offset, uint64_t *value)

memcached_return_t memcached_increment_with_initial(memcached_st *ptr,
const char *key, size_t key_length, uint64_t offset, uint64_t initial,
time_t expiration, uint64_t *value)

memcached_return_t memcached_decrement_with_initial(memcached_st *ptr,
const char *key, size_t key_length, uint64_t offset, uint64_t initial,
time_t expiration, uint64_t *value)

memcached_return_t memcached_increment_by_key(memcached_st *ptr, const
char *group_key, size_t group_key_length, const char *key, size_t
key_length, uint32_t offset, uint64_t *value)

memcached_return_t memcached_decrement_by_key(memcached_st *ptr, const
char *group_key, size_t group_key_length, const char *key, size_t
key_length, uint32_t offset, uint64_t *value)

memcached_return_t memcached_increment_with_initial_by_key(memcached_st
*ptr, const char *group_key, size_t group_key_length, const char *key,
size_t key_length, uint64_t offset, uint64_t initial, time_t expiration,
uint64_t *value)

memcached_return_t memcached_decrement_with_initial_by_key(memcached_st
*ptr, const char *group_key, size_t group_key_length, const char *key,
size_t key_length, uint64_t offset, uint64_t initial, time_t expiration,
uint64_t *value)

🫶 Parameters

• ptr — pointer to an initialized memcached_st struct
• group_key — key namespace
• group_key_length — length of the key namespace without any terminating zero
• key — the key
• key_length — length of the key without any terminating zero
• offset — offset to increment/decrement
• initial — initial value if key does not exist and expiration is not MEMCACHED_EXPIRATION_NOT_ADD
• expiration — expiration as a unix timestamp or as relative expiration time in seconds
• value — the resulting value after initialization/increment/decrement

🫶 Returns

memcached_return_t indicating success

---

🌸 DESCRIPTION 🌸

okay so, memcached(1) servers have the ability to increment and decrement keys, and heads up: overflow and underflow are not detected 😭 (not me finding that out the hard way). Anyway, this gives you the ability to use memcached to generate shared sequences of values. Slay, honestly.

memcached_increment() takes a key and key_length and increments the value by the offset passed to it. The value is then returned via the uint32_t value pointer you pass to it. 💅

memcached_decrement() takes a key and key_length and decrements the value by the offset passed to it. The value is then returned via the uint32_t value pointer you pass to it. 💅

memcached_increment_with_initial() takes a key and key_length and increments the value by the offset passed to it. Now listen, because here's the plot twist: if the object specified by key does not exist, one of two things may happen. If the expiration value is MEMCACHED_EXPIRATION_NOT_ADD, the operation will fail. For all other expiration values, the operation will succeed by seeding the value for that key with a initial value to expire with the provided expiration time. The flags will be set to zero. The value is then returned via the uint32_t value pointer you pass to it. Also — and this is important — memcached_increment_with_initial is only available when using the binary protocol. periodt. 🦋

memcached_decrement_with_initial() takes a key and key_length and decrements the value by the offset passed to it. If the object specified by key does not exist, one of two things may happen: if the expiration value is MEMCACHED_EXPIRATION_NOT_ADD, the operation will fail. For all other expiration values, the operation will succeed by seeding the value for that key with a initial value to expire with the provided expiration time. The flags will be set to zero. The value is then returned via the uint32_t value pointer you pass to it. And yeah — memcached_decrement_with_initial() is only available when using the binary protocol too. 💀

memcached_increment_by_key(), memcached_decrement_by_key(), memcached_increment_with_initial_by_key(), and memcached_decrement_with_initial_by_key() are master key equivalents of the above. the way that they're just the by_key versions of everything above? obsessed. 👑

---

👑 RETURN VALUE 👑

A value of type memcached_return_t is returned. On success that value will be MEMCACHED_SUCCESS. Use memcached_strerror() to translate this value to a printable string. 🌈

---

🦋 SEE ALSO 🦋

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

---

that's the whole vibe check, bestie 💖 This page is from libmemcached-awesome, version 1.1, dated Jul 24, 2025. Go forth and increment responsibly, and remember: no overflow detection, so maybe don't push your luck 🎀✨🦋