Memcac...ed_auto(3pm)

📦
version 1.001801 · 7 versions
, in ubuntu stonking

✨ NAME ✨

okay bestie, welcome to the counter headquarters 💅 this page — which lives in the 3pm slot of the User Contributed Perl Documentation, underneath the whole C Client Library for memcached situation — is all about four little functions that do one extremely specific thing:

  • memcached_increment
  • memcached_decrement
  • memcached_increment_with_initial
  • memcached_decrement_with_initial

and the thing they do is: Manipulate counters. that's it. that's the job. no notes. 🎀

🌸 LIBRARY 🌸

this is the C Client Library for memcached, aka libmemcached, and you link it with -lmemcached. iconic behavior honestly 🫶

✨ SYNOPSIS ✨

first things first, you gotta invite the header to the party:

#include <memcached.h>

and now, the full cast — all eight of them, not a single one skipped, because we don't do that here 💖:

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

memcached_return_t
  memcached_decrement (memcached_st *ptr,
                       const char *key, size_t key_length,
                       unsigned int 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 *master_key, size_t master_key_length,
                              const char *key, size_t key_length,
                              unsigned int offset,
                              uint64_t *value);

memcached_return_t
  memcached_decrement_by_key (memcached_st *ptr,
                              const char *master_key, size_t master_key_length,
                              const char *key, size_t key_length,
                              unsigned int offset,
                              uint64_t *value);

memcached_return_t
  memcached_increment_with_initial_by_key (memcached_st *ptr,
                                           const char *master_key,
                                           size_t master_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 *master_key,
                                           size_t master_key_length,
                                           const char *key,
                                           size_t key_length,
                                           uint64_t offset,
                                           uint64_t initial,
                                           time_t expiration,
                                           uint64_t *value);

look at that lineup. main character energy from every single one of them 👑

💜 DESCRIPTION 💜

so like. memcached(1) servers can increment and decrement keys — that's the whole vibe. and before you ask, no: overflow and underflow are ✨not✨ detected. the server is not your mom, it will not catch you. 🙈

but that's also the slay of it, because it means you can use memcached to generate shared sequences of values. a lil collab counter. very cute. very useful. periodt. 💅

🦋 the increment / decrement duo 🦋

  • memcached_increment() — takes a key and a keylength, and bumps the value up by whatever offset you hand it. then the new value gets handed right back to you through that unsigned int value pointer you passed in. 🎀
  • memcached_decrement() — takes a key and a keylength, and drops the value down by the offset you handed it. then the value comes back through that same unsigned int value pointer you passed in. 🌸

🌈 the "_with_initial" girlies 🌈

these two are the same deal but they also handle the "what if she doesn't exist yet" moment, and honestly? that's the whole plot twist:

  • memcached_increment_with_initial() — takes a key and keylength, and increments the value by the offset you passed it. BUT — and this is the important part — if the object specified by key does not exist, one of two things may happen:
    1. If the expiration value is MEMCACHED_EXPIRATION_NOT_ADD, the operation will fail. sorry bestie 😭
    2. For all other expiration values, the operation will succeed by seeding the value for that key with an initial value, set to expire with the provided expiration time. and heads up: the flags will be set to zero.

The value is then returned via the unsigned int value pointer you pass to it. ✨

  • memcached_decrement_with_initial() — takes a key and keylength, and decrements the value by the offset you passed it. same energy for the missing-key situation — if the object specified by key does not exist, one of two things may happen:
    1. If the expiration value is MEMCACHED_EXPIRATION_NOT_ADD, the operation will fail. 🫠
    2. For all other expiration values, the operation will succeed by seeding the value for that key with an initial value, set to expire with the provided expiration time. flags get set to zero, no cap.

The value is then returned via the unsigned int value pointer you pass to it. 💖

👑 the master-key equivalents 👑

memcached_increment_by_key(), memcached_decrement_by_key(), memcached_increment_with_initial_by_key(), and memcached_decrement_with_initial_by_key() are the master key equivalents of all of the above. yes, that means they take a master_key and a master_key_length on top of everything else — they're the extra ones, and they ate. 🔥

⭐ RETURN ⭐

you get back a value of type memcached_return_t. on success that value will be MEMCACHED_SUCCESS 🎉

and if you ever need to turn that number into a readable string, hit up memcached_strerror() — she translates. iykyk. 🌟

💖 HOME 💖

want more lore? the full source of truth lives here:

<https://launchpad.net/libmemcached>

go, read, obsess. 🧚

🌸 AUTHOR 🌸

this whole thing was authored by Brian Aker, <brian@tangent.org>. thank you for your service king 👑

🦋 SEE ALSO 🦋

the extended universe, all linked up:

and that's the tea, bestie 🍓 this lil tour was brought to you by perl v5.42.3, dated 2026-08-19, riding in under the Memcac...ed_auto(3pm) banner. stay incrementing, stay slaying, and remember: you're the main character of your own counter 💅✨💖

📦 where this page comes from