--- name: "memcached_server_add" section: "3" platform: "linux" package: "libmemcached-awesome" version: "1.1.4-4" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/memcached_server_add" --- # memcached\_server\_add(3) libmemcached Documentation ## NAME memcached\_server\_add - libmemcached Documentation ## SYNOPSIS - **#include \** Compile and link with -lmemcached - **uint32\_t memcached\_server\_count(memcached\_st \<#\_CPPv412memcached\_st\> \*ptr)** - **Parameters** **ptr** -- pointer to initialized **memcached\_st** \<#\_CPPv412memcached\_st\> struct - **Returns** number of configured servers - **memcached\_return\_t \<#\_CPPv418memcached\_return\_t\> memcached\_server\_add(memcached\_st \<#\_CPPv412memcached\_st\> \*ptr, const char \*hostname, in\_port\_t port)** - **Parameters** - • **ptr** -- pointer to initialized **memcached\_st** \<#\_CPPv412memcached\_st\> struct - • **hostname** -- hostname or IP address of the TCP server to add - • **port** -- port of the TCP server - **Returns** **memcached\_return\_t** \<#\_CPPv418memcached\_return\_t\> indicating success - **memcached\_return\_t \<#\_CPPv418memcached\_return\_t\> memcached\_server\_add\_udp(memcached\_st \<#\_CPPv412memcached\_st\> \*ptr, const char \*hostname, in\_port\_t port)** - **Parameters** - • **ptr** -- pointer to initialized **memcached\_st** \<#\_CPPv412memcached\_st\> struct - • **hostname** -- hostname or IP address of the UDP server to add - • **port** -- port of the UDP server - **Returns** **memcached\_return\_t** \<#\_CPPv418memcached\_return\_t\> indicating success - **memcached\_return\_t \<#\_CPPv418memcached\_return\_t\> memcached\_server\_add\_unix\_socket(memcached\_st \<#\_CPPv412memcached\_st\> \*ptr, const char \*socket)** - **Parameters** - • **ptr** -- pointer to initialized **memcached\_st** \<#\_CPPv412memcached\_st\> struct - • **socket** -- path to the UNIX socket of the server to add - **Returns** **memcached\_return\_t** \<#\_CPPv418memcached\_return\_t\> indicating success - **memcached\_return\_t \<#\_CPPv418memcached\_return\_t\> memcached\_server\_push(memcached\_st \<#\_CPPv412memcached\_st\> \*ptr, const memcached\_server\_st \*list)** - **Parameters** - • **ptr** -- pointer to initialized **memcached\_st** \<#\_CPPv412memcached\_st\> struct - • **list** -- pre-configured list of servers to push - **Returns** **memcached\_return\_t** \<#\_CPPv418memcached\_return\_t\> indicating success - **const memcached\_instance\_st \*memcached\_server\_by\_key(memcached\_st \<#\_CPPv412memcached\_st\> \*ptr, const char \*key, size\_t key\_length, memcached\_return\_t \<#\_CPPv418memcached\_return\_t\> \*error)** - **Parameters** - • **ptr** -- pointer to initialized **memcached\_st** \<#\_CPPv412memcached\_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** \<#\_CPPv418memcached\_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 \<#\_CPPv412memcached\_st\> \*ptr)** - **Parameters** **ptr** -- pointer to initialized **memcached\_st** \<#\_CPPv412memcached\_st\> struct - **Returns** the instance of the last server for which there was a connection problem - **memcached\_return\_t \<#\_CPPv418memcached\_return\_t\> memcached\_server\_cursor(const memcached\_st \<#\_CPPv412memcached\_st\> \*ptr, const memcached\_server\_fn \*callback, void \*context, uint32\_t number\_of\_callbacks)** - **Parameters** - • **ptr** -- pointer to initialized **memcached\_st** \<#\_CPPv412memcached\_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** \<#\_CPPv418memcached\_return\_t\> indicating success - **typedef memcached\_return\_t \<#\_CPPv418memcached\_return\_t\> (\*memcached\_server\_fn)(const memcached\_st \<#\_CPPv412memcached\_st\> \*ptr, const memcached\_instance\_st \*server, void \*context)** - **Param ptr** pointer to the **memcached\_st** \<#\_CPPv412memcached\_st\> struct - **Param server** pointer to **memcached\_instance\_st** - **Param context** pointer to user supplied context - **Returns** **memcached\_return\_t** \<#\_CPPv418memcached\_return\_t\> indicating success ## DESCRIPTION **libmemcached** performs operations on a list of hosts. The order of these hosts determine routing to keys. Functions are provided to add keys to **memcached\_st** \<#\_CPPv412memcached\_st\> structures. To manipulate lists of servers see **memcached\_server\_st**. **memcached\_server\_count()** provides you a count of the current number of servers being used by a **memcached\_st** \<#\_CPPv412memcached\_st\> structure. **memcached\_server\_add()** pushes a single TCP server into the **memcached\_st** \<#\_CPPv412memcached\_st\> structure. This server will be placed at the end. Duplicate servers are allowed, so duplication is not checked. Executing this function with the **MEMCACHED\_BEHAVIOR\_USE\_UDP** \<#\_CPPv4N20memcached\_behavior\_t26MEMCACHED\_BEHAVIOR\_USE\_UDPE\> behavior set will result in a **MEMCACHED\_INVALID\_HOST\_PROTOCOL** \<#\_CPPv4N18memcached\_return\_t31MEMCACHED\_INVALID\_HOST\_PROTOCOLE\>. **memcached\_server\_add\_udp()** pushes a single UDP server into the **memcached\_st** \<#\_CPPv412memcached\_st\> structure. This server will be placed at the end. Duplicate servers are allowed, so duplication is not checked. Executing this function without setting the **MEMCACHED\_BEHAVIOR\_USE\_UDP** \<#\_CPPv4N20memcached\_behavior\_t26MEMCACHED\_BEHAVIOR\_USE\_UDPE\> behavior will result in a **MEMCACHED\_INVALID\_HOST\_PROTOCOL** \<#\_CPPv4N18memcached\_return\_t31MEMCACHED\_INVALID\_HOST\_PROTOCOLE\>. **memcached\_server\_add\_unix\_socket()** pushes a single UNIX socket into the **memcached\_st** \<#\_CPPv412memcached\_st\> structure. This UNIX socket will be placed at the end. Duplicate servers are allowed, so duplication is not checked. The length of the filename must be one character less than **MEMCACHED\_MAX\_HOST\_LENGTH**. **memcached\_server\_push()** pushes an array of **memcached\_server\_st** into the **memcached\_st** \<#\_CPPv412memcached\_st\> structure. These servers will be placed at the end. Duplicate servers are allowed, so duplication is not checked. A copy is made of structure so the list provided (and any operations on the list) are not saved. **memcached\_server\_by\_key()** allows you to provide a key and retrieve the server which would be used for assignment. **memcached\_server\_get\_last\_disconnect()** returns a pointer to the last server for which there was a connection problem. 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. **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. An error return from any callback will terminate the loop. **memcached\_server\_cursor()** is passed the original caller **memcached\_st** \<#\_CPPv412memcached\_st\> in its current state. ## RETURN VALUE Varies, see particular functions. ## SEE ALSO **[memcached(1)](/memcached/1.md) \** **[libmemcached(3)](/libmemcached/3.md) \** **[memcached\_server\_st(3)](/memcached_server_st/3.md) \** **[memcached\_strerror(3)](/memcached_strerror/3.md) \**