From 54be7f67e284406a2975ab67aebf5850268f5718 Mon Sep 17 00:00:00 2001 From: Michael Wallner Date: Thu, 13 Aug 2020 13:07:24 +0200 Subject: [PATCH] docs: flush libmemcached --- docs/source/libmemcached.rst | 1 - .../libmemcached/index_advanced_daemon.rst | 1 - .../libmemcached/index_advanced_stats.rst | 1 + docs/source/libmemcached/memcached_get.rst | 4 +- .../libmemcached/memcached_server_st.rst | 47 +++++++--- .../source/libmemcached/memcached_servers.rst | 91 +++++++++++++++---- docs/source/libmemcached/memcached_set.rst | 65 +++++++++---- .../memcached_set_encoding_key.rst | 29 ++++-- docs/source/libmemcached/memcached_stats.rst | 86 +++++++++++++++--- .../libmemcached/memcached_strerror.rst | 7 +- docs/source/libmemcached/memcached_touch.rst | 28 +++++- .../libmemcached/memcached_user_data.rst | 36 ++++---- .../libmemcached/memcached_verbosity.rst | 20 ++-- .../source/libmemcached/memcached_version.rst | 17 +++- 14 files changed, 321 insertions(+), 112 deletions(-) diff --git a/docs/source/libmemcached.rst b/docs/source/libmemcached.rst index dba00583..6c842e81 100644 --- a/docs/source/libmemcached.rst +++ b/docs/source/libmemcached.rst @@ -139,7 +139,6 @@ SEE ALSO .. only:: man :manpage:`memcached(1)` - :manpage:`libmemcached_configuration(3)` :manpage:`libmemcached_examples(3)` diff --git a/docs/source/libmemcached/index_advanced_daemon.rst b/docs/source/libmemcached/index_advanced_daemon.rst index 61783320..a8360f75 100644 --- a/docs/source/libmemcached/index_advanced_daemon.rst +++ b/docs/source/libmemcached/index_advanced_daemon.rst @@ -7,4 +7,3 @@ Affecting the memcached Daemon memcached_dump memcached_flush memcached_verbosity - memcached_version diff --git a/docs/source/libmemcached/index_advanced_stats.rst b/docs/source/libmemcached/index_advanced_stats.rst index 9e1c7d8e..8ad72feb 100644 --- a/docs/source/libmemcached/index_advanced_stats.rst +++ b/docs/source/libmemcached/index_advanced_stats.rst @@ -6,3 +6,4 @@ Statistics memcached_analyze memcached_stats + memcached_version diff --git a/docs/source/libmemcached/memcached_get.rst b/docs/source/libmemcached/memcached_get.rst index d14a1a63..aa8845dc 100644 --- a/docs/source/libmemcached/memcached_get.rst +++ b/docs/source/libmemcached/memcached_get.rst @@ -11,13 +11,13 @@ SYNOPSIS .. function:: char * memcached_get (memcached_st *ptr, const char *key, size_t key_length, size_t *value_length, uint32_t *flags, memcached_return_t *error) -.. function:: memcached_return_t memcached_mget (memcached_st *ptr, const char * const *keys, const size_t *key_length, size_t number_of_keys) +.. function:: memcached_return_t memcached_mget (memcached_st *ptr, const char * const *keys, const size_t *key_length, size_t number_of_keys) .. function:: 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) .. function:: 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) -.. function:: memcached_return_t memcached_fetch_execute (memcached_st *ptr, memcached_execute_fn *callback, void *context, uint32_t number_of_callbacks) +.. function:: memcached_return_t memcached_fetch_execute (memcached_st *ptr, memcached_execute_fn *callback, void *context, uint32_t number_of_callbacks) .. function:: 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) diff --git a/docs/source/libmemcached/memcached_server_st.rst b/docs/source/libmemcached/memcached_server_st.rst index 1ca82c1c..b99b420e 100644 --- a/docs/source/libmemcached/memcached_server_st.rst +++ b/docs/source/libmemcached/memcached_server_st.rst @@ -13,21 +13,28 @@ SYNOPSIS .. c:type:: struct memcached_server_st *memcached_server_list_st -.. function:: const memcached_instance_st * memcached_server_list (memcached_st *ptr) - - :param ptr: pointer to initialized `memcached_st` struct - :returns: list of `memcached_instance_st` objects - .. function:: void memcached_server_list_free (memcached_server_list_st list) - :param list: + :param list: instance of initialized `memcached_server_list_st` object .. function:: memcached_server_list_st memcached_server_list_append (memcached_server_list_st list, const char *hostname, in_port_t port, memcached_return_t *error) + :param list: instance of an existing `memcached_server_list_st` or nullptr to create one + :param hostname: the hostname or path to the socket, defaults to localhost if null + :param port: the port to use, defaults to 11211 if 0 + :param error: pointer to store any `memcached_return_t` error indicating success + :returns: new instance of `memcached_server_list_st` on success or nullptr on failure + .. function:: uint32_t memcached_server_list_count (memcached_server_list_st list) + :param list: instance of `memcached_server_list_st` + :returns: count of servers in the list + .. function:: const char *memcached_server_error (const memcached_instance_st * instance) + :param instance: pointer to an initialized `memcached_instance_st` object + :returns: last error message sent from the server to the client + .. function:: void memcached_server_error_reset (const memcached_instance_st * list) .. deprecated:: 0.39 @@ -36,16 +43,20 @@ SYNOPSIS .. deprecated:: 0.39 + See `memcached`. + DESCRIPTION ----------- -libmemcached(3) operates on a list of hosts which are stored in +`libmemcached` operates on a list of hosts which are stored in :type:`memcached_server_st` structures. You should not modify these structures directly. Functions are provided to modify these structures. -:func:`memcached_server_list` is used to provide an array of all defined hosts. This was incorrectly documented as "requiring free" up till version 0.39. +:func:`memcached_server_list` is used to provide an array of all defined hosts. +This was incorrectly documented as "requiring free" up till version 0.39. -:func:`memcached_server_list_free` deallocates all memory associated with the array of :type:`memcached_server_st` that you passed to it. +:func:`memcached_server_list_free` deallocates all memory associated with the +array of :type:`memcached_server_st` that you passed to it. :func:`memcached_server_list_append` adds a server to the end of a :type:`memcached_server_st` array. On error null will be returned and the @@ -54,10 +65,12 @@ port of a memcached server. DEPRECATED :func:`memcached_servers_parse`, please see :func:`memcached` -:func:`memcached_server_error` can be used to look at the text of the last error message sent by the server to to the client. +:func:`memcached_server_error` can be used to look at the text of the last +error message sent by the server to to the client. Before version 0.39 theses functions used a memcached_server_st \*. In 0.39 -memcached_server_st \* was aliased to :type:`memcached_server_list_st`. This was done for a style reason to help clean up some concepts in the code. +memcached_server_st \* was aliased to :type:`memcached_server_list_st`. +This was done for a style reason to help clean up some concepts in the code. RETURN VALUE ------------ @@ -69,4 +82,14 @@ SEE ALSO .. only:: man - :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)` + :manpage:`memcached(1)` + :manpage:`libmemcached(3)` + :manpage:`memcached_servers(3)` + :manpage:`memcached_strerror(3)` + +.. only:: html + + * :manpage:`memcached(1)` + * :doc:`../libmemcached` + * :doc:`memcached_servers` + * :doc:`memcached_strerror` diff --git a/docs/source/libmemcached/memcached_servers.rst b/docs/source/libmemcached/memcached_servers.rst index ebac5fbc..2fefb376 100644 --- a/docs/source/libmemcached/memcached_servers.rst +++ b/docs/source/libmemcached/memcached_servers.rst @@ -1,54 +1,101 @@ -Manipulate the server information stored in memcached_st -======================================================== +Managing the servers used by memcached_st +========================================= SYNOPSIS -------- #include - -.. type:: memcached_server_fn + Compile and link with -lmemcached .. function:: uint32_t memcached_server_count (memcached_st *ptr) + :param ptr: pointer to initialized `memcached_st` struct + :returns: number of configured servers + .. function:: memcached_return_t memcached_server_add (memcached_st *ptr, const char *hostname, in_port_t port) + :param ptr: pointer to initialized `memcached_st` struct + :param hostname: hostname or IP address of the TCP server to add + :param port: port of the TCP server + :returns: `memcached_return_t` indicating success + .. function:: memcached_return_t memcached_server_add_udp (memcached_st *ptr, const char *hostname, in_port_t port) + :param ptr: pointer to initialized `memcached_st` struct + :param hostname: hostname or IP address of the UDP server to add + :param port: port of the UDP server + :returns: `memcached_return_t` indicating success + .. function:: memcached_return_t memcached_server_add_unix_socket (memcached_st *ptr, const char *socket) + :param ptr: pointer to initialized `memcached_st` struct + :param socket: path to the UNIX socket of the server to add + :returns: `memcached_return_t` indicating success + .. function:: memcached_return_t memcached_server_push (memcached_st *ptr, const memcached_server_st *list) + :param ptr: pointer to initialized `memcached_st` struct + :param list: pre-configured list of servers to push + :returns: `memcached_return_t` indicating success + .. function:: const memcached_instance_st * memcached_server_by_key (memcached_st *ptr, const char *key, size_t key_length, memcached_return_t *error) + :param ptr: pointer to initialized `memcached_st` struct + :param key: key to hash and lookup a server + :param key_length: length of `key` without any terminating zero + :param error: pointer to `memcached_return_t` indicating success + :returns: the server instance to be used for storing/retrieving `key` + .. function:: const memcached_instance_st * memcached_server_get_last_disconnect (const memcached_st *ptr) + :param ptr: pointer to initialized `memcached_st` struct + :returns: the instance of the last server for which there was a connection problem + .. function:: memcached_return_t memcached_server_cursor(const memcached_st *ptr, const memcached_server_fn *callback, void *context, uint32_t number_of_callbacks) -compile and link with -lmemcached + :param ptr: pointer to initialized `memcached_st` struct + :param callback: list of `memcached_server_fn` to be called for each server instance + :param context: pointer to user supplied context for the callback + :param number_of_callbacks: number of callbacks supplied + :returns: `memcached_return_t` indicating success + +.. type:: 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 ----------- `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 structures. To manipulate lists of servers see -memcached_server_st(3). +`memcached_st` structures. To manipulate lists of servers see +`memcached_server_st`. :func:`memcached_server_count` provides you a count of the current number of servers being used by a :type:`memcached_st` structure. -:func:`memcached_server_add` pushes a single TCP server into the :type:`memcached_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` behavior set will result in a `MEMCACHED_INVALID_HOST_PROTOCOL`. +:func:`memcached_server_add` pushes a single TCP server into the +:type:`memcached_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` behavior set will result in +a `MEMCACHED_INVALID_HOST_PROTOCOL`. -:func:`memcached_server_add_udp` pushes a single UDP server into the :type:`memcached_st` structure. This server will be placed at the end. Duplicate -servers are allowed, so duplication is not checked. Executing this function with out setting the `MEMCACHED_BEHAVIOR_USE_UDP` behavior will result in a +:func:`memcached_server_add_udp` pushes a single UDP server into the +:type:`memcached_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` behavior will result in a `MEMCACHED_INVALID_HOST_PROTOCOL`. -:func:`memcached_server_add_unix_socket` pushes a single UNIX socket into the :type:`memcached_st` structure. This UNIX socket will be placed at the end. +:func:`memcached_server_add_unix_socket` pushes a single UNIX socket into the +:type:`memcached_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`. -:func:`memcached_server_push` pushes an array of :type:`memcached_server_st` into the :type:`memcached_st` structure. These servers will be placed at +:func:`memcached_server_push` pushes an array of :type:`memcached_server_st` +into the :type:`memcached_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. @@ -65,7 +112,9 @@ is, the returned server is a very good candidate. 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. :func:`memcached_server_cursor` is passed the original caller :type:`memcached_st` in its current state. +return from any callback will terminate the loop. +:func:`memcached_server_cursor` is passed the original caller +:type:`memcached_st` in its current state. RETURN VALUE ------------ @@ -77,6 +126,14 @@ SEE ALSO .. only:: man - :manpage:`memcached(1)` - :manpage:`libmemcached(3)` - :manpage:`memcached_strerror(3)` + :manpage:`memcached(1)` + :manpage:`libmemcached(3)` + :manpage:`memcached_server_st(3)` + :manpage:`memcached_strerror(3)` + +.. only:: html + + * :manpage:`memcached(1)` + * :doc:`../libmemcached` + * :doc:`memcached_server_st` + * :doc:`memcached_strerror` diff --git a/docs/source/libmemcached/memcached_set.rst b/docs/source/libmemcached/memcached_set.rst index 3daf5b6b..f887109f 100644 --- a/docs/source/libmemcached/memcached_set.rst +++ b/docs/source/libmemcached/memcached_set.rst @@ -24,41 +24,59 @@ SYNOPSIS DESCRIPTION ----------- -:func:`memcached_set`, :func:`memcached_add`, and :func:`memcached_replace` are all used to store information on the server. All methods take a key, and its length to store the object. Keys are currently limited to 250 characters when using either a version of memcached(1) which is 1.4 or below, or when using the text protocol. You must supply both a value and a length. Optionally you -store the object. Keys are currently limited to 250 characters by the +:func:`memcached_set`, :func:`memcached_add`, and :func:`memcached_replace` are +all used to store information on the server. All methods take a key, and its +length to store the object. Keys are currently limited to 250 characters when +using either a version of :manpage:`memcached(1)` which is 1.4 or below, or when +using the text protocol. You must supply both a value and a length. Optionally +you store the object. Keys are currently limited to 250 characters by the memcached(1) server. You must supply both a value and a length. Optionally you -may test an expiration time for the object and a 16 byte value (it is meant to be used as a bitmap). "flags" is a 4byte space that is stored alongside of the main value. Many sub libraries make use of this field, so in most cases users should avoid making use of it. +may test an expiration time for the object and a 16 byte value (it is meant to +be used as a bitmap). "flags" is a 4byte space that is stored alongside of the +main value. Many sub libraries make use of this field, so in most cases users +should avoid making use of it. :func:`memcached_set` will write an object to the server. If an object already exists it will overwrite what is in the server. If the object does not exist it will be written. If you are using the non-blocking mode this function will always return true unless a network error occurs. -:func:`memcached_replace` replaces an object on the server. If the object is not found on the server an error occurs. +:func:`memcached_replace` replaces an object on the server. If the object is not +found on the server an error occurs. -:func:`memcached_add` adds an object to the server. If the object is found on the server an error occurs, otherwise the value is stored. +:func:`memcached_add` adds an object to the server. If the object is found on +the server an error occurs, otherwise the value is stored. -:func:`memcached_set_by_key`, :func:`memcached_add_by_key`, and :func:`memcached_replace_by_key` methods all behave in a similar method as the non +:func:`memcached_set_by_key`, :func:`memcached_add_by_key`, and +:func:`memcached_replace_by_key` methods all behave in a similar method as the non key methods. The difference is that they use their group_key parameter to map objects to particular servers. -If you are looking for performance, :func:`memcached_set` with non-blocking IO is the fastest way to store data on the server. +If you are looking for performance, :func:`memcached_set` with non-blocking IO +is the fastest way to store data on the server. -All of the above functions are tested with the `MEMCACHED_BEHAVIOR_USE_UDP` behavior enabled. However, when using these operations with this behavior +All of the above functions are tested with the `MEMCACHED_BEHAVIOR_USE_UDP` +behavior enabled. However, when using these operations with this behavior on, there are limits to the size of the payload being sent to the server. The reason for these limits is that the Memcached Server does not allow multi-datagram requests and the current server implementation sets a datagram -size to 1400 bytes. Due to protocol overhead, the actual limit of the user supplied data is less than 1400 bytes and depends on the protocol in use as, well as the operation being -executed. When running with the binary protocol, `MEMCACHED_BEHAVIOR_BINARY_PROTOCOL`, the size of the key,value, flags and expiry combined may not -exceed 1368 bytes. When running with the ASCII protocol, the exact limit fluctuates depending on which function is being executed and whether the function is a cas operation or not. For non-cas ASCII set operations, there are at least -1335 bytes available to split among the key, key_prefix, and value; for cas -ASCII operations there are at least 1318 bytes available to split among the key, key_prefix and value. If the total size of the command, including overhead, -exceeds 1400 bytes, a `MEMCACHED_WRITE_FAILURE` will be returned. +size to 1400 bytes. Due to protocol overhead, the actual limit of the user +supplied data is less than 1400 bytes and depends on the protocol in use, as +well as the operation being executed. When running with the binary protocol, +`MEMCACHED_BEHAVIOR_BINARY_PROTOCOL`, the size of the key,value, flags and +expiry combined may not exceed 1368 bytes. When running with the ASCII protocol, +the exact limit fluctuates depending on which function is being executed and +whether the function is a cas operation or not. For non-cas ASCII set operations, +there are at least 1335 bytes available to split among the key, key_prefix, and +value; for cas ASCII operations there are at least 1318 bytes available to split +among the key, key_prefix and value. If the total size of the command, including +overhead, exceeds 1400 bytes, a `MEMCACHED_WRITE_FAILURE` will be returned. RETURN VALUE ------------ All methods return a value of type `memcached_return_t`. + On success the value will be `MEMCACHED_SUCCESS`. Use :func:`memcached_strerror` to translate this value to a printable string. @@ -70,10 +88,17 @@ SEE ALSO .. only:: man - :manpage:`memcached(1)` - :manpage:`libmemcached(3)` - :manpage:`memcached_strerror(3)` - :manpage:`memcached_prepend(3)` - :manpage:`memcached_append(3)` - :manpage:`memcached_cas(3)` + :manpage:`memcached(1)` + :manpage:`libmemcached(3)` + :manpage:`memcached_strerror(3)` + :manpage:`memcached_prepend(3)` + :manpage:`memcached_append(3)` + :manpage:`memcached_cas(3)` + +.. only:: html + * :manpage:`memcached(1)` + * :doc:`../libmemcached` + * :doc:`memcached_strerror` + * :doc:`memcached_auto` + * :doc:`memcached_cas` diff --git a/docs/source/libmemcached/memcached_set_encoding_key.rst b/docs/source/libmemcached/memcached_set_encoding_key.rst index 38ddba09..95e3e32f 100644 --- a/docs/source/libmemcached/memcached_set_encoding_key.rst +++ b/docs/source/libmemcached/memcached_set_encoding_key.rst @@ -1,34 +1,45 @@ Set encryption key ================== -.. index:: object: memcached_st - SYNOPSIS -------- #include + Compile and link with -lmemcached -.. function:: void memcached_set_encoding_key (memcached_st *ptr, const char *string, const size_t string_length) +.. function:: memcached_return_t memcached_set_encoding_key (memcached_st *ptr, const char *str, const size_t length) -Compile and link with -lmemcached + :param ptr: pointer to initialized `memcached_st` struct + :param str: the key to use + :param length: the length of `key` without any terminating zero + :returns: `memcached_return_t` indicating success DESCRIPTION ----------- -:func:`memcached_set_encoding_key` sets the key that will be used to encrypt and decrypt data as it is sent and received from the server. +:func:`memcached_set_encoding_key` sets the key that will be used to encrypt and +decrypt data as it is sent and received from the server. Currently only AES is is supported. RETURN VALUE ------------ -A value of type :type:`memcached_return_t` is returned On success that value -will be `MEMCACHED_SUCCESS`. Use :func:`memcached_strerror` to -translate this value to a printable string. +A value of type :type:`memcached_return_t` is returned. +On success that value will be `MEMCACHED_SUCCESS`. +Use :func:`memcached_strerror` to translate this value to a printable string. SEE ALSO -------- .. only:: man - :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)` + :manpage:`memcached(1)` + :manpage:`libmemcached(3)` + :manpage:`memcached_strerror(3)` + +.. only:: html + + * :manpage:`memcached(1)` + * :doc:`../libmemcached` + * :doc:`memcached_strerror` diff --git a/docs/source/libmemcached/memcached_stats.rst b/docs/source/libmemcached/memcached_stats.rst index 496b06b6..745926b6 100644 --- a/docs/source/libmemcached/memcached_stats.rst +++ b/docs/source/libmemcached/memcached_stats.rst @@ -9,44 +9,93 @@ SYNOPSIS -------- #include + Compile and link with -lmemcached -.. type:: memcached_stat_st +.. type:: struct memcached_stat_st memcached_stat_st .. type:: memcached_return_t (*memcached_stat_fn)(const memcached_instance_st * server, const char *key, size_t key_length, const char *value, size_t value_length, void *context) + :param server: pointer to the `memcached_instance_st` being stat'ed + :param key: the current key + :param key_length: the length of the `key` without any terminating zero + :param value: the value read + :param value_length: the length of the value without any terminating zero + :param context: pointer to the user supplied context + :returns: `memcached_return_t` indicating success + .. function:: memcached_stat_st *memcached_stat (memcached_st *ptr, char *args, memcached_return_t *error) + :param ptr: pointer to an initialized `memcached_st` struct + :param args: particular state object to query + :param error: pointer to `memcached_return_t` indicating success + :returns: array of `memcached_stat_st` objects for all available servers + .. function:: memcached_return_t memcached_stat_servername (memcached_stat_st *stat, char *args, const char *hostname, in_port_t port) + :param stat: pointer to a `memcached_stat_st` struct to fill + :param args: particular state object to query + :param hostname: the hostname or IP address of the server to stat + :param port: the port of the server to stat + :returns: `memcached_return_t` indicating success + .. function:: char * memcached_stat_get_value (memcached_st *ptr, memcached_stat_st *stat, const char *key, memcached_return_t *error) + :param ptr: pointer to initialized `memcached_st` struct + :param stat: pointer to initialized `memcached_stat_st` struct + :param key: the statistic to query + :param error: pointer to `memcached_return_t` indicating success + :returns: string value of the statistic + .. function:: char ** memcached_stat_get_keys (memcached_st *ptr, memcached_stat_st *stat, memcached_return_t *error) -.. function:: memcached_return_t memcached_stat_execute (memcached_st *memc, const char *args, memcached_stat_fn func, void *context) + :param ptr: pointer to initialized `memcached_st` struct + :param stat: pointer to initialized `memcached_stat_st` struct + :param error: pointer to `memcached_return_t` indicating success + :returns: array of default keys probably available in the statistics -Compile and link with -lmemcached +.. function:: memcached_return_t memcached_stat_execute (memcached_st *ptr, const char *args, memcached_stat_fn func, void *context) + + :param ptr: pointer to initialized `memcached_st` struct + :param args: particular state object to query + :param func: `memcached_stat_fn` callback + :param context: pointer to user supplied context + :returns: `memcached_return_t` indication success DESCRIPTION ----------- -libmemcached(3) has the ability to query a memcached server (or collection -of servers) for their current state. Queries to find state return a -:type:`memcached_stat_st` structure. You are responsible for freeing this structure. While it is possible to access the structure directly it is not advisable. :func:`memcached_stat_get_value` has been provided to query the structure. +`libmemcached` has the ability to query a :manpage:`memcached(1)` server (or +collection of servers) for their current state. Queries to find state return a +:type:`memcached_stat_st` structure. You are responsible for freeing this +structure. While it is possible to access the structure directly it is not +advisable. :func:`memcached_stat_get_value` has been provided to query the structure. -:func:`memcached_stat_execute` uses the servers found in :type:`memcached_stat_st` and executes a "stat" command on each server. args is an optional argument that can be passed in to modify the behavior of "stats". You will need to supply a callback function that will be supplied each pair of values returned by +:func:`memcached_stat_execute` uses the servers found in :type:`memcached_stat_st` +and executes a "stat" command on each server. args is an optional argument that +can be passed in to modify the behavior of "stats". You will need to supply a +callback function that will be supplied each pair of values returned by the memcached server. -:func:`memcached_stat` fetches an array of :type:`memcached_stat_st` structures containing the state of all available memcached servers. The return value must be freed by the calling application. If called with the `MEMCACHED_BEHAVIOR_USE_UDP` behavior set, a NULL value is returned and the error parameter is set to `MEMCACHED_NOT_SUPPORTED`. - -:func:`memcached_stat_servername` can be used standalone without a :type:`memcached_st` to obtain the state of a particular server. "args" is used to define a particular state object (a list of these are not provided for by either -the :func:`memcached_stat_get_keys` call nor are they defined in the memcached protocol). You must specify the hostname and port of the server you want to +:func:`memcached_stat` fetches an array of :type:`memcached_stat_st` structures +containing the state of all available memcached servers. The return value must +be freed by the calling application. If called with the +`MEMCACHED_BEHAVIOR_USE_UDP` behavior set, a NULL value is returned and the +error parameter is set to `MEMCACHED_NOT_SUPPORTED`. + +:func:`memcached_stat_servername` can be used standalone without a +:type:`memcached_st` to obtain the state of a particular server. "args" is used +to define a particular state object (a list of these are not provided for by either +the :func:`memcached_stat_get_keys` call nor are they defined in the memcached +protocol). You must specify the hostname and port of the server you want to obtain information on. -:func:`memcached_stat_get_value` returns the value of a particular state key. You specify the key you wish to obtain. The key must be null terminated. +:func:`memcached_stat_get_value` returns the value of a particular state key. +You specify the key you wish to obtain. The key must be null terminated. -:func:`memcached_stat_get_keys` returns a list of keys that the server has state objects on. You are responsible for freeing this list. +:func:`memcached_stat_get_keys` returns a list of keys that the server has state +objects on. You are responsible for freeing this list. -A command line tool, memstat(1), is provided so that you do not have to write +A command line tool, `memstat`, is provided so that you do not have to write an application to do this. RETURN VALUE @@ -62,5 +111,12 @@ SEE ALSO .. only:: man - :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)` + :manpage:`memcached(1)` + :manpage:`libmemcached(3)` + :manpage:`memcached_strerror(3)` + +.. only:: html + * :manpage:`memcached(1)` + * :doc:`../libmemcached` + * :doc:`memcached_strerror` diff --git a/docs/source/libmemcached/memcached_strerror.rst b/docs/source/libmemcached/memcached_strerror.rst index 09ed37e9..a848f541 100644 --- a/docs/source/libmemcached/memcached_strerror.rst +++ b/docs/source/libmemcached/memcached_strerror.rst @@ -9,6 +9,10 @@ SYNOPSIS .. function:: const char *memcached_strerror(memcached_st *ptr, memcached_return_t rc) + :param ptr: pointer to initialized `memcached_st` struct + :param rc: `memcached_return_t` value to query the string representation for + :returns: the string representation of `rc` + DESCRIPTION ----------- @@ -35,9 +39,10 @@ SEE ALSO :manpage:`memcached(1)` :manpage:`libmemcached(3)` + :manpage:`memcached_return_t` .. only:: html * :manpage:`memcached(1)` * :doc:`../libmemcached` - + * :doc:`memcached_return_t` diff --git a/docs/source/libmemcached/memcached_touch.rst b/docs/source/libmemcached/memcached_touch.rst index 75be550d..1b0fdb61 100644 --- a/docs/source/libmemcached/memcached_touch.rst +++ b/docs/source/libmemcached/memcached_touch.rst @@ -1,18 +1,29 @@ Update expiration on a key ========================== -.. index:: object: memcached_st - SYNOPSIS -------- #include + Compile and link with -lmemcached .. function:: memcached_return_t memcached_touch (memcached_st *ptr, const char *key, size_t key_length, time_t expiration) + :param ptr: pointer to initialized `memcached_st` struct + :param key: the key to touch + :param key_length: the length of `key` without any terminating zero + :param expiration: new expiration as a unix timestamp or as relative expiration time in seconds + :returns: `memcached_return_t` indicating success + .. function:: memcached_return_t memcached_touch_by_key (memcached_st *ptr, const char *group_key, size_t group_key_length, const char *key, size_t key_length, time_t expiration) -Compile and link with -lmemcached + :param ptr: pointer to initialized `memcached_st` struct + :param group_key: the `key` namespace + :param group_key_length: the length of `group_key` without any terminating zero + :param key: the key to touch + :param key_length: the length of `key` without any terminating zero + :param expiration: new expiration as a unix timestamp or as relative expiration time in seconds + :returns: `memcached_return_t` indicating success DESCRIPTION ----------- @@ -24,7 +35,7 @@ to find the given value. RETURN VALUE ------------ -A value of type :type:`memcached_return_t` is returned +A value of type :type:`memcached_return_t` is returned. On success that value will be `MEMCACHED_SUCCESS`. Use :func:`memcached_strerror` to translate this value to a printable string. @@ -34,5 +45,12 @@ SEE ALSO .. only:: man - :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)` + :manpage:`memcached(1)` + :manpage:`libmemcached(3)` + :manpage:`memcached_strerror(3)` + +.. only:: html + * :manpage:`memcached(1)` + * :doc:`../libmemcached` + * :doc:`memcached_strerror` diff --git a/docs/source/libmemcached/memcached_user_data.rst b/docs/source/libmemcached/memcached_user_data.rst index a0437df3..7d9e0179 100644 --- a/docs/source/libmemcached/memcached_user_data.rst +++ b/docs/source/libmemcached/memcached_user_data.rst @@ -1,49 +1,51 @@ -============================================== -Storing custom user information in the client. -============================================== - -.. index:: object: memcached_st - -Manage user specific data - -LIBRARY -------- - -C Client Library for memcached (libmemcached, -lmemcached) +Storing custom information in the client +======================================== SYNOPSIS -------- #include + Compile and link with -lmemcached .. function:: void *memcached_get_user_data (memcached_st *ptr) + :param ptr: pointer to initialized `memcached_st` struct + :returns: opaque pointer to the user supplied data + .. function:: void *memcached_set_user_data (memcached_st *ptr, void *data) -Compile and link with -lmemcached + :param ptr: pointer to initialized `memcached_st` struct + :param data: opaque pointer to user supplied data + :returns: opaque pointer to the previously set `data` DESCRIPTION ----------- -libmemcached(3) allows you to store a pointer to a user specific data inside +`libmemcached` allows you to store a pointer to a user specific data inside the memcached_st structure. :func:`memcached_set_user_data` is used to set the user specific data in the :type:`memcached_st` structure. -:func:`memcached_get_user_data` is used to retrieve the user specific data in the :type:`memcached_st` structure. +:func:`memcached_get_user_data` is used to retrieve the user specific data in +the :type:`memcached_st` structure. RETURN VALUE ------------ :func:`memcached_set_user_data` returns the previous value of the user specific data. -:func:`memcached_get_user_data` returns the current value uf the user specific data. +:func:`memcached_get_user_data` returns the current value of the user specific data. SEE ALSO -------- .. only:: man - :manpage:`memcached(1)` :manpage:`libmemcached(3)` + :manpage:`memcached(1)` + :manpage:`libmemcached(3)` + +.. only:: html + * :manpage:`memcached(1)` + * :doc:`../libmemcached` diff --git a/docs/source/libmemcached/memcached_verbosity.rst b/docs/source/libmemcached/memcached_verbosity.rst index cf9db0e7..e784c644 100644 --- a/docs/source/libmemcached/memcached_verbosity.rst +++ b/docs/source/libmemcached/memcached_verbosity.rst @@ -1,24 +1,23 @@ Setting the verbosity of a server ================================= -.. index:: object: memcached_st - -Modify verbosity of servers - SYNOPSIS -------- #include + Compile and link with -lmemcached .. function:: memcached_return_t memcached_verbosity (memcached_st *ptr, uint32_t verbosity) -Compile and link with -lmemcached + :param ptr: pointer to initialized `memcached_st` struct + :param verbosity: level of verbosity + :returns: `memcached_return_t` indicating success DESCRIPTION ----------- :func:`memcached_verbosity` modifies the "verbosity" of the -memcached(1) servers referenced in the :type:`memcached_st` parameter. +:manpage:`memcached(1)` servers referenced in the :type:`memcached_st` parameter. RETURN VALUE ------------ @@ -34,5 +33,12 @@ SEE ALSO .. only:: man - :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)` + :manpage:`memcached(1)` + :manpage:`libmemcached(3)` + :manpage:`memcached_strerror(3)` + +.. only:: html + * :manpage:`memcached(1)` + * :doc:`../libmemcached` + * :doc:`memcached_strerror` diff --git a/docs/source/libmemcached/memcached_version.rst b/docs/source/libmemcached/memcached_version.rst index e11c8334..9c7e840e 100644 --- a/docs/source/libmemcached/memcached_version.rst +++ b/docs/source/libmemcached/memcached_version.rst @@ -1,23 +1,30 @@ -Getting version information about the client and server -======================================================= +Getting version information +=========================== SYNOPSIS -------- #include + Compile and link with -lmemcached .. function:: const char * memcached_lib_version (void) + :returns: version string of `libmemcached` + .. function:: memcached_return_t memcached_version (memcached_st *ptr) -Compile and link with -lmemcached + :param ptr: pointer to initialized `memcached_st` struct + :returns: `memcached_return_t` indicating success DESCRIPTION ----------- -:func:`memcached_lib_version` is used to return a simple version string representing the libmemcached version (client library version, not server version) +:func:`memcached_lib_version` is used to return a simple version string +representing the `libmemcached` version (client library, not server). -:func:`memcached_version` is used to set the major, minor, and micro versions of each memcached server being used by the memcached_st connection structure. It returns the memcached server return code. +:func:`memcached_version` is used to set the major, minor, and micro versions of +each memcached server being used by the `memcached_st` connection structure. +It returns the memcached server return code. RETURN VALUE ------------ -- 2.30.2