From e20117720ca0fa133781b62c43aab59fe864b390 Mon Sep 17 00:00:00 2001 From: Michael Wallner Date: Wed, 27 May 2020 09:49:03 +0200 Subject: [PATCH] docs: bin/ --- .gitignore | 1 + docs/source/bin/index.rst | 45 +++++++++----- docs/source/bin/memcapable.rst | 33 +++++----- docs/source/bin/memcat.rst | 42 ++++++++----- docs/source/bin/memcp.rst | 61 ++++++++++++------ docs/source/bin/memdump.rst | 31 +++++++--- docs/source/bin/memerror.rst | 32 ++++++---- docs/source/bin/memexist.rst | 38 +++++++----- docs/source/bin/memflush.rst | 62 ++++++++++++++----- docs/source/bin/memparse.rst | 26 ++++---- docs/source/bin/memping.rst | 33 +++++----- docs/source/bin/memrm.rst | 36 ++++++----- docs/source/bin/memslap.rst | 34 +++++----- docs/source/bin/memstat.rst | 46 +++++++++----- docs/source/bin/memtouch.rst | 34 +++++----- docs/source/bin/options/all.rst | 8 +++ docs/source/bin/options/common.rst | 20 ++++++ docs/source/bin/options/expire.rst | 4 ++ docs/source/bin/options/flag.rst | 4 ++ docs/source/bin/options/hash.rst | 5 ++ docs/source/bin/options/sasl.rst | 8 +++ docs/source/bin/options/udp.rst | 4 ++ docs/source/conf.py.in | 5 +- docs/source/libmemcached.rst | 1 - .../source/libmemcached/memcached_analyze.rst | 1 + .../libmemcached/memcached_return_t.rst | 14 +++-- src/bin/memcp.cc | 3 - 27 files changed, 412 insertions(+), 219 deletions(-) create mode 100644 docs/source/bin/options/all.rst create mode 100644 docs/source/bin/options/common.rst create mode 100644 docs/source/bin/options/expire.rst create mode 100644 docs/source/bin/options/flag.rst create mode 100644 docs/source/bin/options/hash.rst create mode 100644 docs/source/bin/options/sasl.rst create mode 100644 docs/source/bin/options/udp.rst diff --git a/.gitignore b/.gitignore index 6e4a3f49..ffe575ca 100644 --- a/.gitignore +++ b/.gitignore @@ -42,6 +42,7 @@ src/bin/memslap src/bin/memstat src/bin/memtouch cmake-build-*/ +ccmake-*/ example/memcached_light example/t/memcached_light tags diff --git a/docs/source/bin/index.rst b/docs/source/bin/index.rst index 67dc61cb..6385e8ef 100644 --- a/docs/source/bin/index.rst +++ b/docs/source/bin/index.rst @@ -1,20 +1,37 @@ Client Applications =================== +Data Manipulation +----------------- + .. toctree:: :titlesonly: - - memcapable - memcat - memcp - memdump - memerror - memflush - memrm - memslap + + memexist — Check for the existence of a key + memcat — "cat" data from a server + memcp — "cp" files to a server + memtouch — "touch" a key + memrm – "rm" a key + +Tests and Analysis +------------------ + +.. toctree:: + :titlesonly: + memaslap - memstat - memexist - memparse - memping - memtouch + memslap + memping – Ping a server + memstat – Gather statistics from a server + memerror — Translate libmemcached error codes + memparse — Parse and validate an option string + memcapable — Check a server's capabilities and compatibility + +Server Administration +--------------------- + +.. toctree:: + :titlesonly: + + memdump — Dump a server's data + memflush — Flush a server (erase all cached data) diff --git a/docs/source/bin/memcapable.rst b/docs/source/bin/memcapable.rst index f8290333..d1a4f7a4 100644 --- a/docs/source/bin/memcapable.rst +++ b/docs/source/bin/memcapable.rst @@ -1,53 +1,52 @@ -======================================================================= -memcapable - Checking a Memcached server capabilities and compatibility -======================================================================= +memcapable +========== SYNOPSIS -------- +.. program:: memcapable + memcapable [options] -.. program:: memcapable +Check a memcached server's capabilities and compatibility. DESCRIPTION ----------- :program:`memcapable` connects to the specified memcached server and tries to -determine its capabilities by running the various commands and verifying -the response. - -LIMITATIONS ------------ - -The current version of memcapable will only verify the binary protocol. +determine its capabilities by running various commands and verifying the response. OPTIONS ------- .. option:: -h hostname -Specify the hostname to connect to. The default is \ *localhost*\ + Specify the hostname to connect to. The default is \ *localhost*\ . .. option:: -p port -Specify the port number to connect to. The default is \ *11211*\ + Specify the port number to connect to. The default is \ *11211*\ . .. option:: -c -Generate a coredump when it detects an error from the server. + :manpage:`abort(3)` when detecting an error from the server. .. option:: -v -Print out the comparison when it detects an error from the server. + Print out the comparison when it detects an error from the server. .. option:: -t n -Set the timeout from an IO operation to/from the server to \ *n*\ seconds. + Set the timeout for an IO operation to/from the server to \ *n*\ seconds. SEE ALSO -------- .. only:: man - :manpage:`memcached(1)` :manpage:`libmemcached(3)` + :manpage:`memcached(1)` + :manpage:`libmemcached(3)` + +.. only:: html + * :doc:`/libmemcached` diff --git a/docs/source/bin/memcat.rst b/docs/source/bin/memcat.rst index c3a6b65e..aa6cc540 100644 --- a/docs/source/bin/memcat.rst +++ b/docs/source/bin/memcat.rst @@ -1,43 +1,53 @@ -================================= -memcat - "cat" data from a server -================================= +memcat +====== SYNOPSIS -------- -memcat [options] key +.. program:: memcat -Copy a set of keys to stdout +memcat [options] key [key...] -.. program:: memcat +Read and output the value of one key or the values of a set of keys. DESCRIPTION ----------- -:program:`memcat` outputs to stdout the value a single or multiple set of keys -stored in a memcached(1) server. If any key is not found an error is returned. +:program:`memcat` reads and outputs the value of a single or a set of keys +stored in a :manpage:`memcached(1)` server. + +If any key is not found an error is returned. -It is similar to the standard UNIX cat(1) utility. +It is similar to the standard UNIX :manpage:`cat(1)` utility. OPTIONS ------- -You can specify servers via the option: +.. include:: options/all.rst +.. include:: options/common.rst +.. include:: options/hash.rst -.. option:: --servers +.. option:: --flag -or via the environment variable: + Display stored flags. -.. envvar:: `MEMCACHED_SERVERS` +ENVIRONMENT +----------- -For a full list of operations run the tool with the option: +.. envvar:: MEMCACHED_SERVERS -.. option:: --help + Specify a list of servers. SEE ALSO -------- .. only:: man - :manpage:`memcached(1)` :manpage:`libmemcached(3)` + :manpage:`memcached(1)` + :manpage:`libmemcached(3)` + :manpage:`libmemcached_configuration(3)` + +.. only:: html + * :doc:`/libmemcached` + * :doc:`/libmemcached/configuration` diff --git a/docs/source/bin/memcp.rst b/docs/source/bin/memcp.rst index e67cd28e..deea12a7 100644 --- a/docs/source/bin/memcp.rst +++ b/docs/source/bin/memcp.rst @@ -1,46 +1,69 @@ -============================= -memcp - Copy data to a server -============================= - -Copies files to a collection of memcached servers +memcp +===== SYNOPSIS -------- -memcp [options] [file] [server] - .. program:: memcp +memcp [options] \-\-servers + +Copy files to a collection of memcached servers. + DESCRIPTION ----------- -:program:`memcp` copies one or more files into memcached(1) servers. -It is similar to the standard UNIX cp(1) command. +:program:`memcp` copies one or more files into :manpage:`memcached(1)` servers. +It is similar to the standard UNIX :manpage:`cp(1)` command. -The key names will be the names of the files, -without any directory path. +The key names will be the names of the files, without any directory path. OPTIONS ------- -You can specify servers via the option: +.. include:: options/all.rst +.. include:: options/common.rst +.. include:: options/expire.rst +.. include:: options/flag.rst +.. include:: options/hash.rst +.. include:: options/sasl.rst +.. include:: options/udp.rst + +.. option:: --buffer + + Enable internal buffering of commands. -.. option:: --servers +.. option:: --set -or via the environment variable: + Issue *SET* command(s). This is the default mode. + See also :option:`--add` and :option:`--replace`. -.. envvar:: `MEMCACHED_SERVERS` +.. option:: --add -If you do not specify either these, the final value in the command line list is the name of a server(s). + Issue *ADD* command(s). -For a full list of operations run the tool with the option: +.. option:: --replace -.. option:: --help + Issue *REPLACE* command(s). + +ENVIRONMENT +----------- + +.. envvar:: MEMCACHED_SERVERS + + Specify the list of servers. SEE ALSO -------- .. only:: man - :manpage:`memcached(1)` :manpage:`libmemcached(3)` + :manpage:`memcached(1)` + :manpage:`libmemcached(3)` + :manpage:`memcached_behavior(3)` + +.. only:: html + * :doc:`/libmemcached` + * :doc:`/libmemcached/configuration` + * :doc:`/libmemcached/memcached_behavior` diff --git a/docs/source/bin/memdump.rst b/docs/source/bin/memdump.rst index ed3c8004..07eb2fff 100644 --- a/docs/source/bin/memdump.rst +++ b/docs/source/bin/memdump.rst @@ -1,15 +1,14 @@ -============================= -memdump - Dumping your server -============================= - -Dump a list of keys from a server. +memdump +======= SYNOPSIS -------- +.. program:: memdump + memdump [options] -.. program:: memdump +Dump a list of keys from a server. DESCRIPTION ----------- @@ -21,13 +20,27 @@ provide all keys it is not possible to get a complete "dump". OPTIONS ------- -For a full list of operations run the tool with option: +.. include:: options/all.rst +.. include:: options/common.rst +.. include:: options/hash.rst +.. include:: options/sasl.rst -.. option:: --help +ENVIRONMENT +----------- + +.. envvar:: MEMCACHED_SERVERS + + Specify the list of servers. SEE ALSO -------- .. only:: man - :manpage:`memcached(1)` :manpage:`libmemcached(3)` + :manpage:`memcached(1)` + :manpage:`libmemcached(3)` + +.. only:: html + + * :doc:`/libmemcached` + * :doc:`/libmemcached/memcached_dump` diff --git a/docs/source/bin/memerror.rst b/docs/source/bin/memerror.rst index d67c08f1..525aaf63 100644 --- a/docs/source/bin/memerror.rst +++ b/docs/source/bin/memerror.rst @@ -1,32 +1,42 @@ -============================================== -memerror - translate an error code to a string -============================================== - -Translates a memcached error code into a string +memerror +======== SYNOPSIS -------- -memerror [options] [error code] - .. program:: memerror +memerror [options] + +Translate a memcached error code into a string. + DESCRIPTION ----------- -:program:`memerror` translates an error code from libmemcached(3) into a human +:program:`memerror` translates an error code from `libmemcached` into a human readable string. OPTIONS ------- -For a full list of operations run the tool with option: +.. include:: options/all.rst -.. option:: --help +ENVIRONMENT +----------- + +.. envvar:: MEMCACHED_SERVERS + + Specify the list of servers. SEE ALSO -------- .. only:: man - :manpage:`memcached(1)` :manpage:`libmemcached(3)` + :manpage:`memcached(1)` + :manpage:`libmemcached(3)` + +.. only:: html + + * :doc:`/libmemcached` + * :doc:`/libmemcached/index_errors` diff --git a/docs/source/bin/memexist.rst b/docs/source/bin/memexist.rst index c8542ac8..1859c838 100644 --- a/docs/source/bin/memexist.rst +++ b/docs/source/bin/memexist.rst @@ -1,40 +1,44 @@ -=========================================== -memexist - Check for the existence of a key -=========================================== +memexist +======== SYNOPSIS -------- -memexist [options] [key] - .. program:: memexist +memexist [options] + +Check for the existence of a key. + DESCRIPTION ----------- -:program:`memexist` checks for the existance of a key within a cluster. +:program:`memexist` checks for the existence of a key within a cluster. OPTIONS ------- -You can specify servers via the option: - -.. option:: --servers +.. include:: options/all.rst +.. include:: options/common.rst +.. include:: options/hash.rst +.. include:: options/sasl.rst -or via the environment variable: - -.. envvar:: `MEMCACHED_SERVERS` - -If you do not specify either these, the final value in the command line list is the name of a server(s). +ENVIRONMENT +----------- -For a full list of operations run the tool with the option: +.. envvar:: MEMCACHED_SERVERS -.. option:: --help + Specify the list of servers. SEE ALSO -------- .. only:: man - :manpage:`memcached(1)` :manpage:`libmemcached(3)` + :manpage:`memcached(1)` + :manpage:`libmemcached(3)` + +.. only:: html + * :doc:`/libmemcached` + * :doc:`/libmemcached/memcached_exist` diff --git a/docs/source/bin/memflush.rst b/docs/source/bin/memflush.rst index 461ef85f..ed84d9a9 100644 --- a/docs/source/bin/memflush.rst +++ b/docs/source/bin/memflush.rst @@ -1,8 +1,5 @@ -======================================= -memflush - flush all data from a server -======================================= - -Reset a server or list of servers +memflush +======== SYNOPSIS -------- @@ -11,30 +8,67 @@ memflush [options] .. program:: memflush +Reset a server or list of servers + DESCRIPTION ----------- -:program:`memflush` resets the contents of memcached(1) servers. -This means that all data in the specified servers will be deleted. +:program:`memflush` resets the contents of :manpage:`memcached(1)` servers. + +.. warning:: + + This means that all data in the specified servers will be deleted. OPTIONS ------- -You can specify servers via the option: +.. include:: options/all.rst +.. include:: options/common.rst +.. include:: options/sasl.rst +.. include:: options/expire.rst + +.. note:: -.. option:: --servers + Using an expiration time (period), all keys, which have not bean updated until expiration will cease to exist. -or via the environment variable: + Quoting the `memcached protocol documentation`_, it states: -.. envvar:: `MEMCACHED_SERVERS` + Its effect is to invalidate all + existing items immediately (by default) or after the expiration + specified. After invalidation none of the items will be returned in + response to a retrieval command (unless it's stored again under the + same key *after* flush_all has invalidated the items). -For a full list of operations run the tool with option: + The most precise + definition of what flush_all does is the following: it causes all + items whose update time is earlier than the time at which flush_all + was set to be executed to be ignored for retrieval purposes. -.. option:: --help + The intent of flush_all with a delay, was that in a setting where you + have a pool of memcached servers, and you need to flush all content, + you have the option of not resetting all memcached servers at the + same time (which could e.g. cause a spike in database load with all + clients suddenly needing to recreate content that would otherwise + have been found in the memcached daemon). + +.. _memcached protocol documentation: https://github.com/memcached/memcached/blob/master/doc/protocol.txt + +ENVIRONMENT +----------- + +.. envvar:: MEMCACHED_SERVERS + + Specify the list of servers. SEE ALSO -------- .. only:: man - :manpage:`memcached(1)` :manpage:`libmemcached(3)` + :manpage:`memcached(1)` + :manpage:`libmemcached(3)` + +.. only:: html + +* :doc:`/libmemcached` +* :doc:`/libmemcached/memcached_flush` diff --git a/docs/source/bin/memparse.rst b/docs/source/bin/memparse.rst index 4ad1b754..4a6f4135 100644 --- a/docs/source/bin/memparse.rst +++ b/docs/source/bin/memparse.rst @@ -1,16 +1,15 @@ -================================= -memparse - Parse an option string -================================= - -Used to validate an option string +memparse +======== SYNOPSIS -------- -memparse [options] "option string" - .. program:: memparse +memparse