MEMCACHED_SERVER_ST(3)

📦
version 1.1.4 · 12 versions
, in fedora 43

💖 MEMCACHED_SERVER_ST 💖

okay bestie, gather round, because this is the manual page for memcached_server_st(3) from libmemcached-awesome and it is lowkey the whole reason your keys know where to go. it's giving "backstage pass to the server list" energy. let's get into it 🎀

✨ SYNOPSIS ✨

first thing, you gotta bring the header in:

#include <libmemcached/memcached.h>

and bestie, don't forget:

Compile and link with -lmemcached

that's not optional, that's the vibe. 💅

🌸 uint32_t memcached_server_count(memcached_st *ptr)

Parameters

  • ptr — pointer to initialized memcached_st struct

Returns

number of configured servers

🌸 memcached_return_t memcached_server_add(memcached_st *ptr, const char *hostname, in_port_t port)

Parameters

  • ptr — pointer to initialized memcached_st struct
  • hostname — hostname or IP address of the TCP server to add
  • port — port of the TCP server

Returns

memcached_return_t indicating success

🌸 memcached_return_t memcached_server_add_udp(memcached_st *ptr, const char *hostname, in_port_t port)

Parameters

  • ptr — pointer to initialized memcached_st struct
  • hostname — hostname or IP address of the UDP server to add
  • port — port of the UDP server

Returns

memcached_return_t indicating success

🌸 memcached_return_t memcached_server_add_unix_socket(memcached_st *ptr, const char *socket)

Parameters

  • ptr — pointer to initialized memcached_st struct
  • socket — path to the UNIX socket of the server to add

Returns

memcached_return_t indicating success

🌸 memcached_return_t memcached_server_push(memcached_st *ptr, const memcached_server_st *list)

Parameters

  • ptr — pointer to initialized memcached_st struct
  • list — pre-configured list of servers to push

Returns

memcached_return_t indicating success

🌸 const memcached_instance_st *memcached_server_by_key(memcached_st *ptr, const char *key, size_t key_length, memcached_return_t *error)

Parameters

  • ptr — pointer to initialized memcached_st struct
  • key — key to hash and lookup a server
  • key_length — length of key without any terminating zero
  • error — pointer to memcached_return_t indicating success

Returns

the server instance to be used for storing/retrieving key

🌸 const memcached_instance_st *memcached_server_get_last_disconnect(const memcached_st *ptr)

Parameters

  • ptr — pointer to initialized memcached_st struct

Returns

the instance of the last server for which there was a connection problem

🌸 memcached_return_t memcached_server_cursor(const memcached_st *ptr, const memcached_server_fn *callback, void *context, uint32_t number_of_callbacks)

Parameters

  • ptr — pointer to initialized memcached_st struct
  • callback — list of memcached_server_fn to be called for each server instance
  • context — pointer to user supplied context for the callback
  • number_of_callbacks — number of callbacks supplied

Returns

memcached_return_t indicating success

🌸 the callback type itself, icon behavior only

typedef memcached_return_t (*memcached_server_fn)(const memcached_st *ptr, const memcached_instance_st *server, void *context)

Param ptr

pointer to the memcached_st struct

Param server

pointer to memcached_instance_st

Param context

pointer to user supplied context

Returns

memcached_return_t indicating success

💜 DESCRIPTION 💜

so here's the tea, bestie: libmemcached performs operations on a list of hosts. and the order of these hosts? that literally determines routing to keys. the order IS the plot. 📖✨

the functions here are provided so you can add keys to memcached_st structures. and if you wanna manipulate lists of servers, you go look at memcached_server_st. iykyk.

memcached_server_count() hands you a count of the current number of servers being used by a memcached_st structure. it's the "how many besties are we working with" function. 🫶

memcached_server_add() pushes a single TCP server into the memcached_st structure. this server will be placed at the end. and listen — duplicate servers are allowed, so duplication is not checked. no vibe check on dupes, periodt.

🚨 warning bestie: executing this function with the MEMCACHED_BEHAVIOR_USE_UDP behavior set will result in a MEMCACHED_INVALID_HOST_PROTOCOL. do not do this. i'm begging. 😭

memcached_server_add_udp() pushes a single UDP server into the memcached_st structure. this server will be placed at the end. duplicate servers are allowed, so duplication is not checked. again with the no-dupe-checking, we love a consistent queen.

🚨 and the mirror-image warning: executing this function without setting the MEMCACHED_BEHAVIOR_USE_UDP behavior will result in a MEMCACHED_INVALID_HOST_PROTOCOL. yes really. it's giving strict.

memcached_server_add_unix_socket() pushes a single UNIX socket into the memcached_st structure. this UNIX socket will be placed at the end. duplicate servers are allowed, so duplication is not checked.

⚠️ also, the length of the filename must be one character less than MEMCACHED_MAX_HOST_LENGTH. that's the rule, don't fight it. 💅

memcached_server_push() pushes an array of memcached_server_st into the memcached_st structure. these servers will be placed at the end. duplicate servers are allowed, so duplication is not checked. and here's the cute part: a copy is made of structure so the list provided (and any operations on the list) are not saved. it's a snapshot, not a situationship. 📸

memcached_server_by_key() lets you provide a key and retrieve the server which would be used for assignment. it's the "who's getting this one" oracle. 🔮

memcached_server_get_last_disconnect() returns a pointer to the last server for which there was a connection problem. important nuance bestie: it does not mean this particular server is currently dead — but if the library is reporting a server is, the returned server is a very good candidate. like, prime suspect energy. 🔍

memcached_server_cursor() takes a memcached_st and loops through the list of hosts currently in the cursor, calling the list of callback functions provided. you can optionally pass in a value via context which will be provided to each callback function. and if any callback returns an error, that terminates the loop — no second chances, it's over. 🛑

🌟 one more detail: memcached_server_cursor() is passed the original caller memcached_st in its current state.

🌈 RETURN VALUE 🌈

varies, bestie. go read the particular functions. 💀

🦋 SEE ALSO 🦋

and that's the whole page, no crumbs left. this was libmemcached-awesome version 1.1, dated Jul 24, 2025 — so go forth and add your servers in the correct order, bestie. the routing depends on you and you're the main character now. 👑💖✨

📦 where this page comes from