"Fossies" - the Fresh Open Source Software Archive

Member "memcached-1.6.15/doc/protocol.txt" (30 Mar 2022, 80007 Bytes) of package /linux/www/memcached-1.6.15.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "protocol.txt": 1.6.14_vs_1.6.15.

    1 Protocol
    2 --------
    3 
    4 Clients of memcached communicate with server through TCP connections.
    5 (A UDP interface is also available; details are below under "UDP
    6 protocol.") A given running memcached server listens on some
    7 (configurable) port; clients connect to that port, send commands to
    8 the server, read responses, and eventually close the connection.
    9 
   10 There is no need to send any command to end the session. A client may
   11 just close the connection at any moment it no longer needs it. Note,
   12 however, that clients are encouraged to cache their connections rather
   13 than reopen them every time they need to store or retrieve data.  This
   14 is because memcached is especially designed to work very efficiently
   15 with a very large number (many hundreds, more than a thousand if
   16 necessary) of open connections. Caching connections will eliminate the
   17 overhead associated with establishing a TCP connection (the overhead
   18 of preparing for a new connection on the server side is insignificant
   19 compared to this).
   20 
   21 There are two kinds of data sent in the memcache protocol: text lines
   22 and unstructured data.  Text lines are used for commands from clients
   23 and responses from servers. Unstructured data is sent when a client
   24 wants to store or retrieve data. The server will transmit back
   25 unstructured data in exactly the same way it received it, as a byte
   26 stream. The server doesn't care about byte order issues in
   27 unstructured data and isn't aware of them. There are no limitations on
   28 characters that may appear in unstructured data; however, the reader
   29 of such data (either a client or a server) will always know, from a
   30 preceding text line, the exact length of the data block being
   31 transmitted.
   32 
   33 Text lines are always terminated by \r\n. Unstructured data is _also_
   34 terminated by \r\n, even though \r, \n or any other 8-bit characters
   35 may also appear inside the data. Therefore, when a client retrieves
   36 data from a server, it must use the length of the data block (which it
   37 will be provided with) to determine where the data block ends, and not
   38 the fact that \r\n follows the end of the data block, even though it
   39 does.
   40 
   41 Keys
   42 ----
   43 
   44 Data stored by memcached is identified with the help of a key. A key
   45 is a text string which should uniquely identify the data for clients
   46 that are interested in storing and retrieving it.  Currently the
   47 length limit of a key is set at 250 characters (of course, normally
   48 clients wouldn't need to use such long keys); the key must not include
   49 control characters or whitespace.
   50 
   51 Commands
   52 --------
   53 
   54 There are three types of commands.
   55 
   56 Storage commands (there are six: "set", "add", "replace", "append"
   57 "prepend" and "cas") ask the server to store some data identified by a
   58 key. The client sends a command line, and then a data block; after
   59 that the client expects one line of response, which will indicate
   60 success or failure.
   61 
   62 Retrieval commands ("get", "gets", "gat", and "gats") ask the server to
   63 retrieve data corresponding to a set of keys (one or more keys in one
   64 request). The client sends a command line, which includes all the
   65 requested keys; after that for each item the server finds it sends to
   66 the client one response line with information about the item, and one
   67 data block with the item's data; this continues until the server
   68 finished with the "END" response line.
   69 
   70 All other commands don't involve unstructured data. In all of them,
   71 the client sends one command line, and expects (depending on the
   72 command) either one line of response, or several lines of response
   73 ending with "END" on the last line.
   74 
   75 A command line always starts with the name of the command, followed by
   76 parameters (if any) delimited by whitespace. Command names are
   77 lower-case and are case-sensitive.
   78 
   79 Meta Commands
   80 -------------
   81 
   82 Meta commands are a set of new ASCII-based commands. They follow the same
   83 structure of the original commands but have a new flexible feature set.
   84 Meta commands incorporate most features available in the binary protocol, as
   85 well as a flag system to make the commands flexible rather than having a
   86 large number of high level commands. These commands completely replace the
   87 usage of basic Storage and Retrieval commands.
   88 
   89 Meta flags are not to be confused with client bitflags, which is an opaque
   90 number passed by the client. Meta flags change how the command operates, but
   91 they are not stored in cache.
   92 
   93 These work mixed with normal protocol commands on the same connection. All
   94 existing commands continue to work. The meta commands will not replace
   95 specialized commands that do not sit in the Storage or Retrieval categories
   96 noted in the 'Commands' section above.
   97 
   98 All meta commands follow a basic syntax:
   99 
  100 <cm> <key> <datalen*> <flag1> <flag2> <...>\r\n
  101 
  102 Where <cm> is a 2 character command code.
  103 <datalen> is only for commands with payloads, like set.
  104 
  105 Responses look like:
  106 
  107 <RC> <datalen*> <flag1> <flag2> <...>\r\n
  108 
  109 Where <RC> is a 2 character return code. The number of flags returned are
  110 based off of the flags supplied.
  111 
  112 <datalen> is only for responses with payloads, with the return code 'VA'.
  113 
  114 Flags are single character codes, ie 'q' or 'k' or 'I', which adjust the
  115 behavior of the command. If a flag requests a response flag (ie 't' for TTL
  116 remaining), it is returned in the same order as they were in the original
  117 command, though this is not strict.
  118 
  119 Flags are single character codes, ie 'q' or 'k' or 'O', which adjust the
  120 behavior of a command. Flags may contain token arguments, which come after the
  121 flag and before the next space or newline, ie 'Oopaque' or 'Kuserkey'. Flags
  122 can return new data or reflect information, in the same order they were
  123 supplied in the request. Sending an 't' flag with a get for an item with 20
  124 seconds of TTL remaining, would return 't20' in the response.
  125 
  126 All commands accept a tokens 'P' and 'L' which are completely ignored. The
  127 arguments to 'P' and 'L' can be used as hints or path specifications to a
  128 proxy or router inbetween a client and a memcached daemon. For example, a
  129 client may prepend a "path" in the key itself: "mg /path/foo v" or in a proxy
  130 token: "mg foo Lpath/ v" - the proxy may then optionally remove or forward the
  131 token to a memcached daemon, which will ignore them.
  132 
  133 Syntax errors are handled the same as noted under 'Error strings' section
  134 below.
  135 
  136 For usage examples beyond basic syntax, please see the wiki:
  137 https://github.com/memcached/memcached/wiki/MetaCommands
  138 
  139 Expiration times
  140 ----------------
  141 
  142 Some commands involve a client sending some kind of expiration time
  143 (relative to an item or to an operation requested by the client) to
  144 the server. In all such cases, the actual value sent may either be
  145 Unix time (number of seconds since January 1, 1970, as a 32-bit
  146 value), or a number of seconds starting from current time. In the
  147 latter case, this number of seconds may not exceed 60*60*24*30 (number
  148 of seconds in 30 days); if the number sent by a client is larger than
  149 that, the server will consider it to be real Unix time value rather
  150 than an offset from current time.
  151 
  152 Note that a TTL of 1 will sometimes immediately expire. Time is internally
  153 updated on second boundaries, which makes expiration time roughly +/- 1s.
  154 This more proportionally affects very low TTL's.
  155 
  156 Error strings
  157 -------------
  158 
  159 Each command sent by a client may be answered with an error string
  160 from the server. These error strings come in three types:
  161 
  162 - "ERROR\r\n"
  163 
  164   means the client sent a nonexistent command name.
  165 
  166 - "CLIENT_ERROR <error>\r\n"
  167 
  168   means some sort of client error in the input line, i.e. the input
  169   doesn't conform to the protocol in some way. <error> is a
  170   human-readable error string.
  171 
  172 - "SERVER_ERROR <error>\r\n"
  173 
  174   means some sort of server error prevents the server from carrying
  175   out the command. <error> is a human-readable error string. In cases
  176   of severe server errors, which make it impossible to continue
  177   serving the client (this shouldn't normally happen), the server will
  178   close the connection after sending the error line. This is the only
  179   case in which the server closes a connection to a client.
  180 
  181 
  182 In the descriptions of individual commands below, these error lines
  183 are not again specifically mentioned, but clients must allow for their
  184 possibility.
  185 
  186 Authentication
  187 --------------
  188 
  189 Optional username/password token authentication (see -Y option). Used by
  190 sending a fake "set" command with any key:
  191 
  192 set <key> <flags> <exptime> <bytes>\r\n
  193 username password\r\n
  194 
  195 key, flags, and exptime are ignored for authentication. Bytes is the length
  196 of the username/password payload.
  197 
  198 - "STORED\r\n" indicates success. After this point any command should work
  199   normally.
  200 
  201 - "CLIENT_ERROR [message]\r\n" will be returned if authentication fails for
  202   any reason.
  203 
  204 Storage commands
  205 ----------------
  206 
  207 First, the client sends a command line which looks like this:
  208 
  209 <command name> <key> <flags> <exptime> <bytes> [noreply]\r\n
  210 cas <key> <flags> <exptime> <bytes> <cas unique> [noreply]\r\n
  211 
  212 - <command name> is "set", "add", "replace", "append" or "prepend"
  213 
  214   "set" means "store this data".
  215 
  216   "add" means "store this data, but only if the server *doesn't* already
  217   hold data for this key".
  218 
  219   "replace" means "store this data, but only if the server *does*
  220   already hold data for this key".
  221 
  222   "append" means "add this data to an existing key after existing data".
  223 
  224   "prepend" means "add this data to an existing key before existing data".
  225 
  226   The append and prepend commands do not accept flags or exptime.
  227   They update existing data portions, and ignore new flag and exptime
  228   settings.
  229 
  230   "cas" is a check and set operation which means "store this data but
  231   only if no one else has updated since I last fetched it."
  232 
  233 - <key> is the key under which the client asks to store the data
  234 
  235 - <flags> is an arbitrary 16-bit unsigned integer (written out in
  236   decimal) that the server stores along with the data and sends back
  237   when the item is retrieved. Clients may use this as a bit field to
  238   store data-specific information; this field is opaque to the server.
  239   Note that in memcached 1.2.1 and higher, flags may be 32-bits, instead
  240   of 16, but you might want to restrict yourself to 16 bits for
  241   compatibility with older versions.
  242 
  243 - <exptime> is expiration time. If it's 0, the item never expires
  244   (although it may be deleted from the cache to make place for other
  245   items). If it's non-zero (either Unix time or offset in seconds from
  246   current time), it is guaranteed that clients will not be able to
  247   retrieve this item after the expiration time arrives (measured by
  248   server time). If a negative value is given the item is immediately
  249   expired.
  250 
  251 - <bytes> is the number of bytes in the data block to follow, *not*
  252   including the delimiting \r\n. <bytes> may be zero (in which case
  253   it's followed by an empty data block).
  254 
  255 - <cas unique> is a unique 64-bit value of an existing entry.
  256   Clients should use the value returned from the "gets" command
  257   when issuing "cas" updates.
  258 
  259 - "noreply" optional parameter instructs the server to not send the
  260   reply.  NOTE: if the request line is malformed, the server can't
  261   parse "noreply" option reliably.  In this case it may send the error
  262   to the client, and not reading it on the client side will break
  263   things.  Client should construct only valid requests.
  264 
  265 After this line, the client sends the data block:
  266 
  267 <data block>\r\n
  268 
  269 - <data block> is a chunk of arbitrary 8-bit data of length <bytes>
  270   from the previous line.
  271 
  272 After sending the command line and the data block the client awaits
  273 the reply, which may be:
  274 
  275 - "STORED\r\n", to indicate success.
  276 
  277 - "NOT_STORED\r\n" to indicate the data was not stored, but not
  278 because of an error. This normally means that the
  279 condition for an "add" or a "replace" command wasn't met.
  280 
  281 - "EXISTS\r\n" to indicate that the item you are trying to store with
  282 a "cas" command has been modified since you last fetched it.
  283 
  284 - "NOT_FOUND\r\n" to indicate that the item you are trying to store
  285 with a "cas" command did not exist.
  286 
  287 
  288 Retrieval command:
  289 ------------------
  290 
  291 The retrieval commands "get" and "gets" operate like this:
  292 
  293 get <key>*\r\n
  294 gets <key>*\r\n
  295 
  296 - <key>* means one or more key strings separated by whitespace.
  297 
  298 After this command, the client expects zero or more items, each of
  299 which is received as a text line followed by a data block. After all
  300 the items have been transmitted, the server sends the string
  301 
  302 "END\r\n"
  303 
  304 to indicate the end of response.
  305 
  306 Each item sent by the server looks like this:
  307 
  308 VALUE <key> <flags> <bytes> [<cas unique>]\r\n
  309 <data block>\r\n
  310 
  311 - <key> is the key for the item being sent
  312 
  313 - <flags> is the flags value set by the storage command
  314 
  315 - <bytes> is the length of the data block to follow, *not* including
  316   its delimiting \r\n
  317 
  318 - <cas unique> is a unique 64-bit integer that uniquely identifies
  319   this specific item.
  320 
  321 - <data block> is the data for this item.
  322 
  323 If some of the keys appearing in a retrieval request are not sent back
  324 by the server in the item list this means that the server does not
  325 hold items with such keys (because they were never stored, or stored
  326 but deleted to make space for more items, or expired, or explicitly
  327 deleted by a client).
  328 
  329 
  330 Deletion
  331 --------
  332 
  333 The command "delete" allows for explicit deletion of items:
  334 
  335 delete <key> [noreply]\r\n
  336 
  337 - <key> is the key of the item the client wishes the server to delete
  338 
  339 - "noreply" optional parameter instructs the server to not send the
  340   reply.  See the note in Storage commands regarding malformed
  341   requests.
  342 
  343 The response line to this command can be one of:
  344 
  345 - "DELETED\r\n" to indicate success
  346 
  347 - "NOT_FOUND\r\n" to indicate that the item with this key was not
  348   found.
  349 
  350 See the "flush_all" command below for immediate invalidation
  351 of all existing items.
  352 
  353 
  354 Increment/Decrement
  355 -------------------
  356 
  357 Commands "incr" and "decr" are used to change data for some item
  358 in-place, incrementing or decrementing it. The data for the item is
  359 treated as decimal representation of a 64-bit unsigned integer.  If
  360 the current data value does not conform to such a representation, the
  361 incr/decr commands return an error (memcached <= 1.2.6 treated the
  362 bogus value as if it were 0, leading to confusion). Also, the item
  363 must already exist for incr/decr to work; these commands won't pretend
  364 that a non-existent key exists with value 0; instead, they will fail.
  365 
  366 The client sends the command line:
  367 
  368 incr <key> <value> [noreply]\r\n
  369 
  370 or
  371 
  372 decr <key> <value> [noreply]\r\n
  373 
  374 - <key> is the key of the item the client wishes to change
  375 
  376 - <value> is the amount by which the client wants to increase/decrease
  377 the item. It is a decimal representation of a 64-bit unsigned integer.
  378 
  379 - "noreply" optional parameter instructs the server to not send the
  380   reply.  See the note in Storage commands regarding malformed
  381   requests.
  382 
  383 The response will be one of:
  384 
  385 - "NOT_FOUND\r\n" to indicate the item with this value was not found
  386 
  387 - <value>\r\n , where <value> is the new value of the item's data,
  388   after the increment/decrement operation was carried out.
  389 
  390 Note that underflow in the "decr" command is caught: if a client tries
  391 to decrease the value below 0, the new value will be 0.  Overflow in
  392 the "incr" command will wrap around the 64 bit mark.
  393 
  394 Note also that decrementing a number such that it loses length isn't
  395 guaranteed to decrement its returned length.  The number MAY be
  396 space-padded at the end, but this is purely an implementation
  397 optimization, so you also shouldn't rely on that.
  398 
  399 Touch
  400 -----
  401 
  402 The "touch" command is used to update the expiration time of an existing item
  403 without fetching it.
  404 
  405 touch <key> <exptime> [noreply]\r\n
  406 
  407 - <key> is the key of the item the client wishes the server to touch
  408 
  409 - <exptime> is expiration time. Works the same as with the update commands
  410   (set/add/etc). This replaces the existing expiration time. If an existing
  411   item were to expire in 10 seconds, but then was touched with an
  412   expiration time of "20", the item would then expire in 20 seconds.
  413 
  414 - "noreply" optional parameter instructs the server to not send the
  415   reply.  See the note in Storage commands regarding malformed
  416   requests.
  417 
  418 The response line to this command can be one of:
  419 
  420 - "TOUCHED\r\n" to indicate success
  421 
  422 - "NOT_FOUND\r\n" to indicate that the item with this key was not
  423   found.
  424 
  425 Get And Touch
  426 -------------
  427 
  428 The "gat" and "gats" commands are used to fetch items and update the
  429 expiration time of an existing items.
  430 
  431 gat <exptime> <key>*\r\n
  432 gats <exptime> <key>*\r\n
  433 
  434 - <exptime> is expiration time.
  435 
  436 - <key>* means one or more key strings separated by whitespace.
  437 
  438 After this command, the client expects zero or more items, each of
  439 which is received as a text line followed by a data block. After all
  440 the items have been transmitted, the server sends the string
  441 
  442 "END\r\n"
  443 
  444 to indicate the end of response.
  445 
  446 Each item sent by the server looks like this:
  447 
  448 VALUE <key> <flags> <bytes> [<cas unique>]\r\n
  449 <data block>\r\n
  450 
  451 - <key> is the key for the item being sent
  452 
  453 - <flags> is the flags value set by the storage command
  454 
  455 - <bytes> is the length of the data block to follow, *not* including
  456   its delimiting \r\n
  457 
  458 - <cas unique> is a unique 64-bit integer that uniquely identifies
  459   this specific item.
  460 
  461 - <data block> is the data for this item.
  462 
  463 Meta Debug
  464 ----------
  465 
  466 The meta debug command is a human readable dump of all available internal
  467 metadata of an item, minus the value.
  468 
  469 me <key> <flag>\r\n
  470 
  471 - <key> means one key string.
  472 - if <flag> is 'b', then <key> is a base64 encoded binary value. the response
  473   key will also be base64 encoded.
  474 
  475 The response looks like:
  476 
  477 ME <key> <k>=<v>*\r\n
  478 
  479 A miss looks like:
  480 
  481 EN\r\n
  482 
  483 Each of the keys and values are the internal data for the item.
  484 
  485 exp   = expiration time
  486 la    = time in seconds since last access
  487 cas   = CAS ID
  488 fetch = whether an item has been fetched before
  489 cls   = slab class id
  490 size  = total size in bytes
  491 
  492 Others may be added.
  493 
  494 Meta Get
  495 --------
  496 
  497 The meta get command is the generic command for retrieving key data from
  498 memcached. Based on the flags supplied, it can replace all of the commands:
  499 "get", "gets", "gat", "gats", "touch", as well as adding new options.
  500 
  501 mg <key> <flags>*\r\n
  502 
  503 - <key> means one key string. Unlike "get" metaget can only take a single key.
  504 
  505 - <flags> are a set of single character codes ended with a space or newline.
  506   flags may have token strings after the initial character.
  507 
  508 After this command, the client expects an item to be returned, received as a
  509 text line followed by an optional data block.
  510 
  511 If a response line appearing in a retrieval request is not sent back
  512 by the server this means that the server does not
  513 have the item (because it was never stored, or stored
  514 but deleted to make space for more items, or expired, or explicitly
  515 deleted by a client).
  516 
  517 An item sent by the server looks like:
  518 
  519 VA <size> <flags>*\r\n
  520 <data block>\r\n
  521 
  522 - <size> is the size of <data block> in bytes, minus the \r\n
  523 
  524 - <flags>* are flags returned by the server, based on the command flags.
  525   They are added in order specified by the flags sent.
  526 
  527 - <data block> is the data for this item. Note that the data block is
  528   optional, requiring the 'v' flag to be supplied.
  529 
  530 If the request did not ask for a value in the response (v) flag, the server
  531 response looks like:
  532 
  533 HD <flags>*\r\n
  534 
  535 If the request resulted in a miss, the response looks like:
  536 
  537 EN\r\n
  538 
  539 Unless the (q) flag was supplied, which suppresses the status code for a miss.
  540 
  541 The flags used by the 'mg' command are:
  542 
  543 - b: interpret key as base64 encoded binary value
  544 - c: return item cas token
  545 - f: return client flags token
  546 - h: return whether item has been hit before as a 0 or 1
  547 - k: return key as a token
  548 - l: return time since item was last accessed in seconds
  549 - O(token): opaque value, consumes a token and copies back with response
  550 - q: use noreply semantics for return codes.
  551 - s: return item size token
  552 - t: return item TTL remaining in seconds (-1 for unlimited)
  553 - u: don't bump the item in the LRU
  554 - v: return item value in <data block>
  555 
  556 These flags can modify the item:
  557 - N(token): vivify on miss, takes TTL as a argument
  558 - R(token): if token is less than remaining TTL win for recache
  559 - T(token): update remaining TTL
  560 
  561 These extra flags can be added to the response:
  562 - W: client has "won" the recache flag
  563 - X: item is stale
  564 - Z: item has already sent a winning flag
  565 
  566 The flags are now repeated with detailed information where useful:
  567 
  568 - b: interpret key as base64 encoded binary value
  569 
  570 This flag instructs memcached to run a base64 decoder on <key> before looking
  571 it up. This allows storing and fetching of binary packed keys, so long as they
  572 are sent to memcached in base64 encoding.
  573 
  574 If 'b' flag is sent in the response, and a key is returned via 'k', this
  575 signals to the client that the key is base64 encoded binary.
  576 
  577 - h: return whether item has been hit before as a 0 or 1
  578 - l: return time since item was last accessed in seconds
  579 
  580 The above two flags return the value of "hit before?" and "last access time"
  581 before the command was processed. Otherwise this would always show a 1 for
  582 hit or always show an access time of "0" unless combined with the "u" flag.
  583 
  584 - O(token): opaque value, consumes a token and copies back with response
  585 
  586 The O(opaque) token is used by this and other commands to allow easier
  587 pipelining of requests while saving bytes on the wire for responses. For
  588 example: if pipelining three get commands together, you may not know which
  589 response belongs to which without also retrieving the key. If the key is very
  590 long this can generate a lot of traffic, especially if the data block is very
  591 small. Instead, you can supply an "O" flag for each mg with tokens of "1" "2"
  592 and "3", to match up responses to the request.
  593 
  594 Opaque tokens may be up to 32 bytes in length, and are a string similar to
  595 keys.
  596 
  597 - q: use noreply semantics for return codes.
  598 
  599 Noreply is a method of reducing the amount of data sent back by memcached to
  600 the client for normal responses. In the case of metaget, if an item is not
  601 available the "VA" line is normally not sent, and the response is terminated by
  602 "EN\r\n".
  603 
  604 With noreply enabled, the "EN\r\n" marker is suppressed. This allows you to
  605 pipeline several mg's together and read all of the responses without the
  606 "EN\r\n" lines in the middle.
  607 
  608 Errors are always returned.
  609 
  610 - u: don't bump the item in the LRU
  611 
  612 It is possible to access an item without causing it to be "bumped" to the head
  613 of the LRU. This also avoids marking an item as being hit or updating its last
  614 access time.
  615 
  616 - v: return item value in <data block>
  617 
  618 The data block for a metaget response is optional, requiring this flag to be
  619 passed in. The response code also changes from "HD" to "VA <size>"
  620 
  621 These flags can modify the item:
  622 - N(token): vivify on miss, takes TTL as a argument
  623 
  624 Used to help with so called "dog piling" problems with recaching of popular
  625 items. If supplied, and metaget does not find the item in cache, it will
  626 create a stub item with the key and TTL as supplied. If such an item is
  627 created a 'W' flag is added to the response to indicate to a client that they
  628 have "won" the right to recache an item.
  629 
  630 The automatically created item has 0 bytes of data.
  631 
  632 Further requests will see a 'Z' flag to indicate that another client has
  633 already received the win flag.
  634 
  635 Can be combined with CAS flags to gate the update further.
  636 
  637 - R(token): if token is less than remaining TTL win for recache
  638 
  639 Similar to and can be combined with 'N'. If the remaining TTL of an item is
  640 below the supplied token, return a 'W' flag to indicate the client has "won"
  641 the right to recache an item. This allows refreshing an item before it leads to
  642 a miss.
  643 
  644 - T(token): update remaining TTL
  645 
  646 Similar to "touch" and "gat" commands, updates the remaining TTL of an item if
  647 hit.
  648 
  649 These extra flags can be added to the response:
  650 - W: client has "won" the recache flag
  651 
  652 When combined with N or R flags, a client may be informed they have "won"
  653 ownership of a cache item. This allows a single client to be atomically
  654 notified that it should cache or update an item. Further clients requesting
  655 the item can use the existing data block (if valid or stale), retry, wait, or
  656 take some other action while the item is missing.
  657 
  658 This is used when the act of recaching an item can cause undue load on another
  659 system (CPU, database accesses, time, and so on).
  660 
  661 - X: item is stale
  662 
  663 Items can be marked as stale by the metadelete command. This indicates to the
  664 client that an object needs to be updated, and that it should make a decision
  665 o if potentially stale data is safe to use.
  666 
  667 This is used when you want to convince clients to recache an item, but it's
  668 safe to use pre-existing data while the recache happens.
  669 
  670 - Z: item has already sent a winning flag
  671 
  672 When combined with the X flag, or the client N or R flags, this extra response
  673 flag indicates to a client that a different client is responsible for
  674 recaching this item. If there is data supplied it may use it, or the client
  675 may decide to retry later or take some other action.
  676 
  677 Meta Set
  678 --------
  679 
  680 The meta set command a generic command for storing data to memcached. Based
  681 on the flags supplied, it can replace all storage commands (see token M) as
  682 well as adds new options.
  683 
  684 ms <key> <datalen> <flags>*\r\n
  685 
  686 - <key> means one key string.
  687 
  688 - <datalen> is the length of the payload data.
  689 
  690 - <flags> are a set of single character codes ended with a space or newline.
  691   flags may have strings after the initial character.
  692 
  693 After this line, the client sends the data block:
  694 
  695 <data block>\r\n
  696 
  697 - <data block> is a chunk of arbitrary 8-bit data of length supplied by an 'S'
  698   flag and token from the request line. If no 'S' flag is supplied the data
  699   is assumed to be 0 length.
  700 
  701 After sending the command line and the data block the client awaits
  702 the reply, which is of the format:
  703 
  704 <CD> <flags>*\r\n
  705 
  706 Where CD is one of:
  707 
  708 - "HD" (STORED), to indicate success.
  709 
  710 - "NS" (NOT_STORED), to indicate the data was not stored, but not
  711 because of an error.
  712 
  713 - "EX" (EXISTS), to indicate that the item you are trying to store with
  714 CAS semantics has been modified since you last fetched it.
  715 
  716 - "NF" (NOT_FOUND), to indicate that the item you are trying to store
  717 with CAS semantics did not exist.
  718 
  719 The flags used by the 'ms' command are:
  720 
  721 - b: interpret key as base64 encoded binary value (see metaget)
  722 - c: return CAS value if successfully stored.
  723 - C(token): compare CAS value when storing item
  724 - F(token): set client flags to token (32 bit unsigned numeric)
  725 - I: invalidate. set-to-invalid if supplied CAS is older than item's CAS
  726 - k: return key as a token
  727 - O(token): opaque value, consumes a token and copies back with response
  728 - q: use noreply semantics for return codes
  729 - T(token): Time-To-Live for item, see "Expiration" above.
  730 - M(token): mode switch to change behavior to add, replace, append, prepend
  731 
  732 The flags are now repeated with detailed information where useful:
  733 
  734 - c: returns the CAS value on successful storage. Will return 0 on error, but
  735   clients must not depend on the return value being zero. In future versions
  736 this may return the current CAS value for "EX" return code conditions.
  737 
  738 - C(token): compare CAS value when storing item
  739 
  740 Similar to the basic "cas" command, only store item if the supplied token
  741 matches the current CAS value of the item. When combined with the 'I' flag, a
  742 CAS value that is _lower_ than the current value may be accepted, but the item
  743 will be marked as "stale", returning the X flag with mget requests.
  744 
  745 - F(token): set client flags to token (32 bit unsigned numeric)
  746 
  747 Sets flags to 0 if not supplied.
  748 
  749 - I: invalid. set-to-invalid if CAS is older than it should be.
  750 
  751 Functional when combined with 'C' flag above.
  752 
  753 - O(token): opaque value, consumes a token and copies back with response
  754 
  755 See description under 'Meta Get'
  756 
  757 - q: use noreply semantics for return codes
  758 
  759 Noreply is a method of reducing the amount of data sent back by memcached to
  760 the client for normal responses. In the case of metaset, a response that
  761 would start with "HD" will not be sent. Any other code, such as "EX"
  762 (EXISTS) will still be returned.
  763 
  764 Errors are always returned.
  765 
  766 - M(token): mode switch. Takes a single character for the mode.
  767 
  768 E: "add" command. LRU bump and return NS if item exists. Else
  769 add.
  770 A: "append" command. If item exists, append the new value to its data.
  771 P: "prepend" command. If item exists, prepend the new value to its data.
  772 R: "replace" command. Set only if item already exists.
  773 S: "set" command. The default mode, added for completeness.
  774 
  775 The "cas" command is supplanted by specifying the cas value with the 'C' flag.
  776 Append and Prepend modes will also respect a supplied cas value.
  777 
  778 Meta Delete
  779 -----------
  780 
  781 The meta delete command allows for explicit deletion of items, as well as
  782 marking items as "stale" to allow serving items as stale during revalidation.
  783 
  784 md <key> <flags>*\r\n
  785 
  786 - <key> means one key string.
  787 
  788 - <flags> are a set of single character codes ended with a space or newline.
  789   flags may have strings after the initial character.
  790 
  791 The response is in the format:
  792 
  793 <CD> <flags> <tokens>*\r\n
  794 
  795 Where CD is one of:
  796 
  797 - "HD" (DELETED), to indicate success
  798 
  799 - "NF" (NOT_FOUND), to indicate that the item with this key was not found.
  800 
  801 - "EX" (EXISTS), to indicate that the supplied CAS token does not match the
  802   stored item.
  803 
  804 The flags used by the 'md' command are:
  805 
  806 - b: interpret key as base64 encoded binary value (see metaget)
  807 - C(token): compare CAS value
  808 - I: invalidate. mark as stale, bumps CAS.
  809 - k: return key
  810 - O(token): opaque to copy back.
  811 - q: noreply
  812 - T(token): updates TTL, only when paired with the 'I' flag
  813 
  814 The flags are now repeated with detailed information where useful:
  815 
  816 - C(token): compare CAS value
  817 
  818 Can be used to only delete or mark-stale if a supplied CAS value matches.
  819 
  820 - I: invalidate. mark as stale, bumps CAS.
  821 
  822 Instead of removing an item, this will give the item a new CAS value and mark
  823 it as stale. This means when it is later fetched by metaget, the client will
  824 be supplied an 'X' flag to show the data is stale and needs to be recached.
  825 
  826 - O(token): opaque to copy back.
  827 
  828 See description under 'Meta Get'
  829 
  830 - q: noreply
  831 
  832 See description under 'Meta Set'. In the case of meta delete, this will hide
  833 response lines with the code "DE". It will still return any other responses.
  834 
  835 - T(token): updates TTL, only when paired with the 'I' flag
  836 
  837 When marking an item as stale with 'I', the 'T' flag can be used to update the
  838 TTL as well; limiting the amount of time an item will live while stale and
  839 waiting to be recached.
  840 
  841 Meta Arithmetic
  842 ---------------
  843 
  844 The meta arithmetic command allows for basic operations against numerical
  845 values. This replaces the "incr" and "decr" commands. Values are unsigned
  846 64bit integers. Decrementing will reach 0 rather than underflow. Incrementing
  847 can overflow.
  848 
  849 ma <key> <flags>*\r\n
  850 
  851 - <key> means one key string.
  852 
  853 - <flags> are a set of single character codes ended with a space or newline.
  854   flags may have strings after the initial character.
  855 
  856 The response is in the format:
  857 
  858 <CD> <flags> <tokens>*\r\n
  859 
  860 Where CD is one of:
  861 
  862 - "HD" to indicate success
  863 
  864 - "NF" (NOT_FOUND), to indicate that the item with this key was not found.
  865 
  866 - "NS" (NOT_STORED), to indicate that the item was not created as requested
  867   after a miss.
  868 
  869 - "EX" (EXISTS), to indicate that the supplied CAS token does not match the
  870   stored item.
  871 
  872 If the 'v' flag is supplied, the response is formatted as:
  873 
  874 VA <size> <flags>*\r\n
  875 <number>\r\n
  876 
  877 The flags used by the 'ma' command are:
  878 
  879 - b: interpret key as base64 encoded binary value (see metaget)
  880 - C(token): compare CAS value (see mset)
  881 - N(token): auto create item on miss with supplied TTL
  882 - J(token): initial value to use if auto created after miss (default 0)
  883 - D(token): delta to apply (decimal unsigned 64-bit number, default 1)
  884 - T(token): update TTL on success
  885 - M(token): mode switch to change between incr and decr modes.
  886 - q: use noreply semantics for return codes (see details under mset)
  887 - t: return current TTL
  888 - c: return current CAS value if successful.
  889 - v: return new value
  890 
  891 The flags are now repeated with detailed information where useful:
  892 
  893 - C(token): compare CAS value
  894 
  895 Can be used to only incr/decr if a supplied CAS value matches. A new CAS value
  896 is generated after a delta is applied. Add the 'c' flag to get the new CAS
  897 value after success.
  898 
  899 - N(token): auto create item on miss with supplied TTL
  900 
  901 Similar to mget, on a miss automatically create the item. A value can be
  902 seeded using the J flag.
  903 
  904 - J(token): initial value
  905 
  906 An unsigned 64-bit integer which will be seeded as the value on a miss. Must be
  907 combined with an N flag.
  908 
  909 - D(token): delta to apply
  910 
  911 An unsigned integer to either add or subtract from the currently stored
  912 number.
  913 
  914 - T(token): update TTL
  915 
  916 On success, sets the remaining TTL to the supplied value.
  917 
  918 -M(token): mode switch. Takes a single character for the mode.
  919 
  920 I: Increment mode (default)
  921 +: Alias for increment
  922 D: Decrement mode
  923 -: Alias for decrement
  924 
  925 Meta No-Op
  926 ----------
  927 
  928 The meta no-op command exists solely to return a static response code. It
  929 takes no flags, no arguments.
  930 
  931 "mn\r\n"
  932 
  933 This returns the static response:
  934 
  935 "MN\r\n"
  936 
  937 This command is useful when used with the 'q' flag and pipelining commands.
  938 For example, with 'mg' the response lines are blank on miss when the 'q' flag
  939 is supplied. If pipelining several 'mg's together with noreply semantics, an
  940 "mn\r\n" command can be tagged to the end of the chain, which will return an
  941 "MN\r\n", signalling to a client that all previous commands have been
  942 processed.
  943 
  944 Slabs Reassign
  945 --------------
  946 
  947 NOTE: This command is subject to change as of this writing.
  948 
  949 The slabs reassign command is used to redistribute memory once a running
  950 instance has hit its limit. It might be desirable to have memory laid out
  951 differently than was automatically assigned after the server started.
  952 
  953 slabs reassign <source class> <dest class>\r\n
  954 
  955 - <source class> is an id number for the slab class to steal a page from
  956 
  957 A source class id of -1 means "pick from any valid class"
  958 
  959 - <dest class> is an id number for the slab class to move a page to
  960 
  961 The response line could be one of:
  962 
  963 - "OK" to indicate the page has been scheduled to move
  964 
  965 - "BUSY [message]" to indicate a page is already being processed, try again
  966   later.
  967 
  968 - "BADCLASS [message]" a bad class id was specified
  969 
  970 - "NOSPARE [message]" source class has no spare pages
  971 
  972 - "NOTFULL [message]" dest class must be full to move new pages to it
  973 
  974 - "UNSAFE [message]" source class cannot move a page right now
  975 
  976 - "SAME [message]" must specify different source/dest ids.
  977 
  978 Slabs Automove
  979 --------------
  980 
  981 NOTE: This command is subject to change as of this writing.
  982 
  983 The slabs automove command enables a background thread which decides on its
  984 own when to move memory between slab classes. Its implementation and options
  985 will likely be in flux for several versions. See the wiki/mailing list for
  986 more details.
  987 
  988 The automover can be enabled or disabled at runtime with this command.
  989 
  990 slabs automove <0|1>
  991 
  992 - 0|1|2 is the indicator on whether to enable the slabs automover or not.
  993 
  994 The response should always be "OK\r\n"
  995 
  996 - <0> means to set the thread on standby
  997 
  998 - <1> means to return pages to a global pool when there are more than 2 pages
  999   worth of free chunks in a slab class. Pages are then re-assigned back into
 1000   other classes as-needed.
 1001 
 1002 - <2> is a highly aggressive mode which causes pages to be moved every time
 1003   there is an eviction. It is not recommended to run for very long in this
 1004   mode unless your access patterns are very well understood.
 1005 
 1006 LRU Tuning
 1007 ----------
 1008 
 1009 Memcached supports multiple LRU algorithms, with a few tunables. Effort is
 1010 made to have sane defaults however you are able to tune while the daemon is
 1011 running.
 1012 
 1013 The traditional model is "flat" mode, which is a single LRU chain per slab
 1014 class. The newer (with `-o modern` or `-o lru_maintainer`) is segmented into
 1015 HOT, WARM, COLD. There is also a TEMP LRU. See doc/new_lru.txt for details.
 1016 
 1017 lru <tune|mode|temp_ttl> <option list>
 1018 
 1019 - "tune" takes numeric arguments "percent hot", "percent warm",
 1020   "max hot factor", "max warm age factor". IE: "lru tune 10 25 0.1 2.0".
 1021   This would cap HOT_LRU at 10% of the cache, or tail is idle longer than
 1022   10% of COLD_LRU. WARM_LRU is up to 25% of cache, or tail is idle longer
 1023   than 2x COLD_LRU.
 1024 
 1025 - "mode" <flat|segmented>: "flat" is traditional mode. "segmented" uses
 1026   HOT|WARM|COLD split. "segmented" mode requires `-o lru_maintainer` at start
 1027   time. If switching from segmented to flat mode, the background thread will
 1028   pull items from HOT|WARM into COLD queue.
 1029 
 1030 - "temp_ttl" <ttl>: If TTL is less than zero, disable usage of TEMP_LRU. If
 1031   zero or above, items set with a TTL lower than this will go into TEMP_LRU
 1032   and be unevictable until they naturally expire or are otherwise deleted or
 1033   replaced.
 1034 
 1035 The response line could be one of:
 1036 
 1037 - "OK" to indicate a successful update of the settings.
 1038 
 1039 - "ERROR [message]" to indicate a failure or improper arguments.
 1040 
 1041 LRU_Crawler
 1042 -----------
 1043 
 1044 NOTE: This command (and related commands) are subject to change as of this
 1045 writing.
 1046 
 1047 The LRU Crawler is an optional background thread which will walk from the tail
 1048 toward the head of requested slab classes, actively freeing memory for expired
 1049 items. This is useful if you have a mix of items with both long and short
 1050 TTL's, but aren't accessed very often. This system is not required for normal
 1051 usage, and can add small amounts of latency and increase CPU usage.
 1052 
 1053 lru_crawler <enable|disable>
 1054 
 1055 - Enable or disable the LRU Crawler background thread.
 1056 
 1057 The response line could be one of:
 1058 
 1059 - "OK" to indicate the crawler has been started or stopped.
 1060 
 1061 - "ERROR [message]" something went wrong while enabling or disabling.
 1062 
 1063 lru_crawler sleep <microseconds>
 1064 
 1065 - The number of microseconds to sleep in between each item checked for
 1066   expiration. Smaller numbers will obviously impact the system more.
 1067   A value of "0" disables the sleep, "1000000" (one second) is the max.
 1068 
 1069 The response line could be one of:
 1070 
 1071 - "OK"
 1072 
 1073 - "CLIENT_ERROR [message]" indicating a format or bounds issue.
 1074 
 1075 lru_crawler tocrawl <32u>
 1076 
 1077 - The maximum number of items to inspect in a slab class per run request. This
 1078   allows you to avoid scanning all of very large slabs when it is unlikely to
 1079   find items to expire.
 1080 
 1081 The response line could be one of:
 1082 
 1083 - "OK"
 1084 
 1085 - "CLIENT_ERROR [message]" indicating a format or bound issue.
 1086 
 1087 lru_crawler crawl <classid,classid,classid|all>
 1088 
 1089 - Takes a single, or a list of, numeric classids (ie: 1,3,10). This instructs
 1090   the crawler to start at the tail of each of these classids and run to the
 1091   head. The crawler cannot be stopped or restarted until it completes the
 1092   previous request.
 1093 
 1094   The special keyword "all" instructs it to crawl all slabs with items in
 1095   them.
 1096 
 1097 The response line could be one of:
 1098 
 1099 - "OK" to indicate successful launch.
 1100 
 1101 - "BUSY [message]" to indicate the crawler is already processing a request.
 1102 
 1103 - "BADCLASS [message]" to indicate an invalid class was specified.
 1104 
 1105 lru_crawler metadump <classid,classid,classid|all|hash>
 1106 
 1107 - Similar in function to the above "lru_crawler crawl" command, this function
 1108   outputs one line for every valid item found in the matching slab classes.
 1109   Similar to "cachedump", but does not lock the cache and can return all
 1110   items, not just 1MB worth.
 1111 
 1112   if "hash" is specified instead of a classid or "all", the crawler will dump
 1113   items by directly walking the hash table instead of the LRU's. This makes it
 1114   more likely all items will be visited once as LRU reordering and locking can
 1115   cause frequently accessed items to be missed.
 1116 
 1117   Lines are in "key=value key2=value2" format, with value being URI encoded
 1118   (ie: %20 for a space).
 1119 
 1120   The exact keys available are subject to change, but will include at least:
 1121 
 1122   "key", "exp" (expiration time), "la", (last access time), "cas",
 1123   "fetch" (if item has been fetched before).
 1124 
 1125 The response line could be one of:
 1126 
 1127 - "OK" to indicate successful launch.
 1128 
 1129 - "BUSY [message]" to indicate the crawler is already processing a request.
 1130 
 1131 - "BADCLASS [message]" to indicate an invalid class was specified.
 1132 
 1133 Watchers
 1134 --------
 1135 
 1136 Watchers are a way to connect to memcached and inspect what's going on
 1137 internally. This is an evolving feature so new endpoints should show up over
 1138 time.
 1139 
 1140 watch <fetchers|mutations|evictions|connevents>
 1141 
 1142 - Turn connection into a watcher. Options can be stacked and are
 1143   space-separated. Logs will be sent to the watcher until it disconnects.
 1144 
 1145 The response line could be one of:
 1146 
 1147 - "OK" to indicate the watcher is ready to send logs.
 1148 
 1149 - "ERROR [message]" something went wrong while enabling.
 1150 
 1151 The response format is in "key=value key2=value2" format, for easy parsing.
 1152 Lines are prepending with "ts=" for a timestamp and "gid=" for a global ID
 1153 number of the log line. Given how logs are collected internally they may be
 1154 printed out of order. If this is important the GID may be used to put log
 1155 lines back in order.
 1156 
 1157 The value of keys (and potentially other things) are "URI encoded". Since most
 1158 keys used conform to standard ASCII, this should have no effect. For keys with
 1159 less standard or binary characters, "%NN"'s are inserted to represent the
 1160 byte, ie: "n%2Cfoo" for "n,foo".
 1161 
 1162 The arguments are:
 1163 
 1164 - "fetchers": Currently emits logs every time an item is fetched internally.
 1165   This means a "set" command would also emit an item_get log, as it checks for
 1166   an item before replacing it. Multigets should also emit multiple lines.
 1167 
 1168 - "mutations": Currently emits logs when an item is stored in most cases.
 1169   Shows errors for most cases when items cannot be stored.
 1170 
 1171 - "evictions": Shows some information about items as they are evicted from the
 1172   cache. Useful in seeing if items being evicted were actually used, and which
 1173   keys are getting removed.
 1174 
 1175 - "connevents": Emits logs when connections are opened and closed, i.e. when
 1176   clients connect or disconnect. For TCP transports, logs indicate the remote
 1177   address IP and port. Connection close events additionally supply a reason for
 1178   closing the connection.
 1179 
 1180 - "proxycmds": Emits detailed timing logs about requests/responses being
 1181   returned to a client while in proxy mode. The conditions which logs are
 1182   written here may be influenced by configuration.
 1183 
 1184 - "proxyevents": Emits internal proxy errors and system events, such as
 1185   configuration reloads.
 1186 
 1187 - "proxyuser": Emits log entries created from lua configuration files.
 1188 
 1189 Statistics
 1190 ----------
 1191 
 1192 The command "stats" is used to query the server about statistics it
 1193 maintains and other internal data. It has two forms. Without
 1194 arguments:
 1195 
 1196 stats\r\n
 1197 
 1198 it causes the server to output general-purpose statistics and
 1199 settings, documented below.  In the other form it has some arguments:
 1200 
 1201 stats <args>\r\n
 1202 
 1203 Depending on <args>, various internal data is sent by the server. The
 1204 kinds of arguments and the data sent are not documented in this version
 1205 of the protocol, and are subject to change for the convenience of
 1206 memcache developers.
 1207 
 1208 
 1209 General-purpose statistics
 1210 --------------------------
 1211 
 1212 Upon receiving the "stats" command without arguments, the server sends
 1213 a number of lines which look like this:
 1214 
 1215 STAT <name> <value>\r\n
 1216 
 1217 The server terminates this list with the line
 1218 
 1219 END\r\n
 1220 
 1221 In each line of statistics, <name> is the name of this statistic, and
 1222 <value> is the data.  The following is the list of all names sent in
 1223 response to the "stats" command, together with the type of the value
 1224 sent for this name, and the meaning of the value.
 1225 
 1226 In the type column below, "32u" means a 32-bit unsigned integer, "64u"
 1227 means a 64-bit unsigned integer. '32u.32u' means two 32-bit unsigned
 1228 integers separated by a colon (treat this as a floating point number).
 1229 
 1230 |-----------------------+---------+-------------------------------------------|
 1231 | Name                  | Type    | Meaning                                   |
 1232 |-----------------------+---------+-------------------------------------------|
 1233 | pid                   | 32u     | Process id of this server process         |
 1234 | uptime                | 32u     | Number of secs since the server started   |
 1235 | time                  | 32u     | current UNIX time according to the server |
 1236 | version               | string  | Version string of this server             |
 1237 | pointer_size          | 32      | Default size of pointers on the host OS   |
 1238 |                       |         | (generally 32 or 64)                      |
 1239 | rusage_user           | 32u.32u | Accumulated user time for this process    |
 1240 |                       |         | (seconds:microseconds)                    |
 1241 | rusage_system         | 32u.32u | Accumulated system time for this process  |
 1242 |                       |         | (seconds:microseconds)                    |
 1243 | curr_items            | 64u     | Current number of items stored            |
 1244 | total_items           | 64u     | Total number of items stored since        |
 1245 |                       |         | the server started                        |
 1246 | bytes                 | 64u     | Current number of bytes used              |
 1247 |                       |         | to store items                            |
 1248 | max_connections       | 32u     | Max number of simultaneous connections    |
 1249 | curr_connections      | 32u     | Number of open connections                |
 1250 | total_connections     | 32u     | Total number of connections opened since  |
 1251 |                       |         | the server started running                |
 1252 | rejected_connections  | 64u     | Conns rejected in maxconns_fast mode      |
 1253 | connection_structures | 32u     | Number of connection structures allocated |
 1254 |                       |         | by the server                             |
 1255 | response_obj_oom      | 64u     | Connections closed by lack of memory      |
 1256 | response_obj_count    | 64u     | Total response objects in use             |
 1257 | response_obj_bytes    | 64u     | Total bytes used for resp. objects. is a  |
 1258 |                       |         | subset of bytes from read_buf_bytes.      |
 1259 | read_buf_count        | 64u     | Total read/resp buffers allocated         |
 1260 | read_buf_bytes        | 64u     | Total read/resp buffer bytes allocated    |
 1261 | read_buf_bytes_free   | 64u     | Total read/resp buffer bytes cached       |
 1262 | read_buf_oom          | 64u     | Connections closed by lack of memory      |
 1263 | reserved_fds          | 32u     | Number of misc fds used internally        |
 1264 | proxy_conn_requests   | 64u     | Number of requests received by the proxy  |
 1265 | proxy_conn_errors     | 64u     | Number of internal errors from proxy      |
 1266 | proxy_conn_oom        | 64u     | Number of out of memory errors while      |
 1267 |                       |         | serving proxy requests                    |
 1268 | proxy_req_active      | 64u     | Number of in-flight proxy requests        |
 1269 | cmd_get               | 64u     | Cumulative number of retrieval reqs       |
 1270 | cmd_set               | 64u     | Cumulative number of storage reqs         |
 1271 | cmd_flush             | 64u     | Cumulative number of flush reqs           |
 1272 | cmd_touch             | 64u     | Cumulative number of touch reqs           |
 1273 | get_hits              | 64u     | Number of keys that have been requested   |
 1274 |                       |         | and found present                         |
 1275 | get_misses            | 64u     | Number of items that have been requested  |
 1276 |                       |         | and not found                             |
 1277 | get_expired           | 64u     | Number of items that have been requested  |
 1278 |                       |         | but had already expired.                  |
 1279 | get_flushed           | 64u     | Number of items that have been requested  |
 1280 |                       |         | but have been flushed via flush_all       |
 1281 | delete_misses         | 64u     | Number of deletions reqs for missing keys |
 1282 | delete_hits           | 64u     | Number of deletion reqs resulting in      |
 1283 |                       |         | an item being removed.                    |
 1284 | incr_misses           | 64u     | Number of incr reqs against missing keys. |
 1285 | incr_hits             | 64u     | Number of successful incr reqs.           |
 1286 | decr_misses           | 64u     | Number of decr reqs against missing keys. |
 1287 | decr_hits             | 64u     | Number of successful decr reqs.           |
 1288 | cas_misses            | 64u     | Number of CAS reqs against missing keys.  |
 1289 | cas_hits              | 64u     | Number of successful CAS reqs.            |
 1290 | cas_badval            | 64u     | Number of CAS reqs for which a key was    |
 1291 |                       |         | found, but the CAS value did not match.   |
 1292 | touch_hits            | 64u     | Number of keys that have been touched     |
 1293 |                       |         | with a new expiration time                |
 1294 | touch_misses          | 64u     | Number of items that have been touched    |
 1295 |                       |         | and not found                             |
 1296 | store_too_large       | 64u     | Number of rejected storage requests       |
 1297 |                       |         | caused by attempting to write a value     |
 1298 |                       |         | larger than the -I limit                  |
 1299 | store_no_memory       | 64u     | Number of rejected storage requests       |
 1300 |                       |         | caused by exhaustion of the -m memory     |
 1301 |                       |         | limit (relevant when -M is used)          |
 1302 | auth_cmds             | 64u     | Number of authentication commands         |
 1303 |                       |         | handled, success or failure.              |
 1304 | auth_errors           | 64u     | Number of failed authentications.         |
 1305 | idle_kicks            | 64u     | Number of connections closed due to       |
 1306 |                       |         | reaching their idle timeout.              |
 1307 | evictions             | 64u     | Number of valid items removed from cache  |
 1308 |                       |         | to free memory for new items              |
 1309 | reclaimed             | 64u     | Number of times an entry was stored using |
 1310 |                       |         | memory from an expired entry              |
 1311 | bytes_read            | 64u     | Total number of bytes read by this server |
 1312 |                       |         | from network                              |
 1313 | bytes_written         | 64u     | Total number of bytes sent by this server |
 1314 |                       |         | to network                                |
 1315 | limit_maxbytes        | size_t  | Number of bytes this server is allowed to |
 1316 |                       |         | use for storage.                          |
 1317 | accepting_conns       | bool    | Whether or not server is accepting conns  |
 1318 | listen_disabled_num   | 64u     | Number of times server has stopped        |
 1319 |                       |         | accepting new connections (maxconns).     |
 1320 | time_in_listen_disabled_us                                                  |
 1321 |                       | 64u     | Number of microseconds in maxconns.       |
 1322 | threads               | 32u     | Number of worker threads requested.       |
 1323 |                       |         | (see doc/threads.txt)                     |
 1324 | conn_yields           | 64u     | Number of times any connection yielded to |
 1325 |                       |         | another due to hitting the -R limit.      |
 1326 | hash_power_level      | 32u     | Current size multiplier for hash table    |
 1327 | hash_bytes            | 64u     | Bytes currently used by hash tables       |
 1328 | hash_is_expanding     | bool    | Indicates if the hash table is being      |
 1329 |                       |         | grown to a new size                       |
 1330 | expired_unfetched     | 64u     | Items pulled from LRU that were never     |
 1331 |                       |         | touched by get/incr/append/etc before     |
 1332 |                       |         | expiring                                  |
 1333 | evicted_unfetched     | 64u     | Items evicted from LRU that were never    |
 1334 |                       |         | touched by get/incr/append/etc.           |
 1335 | evicted_active        | 64u     | Items evicted from LRU that had been hit  |
 1336 |                       |         | recently but did not jump to top of LRU   |
 1337 | slab_reassign_running | bool    | If a slab page is being moved             |
 1338 | slabs_moved           | 64u     | Total slab pages moved                    |
 1339 | crawler_reclaimed     | 64u     | Total items freed by LRU Crawler          |
 1340 | crawler_items_checked | 64u     | Total items examined by LRU Crawler       |
 1341 | lrutail_reflocked     | 64u     | Times LRU tail was found with active ref. |
 1342 |                       |         | Items can be evicted to avoid OOM errors. |
 1343 | moves_to_cold         | 64u     | Items moved from HOT/WARM to COLD LRU's   |
 1344 | moves_to_warm         | 64u     | Items moved from COLD to WARM LRU         |
 1345 | moves_within_lru      | 64u     | Items reshuffled within HOT or WARM LRU's |
 1346 | direct_reclaims       | 64u     | Times worker threads had to directly      |
 1347 |                       |         | reclaim or evict items.                   |
 1348 | lru_crawler_starts    | 64u     | Times an LRU crawler was started          |
 1349 | lru_maintainer_juggles                                                      |
 1350 |                       | 64u     | Number of times the LRU bg thread woke up |
 1351 | slab_global_page_pool | 32u     | Slab pages returned to global pool for    |
 1352 |                       |         | reassignment to other slab classes.       |
 1353 | slab_reassign_rescues | 64u     | Items rescued from eviction in page move  |
 1354 | slab_reassign_evictions_nomem                                               |
 1355 |                       | 64u     | Valid items evicted during a page move    |
 1356 |                       |         | (due to no free memory in slab)           |
 1357 | slab_reassign_chunk_rescues                                                 |
 1358 |                       | 64u     | Individual sections of an item rescued    |
 1359 |                       |         | during a page move.                       |
 1360 | slab_reassign_inline_reclaim                                                |
 1361 |                       | 64u     | Internal stat counter for when the page   |
 1362 |                       |         | mover clears memory from the chunk        |
 1363 |                       |         | freelist when it wasn't expecting to.     |
 1364 | slab_reassign_busy_items                                                    |
 1365 |                       | 64u     | Items busy during page move, requiring a  |
 1366 |                       |         | retry before page can be moved.           |
 1367 | slab_reassign_busy_deletes                                                  |
 1368 |                       | 64u     | Items busy during page move, requiring    |
 1369 |                       |         | deletion before page can be moved.        |
 1370 | log_worker_dropped    | 64u     | Logs a worker never wrote due to full buf |
 1371 | log_worker_written    | 64u     | Logs written by a worker, to be picked up |
 1372 | log_watcher_skipped   | 64u     | Logs not sent to slow watchers.           |
 1373 | log_watcher_sent      | 64u     | Logs written to watchers.                 |
 1374 | log_watchers          | 64u     | Number of currently active watchers.      |
 1375 | unexpected_napi_ids   | 64u     | Number of times an unexpected napi id is  |
 1376 |                       |         | is received. See doc/napi_ids.txt         |
 1377 | round_robin_fallback  | 64u     | Number of times napi id of 0 is received  |
 1378 |                       |         | resulting in fallback to round robin      |
 1379 |                       |         | thread selection. See doc/napi_ids.txt    |
 1380 |-----------------------+---------+-------------------------------------------|
 1381 
 1382 Settings statistics
 1383 -------------------
 1384 CAVEAT: This section describes statistics which are subject to change in the
 1385 future.
 1386 
 1387 The "stats" command with the argument of "settings" returns details of
 1388 the settings of the running memcached.  This is primarily made up of
 1389 the results of processing commandline options.
 1390 
 1391 Note that these are not guaranteed to return in any specific order and
 1392 this list may not be exhaustive.  Otherwise, this returns like any
 1393 other stats command.
 1394 
 1395 |-------------------+----------+----------------------------------------------|
 1396 | Name              | Type     | Meaning                                      |
 1397 |-------------------+----------+----------------------------------------------|
 1398 | maxbytes          | size_t   | Maximum number of bytes allowed in the cache |
 1399 | maxconns          | 32       | Maximum number of clients allowed.           |
 1400 | tcpport           | 32       | TCP listen port.                             |
 1401 | udpport           | 32       | UDP listen port.                             |
 1402 | inter             | string   | Listen interface.                            |
 1403 | verbosity         | 32       | 0 = none, 1 = some, 2 = lots                 |
 1404 | oldest            | 32u      | Age of the oldest honored object.            |
 1405 | evictions         | on/off   | When off, LRU evictions are disabled.        |
 1406 | domain_socket     | string   | Path to the domain socket (if any).          |
 1407 | umask             | 32 (oct) | umask for the creation of the domain socket. |
 1408 | shutdown_command  | yes/no   | If shutdown admin command is enabled.        |
 1409 | growth_factor     | float    | Chunk size growth factor.                    |
 1410 | chunk_size        | 32       | Minimum space allocated for key+value+flags. |
 1411 | num_threads       | 32       | Number of threads (including dispatch).      |
 1412 | stat_key_prefix   | char     | Stats prefix separator character.            |
 1413 | detail_enabled    | bool     | If yes, stats detail is enabled.             |
 1414 | reqs_per_event    | 32       | Max num IO ops processed within an event.    |
 1415 | cas_enabled       | bool     | When no, CAS is not enabled for this server. |
 1416 | tcp_backlog       | 32       | TCP listen backlog.                          |
 1417 | auth_enabled_sasl | yes/no   | SASL auth requested and enabled.             |
 1418 | item_size_max     | size_t   | maximum item size                            |
 1419 | maxconns_fast     | bool     | If fast disconnects are enabled              |
 1420 | hashpower_init    | 32       | Starting size multiplier for hash table      |
 1421 | slab_reassign     | bool     | Whether slab page reassignment is allowed    |
 1422 | slab_automove     | bool     | Whether slab page automover is enabled       |
 1423 | slab_automove_ratio                                                         |
 1424 |                   | float    | Ratio limit between young/old slab classes   |
 1425 | slab_automove_window                                                        |
 1426 |                   | 32u      | Internal algo tunable for automove           |
 1427 | slab_chunk_max    | 32       | Max slab class size (avoid unless necessary) |
 1428 | hash_algorithm    | char     | Hash table algorithm in use                  |
 1429 | lru_crawler       | bool     | Whether the LRU crawler is enabled           |
 1430 | lru_crawler_sleep | 32       | Microseconds to sleep between LRU crawls     |
 1431 | lru_crawler_tocrawl                                                         |
 1432 |                   | 32u      | Max items to crawl per slab per run          |
 1433 | lru_maintainer_thread                                                       |
 1434 |                   | bool     | Split LRU mode and background threads        |
 1435 | hot_lru_pct       | 32       | Pct of slab memory reserved for HOT LRU      |
 1436 | warm_lru_pct      | 32       | Pct of slab memory reserved for WARM LRU     |
 1437 | hot_max_factor    | float    | Set idle age of HOT LRU to COLD age * this   |
 1438 | warm_max_factor   | float    | Set idle age of WARM LRU to COLD age * this  |
 1439 | temp_lru          | bool     | If yes, items < temporary_ttl use TEMP_LRU   |
 1440 | temporary_ttl     | 32u      | Items with TTL < this are marked  temporary  |
 1441 | idle_time         | 0        | Drop connections that are idle this many     |
 1442 |                   |          | seconds (0 disables)                         |
 1443 | watcher_logbuf_size                                                         |
 1444 |                   | 32u      | Size of internal (not socket) write buffer   |
 1445 |                   |          | per active watcher connected.                |
 1446 | worker_logbuf_size| 32u      | Size of internal per-worker-thread buffer    |
 1447 |                   |          | which the background thread reads from.      |
 1448 | read_obj_mem_limit| 32u      | Megabyte limit for conn. read/resp buffers.  |
 1449 | track_sizes       | bool     | If yes, a "stats sizes" histogram is being   |
 1450 |                   |          | dynamically tracked.                         |
 1451 | inline_ascii_response                                                       |
 1452 |                   | bool     | Does nothing as of 1.5.15                    |
 1453 | drop_privileges   | bool     | If yes, and available, drop unused syscalls  |
 1454 |                   |          | (see seccomp on Linux, pledge on OpenBSD)    |
 1455 | proxy_enabled     | bool     | If proxy has been configured at start        |
 1456 | proxy_uring_enabled                                                         |
 1457                     | bool     | If proxy is configured to use IO_URING.      |
 1458                     |          | NOTE: uring may be used if kernel too old    |
 1459 | memory_file       | char     | Warm restart memory file path, if enabled    |
 1460 |-------------------+----------+----------------------------------------------|
 1461 
 1462 
 1463 Item statistics
 1464 ---------------
 1465 CAVEAT: This section describes statistics which are subject to change in the
 1466 future.
 1467 
 1468 The "stats" command with the argument of "items" returns information about
 1469 item storage per slab class. The data is returned in the format:
 1470 
 1471 STAT items:<slabclass>:<stat> <value>\r\n
 1472 
 1473 The server terminates this list with the line
 1474 
 1475 END\r\n
 1476 
 1477 The slabclass aligns with class ids used by the "stats slabs" command. Where
 1478 "stats slabs" describes size and memory usage, "stats items" shows higher
 1479 level information.
 1480 
 1481 The following item values are defined as of writing.
 1482 
 1483 Name                   Meaning
 1484 ------------------------------
 1485 number                 Number of items presently stored in this class. Expired
 1486                        items are not automatically excluded.
 1487 number_hot             Number of items presently stored in the HOT LRU.
 1488 number_warm            Number of items presently stored in the WARM LRU.
 1489 number_cold            Number of items presently stored in the COLD LRU.
 1490 number_temp            Number of items presently stored in the TEMPORARY LRU.
 1491 age_hot                Age of the oldest item in HOT LRU.
 1492 age_warm               Age of the oldest item in WARM LRU.
 1493 age                    Age of the oldest item in the LRU.
 1494 mem_requested          Number of bytes requested to be stored in this LRU[*]
 1495 evicted                Number of times an item had to be evicted from the LRU
 1496                        before it expired.
 1497 evicted_nonzero        Number of times an item which had an explicit expire
 1498                        time set had to be evicted from the LRU before it
 1499                        expired.
 1500 evicted_time           Seconds since the last access for the most recent item
 1501                        evicted from this class. Use this to judge how
 1502                        recently active your evicted data is.
 1503 outofmemory            Number of times the underlying slab class was unable to
 1504                        store a new item. This means you are running with -M or
 1505                        an eviction failed.
 1506 tailrepairs            Number of times we self-healed a slab with a refcount
 1507                        leak. If this counter is increasing a lot, please
 1508                        report your situation to the developers.
 1509 reclaimed              Number of times an entry was stored using memory from
 1510                        an expired entry.
 1511 expired_unfetched      Number of expired items reclaimed from the LRU which
 1512                        were never touched after being set.
 1513 evicted_unfetched      Number of valid items evicted from the LRU which were
 1514                        never touched after being set.
 1515 evicted_active         Number of valid items evicted from the LRU which were
 1516                        recently touched but were evicted before being moved to
 1517                        the top of the LRU again.
 1518 crawler_reclaimed      Number of items freed by the LRU Crawler.
 1519 lrutail_reflocked      Number of items found to be refcount locked in the
 1520                        LRU tail.
 1521 moves_to_cold          Number of items moved from HOT or WARM into COLD.
 1522 moves_to_warm          Number of items moved from COLD to WARM.
 1523 moves_within_lru       Number of times active items were bumped within
 1524                        HOT or WARM.
 1525 direct_reclaims        Number of times worker threads had to directly pull LRU
 1526                        tails to find memory for a new item.
 1527 hits_to_hot
 1528 hits_to_warm
 1529 hits_to_cold
 1530 hits_to_temp           Number of get_hits to each sub-LRU.
 1531 
 1532 Note this will only display information about slabs which exist, so an empty
 1533 cache will return an empty set.
 1534 
 1535 * Items are stored in a slab that is the same size or larger than the
 1536   item.  mem_requested shows the size of all items within a
 1537   slab. (total_chunks * chunk_size) - mem_requested shows memory
 1538   wasted in a slab class.  If you see a lot of waste, consider tuning
 1539   the slab factor.
 1540 
 1541 
 1542 Item size statistics
 1543 --------------------
 1544 CAVEAT: This section describes statistics which are subject to change in the
 1545 future.
 1546 
 1547 The "stats" command with the argument of "sizes" returns information about the
 1548 general size and count of all items stored in the cache.
 1549 WARNING: In versions prior to 1.4.27 this command causes the cache server to
 1550 lock while it iterates the items. 1.4.27 and greater are safe.
 1551 
 1552 The data is returned in the following format:
 1553 
 1554 STAT <size> <count>\r\n
 1555 
 1556 The server terminates this list with the line
 1557 
 1558 END\r\n
 1559 
 1560 'size' is an approximate size of the item, within 32 bytes.
 1561 'count' is the amount of items that exist within that 32-byte range.
 1562 
 1563 This is essentially a display of all of your items if there was a slab class
 1564 for every 32 bytes. You can use this to determine if adjusting the slab growth
 1565 factor would save memory overhead. For example: generating more classes in the
 1566 lower range could allow items to fit more snugly into their slab classes, if
 1567 most of your items are less than 200 bytes in size.
 1568 
 1569 In 1.4.27 and after, this feature must be manually enabled.
 1570 
 1571 A "stats" command with the argument of "sizes_enable" will enable the
 1572 histogram at runtime. This has a small overhead to every store or delete
 1573 operation. If you don't want to incur this, leave it off.
 1574 
 1575 A "stats" command with the argument of "sizes_disable" will disable the
 1576 histogram.
 1577 
 1578 It can also be enabled at starttime with "-o track_sizes"
 1579 
 1580 If disabled, "stats sizes" will return:
 1581 
 1582 STAT sizes_status disabled\r\n
 1583 
 1584 "stats sizes_enable" will return:
 1585 
 1586 STAT sizes_status enabled\r\n
 1587 
 1588 "stats sizes_disable" will return:
 1589 
 1590 STAT sizes_status disabled\r\n
 1591 
 1592 If an error happens, it will return:
 1593 
 1594 STAT sizes_status error\r\n
 1595 STAT sizes_error [error_message]\r\n
 1596 
 1597 CAVEAT: If CAS support is disabled, you cannot enable/disable this feature at
 1598 runtime.
 1599 
 1600 Slab statistics
 1601 ---------------
 1602 CAVEAT: This section describes statistics which are subject to change in the
 1603 future.
 1604 
 1605 The "stats" command with the argument of "slabs" returns information about
 1606 each of the slabs created by memcached during runtime. This includes per-slab
 1607 information along with some totals. The data is returned in the format:
 1608 
 1609 STAT <slabclass>:<stat> <value>\r\n
 1610 STAT <stat> <value>\r\n
 1611 
 1612 The server terminates this list with the line
 1613 
 1614 END\r\n
 1615 
 1616 |-----------------+----------------------------------------------------------|
 1617 | Name            | Meaning                                                  |
 1618 |-----------------+----------------------------------------------------------|
 1619 | chunk_size      | The amount of space each chunk uses. One item will use   |
 1620 |                 | one chunk of the appropriate size.                       |
 1621 | chunks_per_page | How many chunks exist within one page. A page by         |
 1622 |                 | default is less than or equal to one megabyte in size.   |
 1623 |                 | Slabs are allocated by page, then broken into chunks.    |
 1624 | total_pages     | Total number of pages allocated to the slab class.       |
 1625 | total_chunks    | Total number of chunks allocated to the slab class.      |
 1626 | get_hits        | Total number of get requests serviced by this class.     |
 1627 | cmd_set         | Total number of set requests storing data in this class. |
 1628 | delete_hits     | Total number of successful deletes from this class.      |
 1629 | incr_hits       | Total number of incrs modifying this class.              |
 1630 | decr_hits       | Total number of decrs modifying this class.              |
 1631 | cas_hits        | Total number of CAS commands modifying this class.       |
 1632 | cas_badval      | Total number of CAS commands that failed to modify a     |
 1633 |                 | value due to a bad CAS id.                               |
 1634 | touch_hits      | Total number of touches serviced by this class.          |
 1635 | used_chunks     | How many chunks have been allocated to items.            |
 1636 | free_chunks     | Chunks not yet allocated to items, or freed via delete.  |
 1637 | free_chunks_end | Number of free chunks at the end of the last allocated   |
 1638 |                 | page.                                                    |
 1639 | active_slabs    | Total number of slab classes allocated.                  |
 1640 | total_malloced  | Total amount of memory allocated to slab pages.          |
 1641 |-----------------+----------------------------------------------------------|
 1642 
 1643 
 1644 Connection statistics
 1645 ---------------------
 1646 The "stats" command with the argument of "conns" returns information
 1647 about currently active connections and about sockets that are listening
 1648 for new connections. The data is returned in the format:
 1649 
 1650 STAT <file descriptor>:<stat> <value>\r\n
 1651 
 1652 The server terminates this list with the line
 1653 
 1654 END\r\n
 1655 
 1656 The following "stat" keywords may be present:
 1657 
 1658 |---------------------+------------------------------------------------------|
 1659 | Name                | Meaning                                              |
 1660 |---------------------+------------------------------------------------------|
 1661 | addr                | The address of the remote side. For listening        |
 1662 |                     | sockets this is the listen address. Note that some   |
 1663 |                     | socket types (such as UNIX-domain) don't have        |
 1664 |                     | meaningful remote addresses.                         |
 1665 | listen_addr         | The address of the server. This field is absent      |
 1666 |                     | for listening sockets.                               |
 1667 | state               | The current state of the connection. See below.      |
 1668 | secs_since_last_cmd | The number of seconds since the most recently        |
 1669 |                     | issued command on the connection. This measures      |
 1670 |                     | the time since the start of the command, so if       |
 1671 |                     | "state" indicates a command is currently executing,  |
 1672 |                     | this will be the number of seconds the current       |
 1673 |                     | command has been running.                            |
 1674 |---------------------+------------------------------------------------------|
 1675 
 1676 The value of the "state" stat may be one of the following:
 1677 
 1678 |----------------+-----------------------------------------------------------|
 1679 | Name           | Meaning                                                   |
 1680 |----------------+-----------------------------------------------------------|
 1681 | conn_closing   | Shutting down the connection.                             |
 1682 | conn_listening | Listening for new connections or a new UDP request.       |
 1683 | conn_mwrite    | Writing a complex response, e.g., to a "get" command.     |
 1684 | conn_new_cmd   | Connection is being prepared to accept a new command.     |
 1685 | conn_nread     | Reading extended data, typically for a command such as    |
 1686 |                | "set" or "put".                                           |
 1687 | conn_parse_cmd | The server has received a command and is in the middle    |
 1688 |                | of parsing it or executing it.                            |
 1689 | conn_read      | Reading newly-arrived command data.                       |
 1690 | conn_swallow   | Discarding excess input, e.g., after an error has         |
 1691 |                | occurred.                                                 |
 1692 | conn_waiting   | A partial command has been received and the server is     |
 1693 |                | waiting for the rest of it to arrive (note the difference |
 1694 |                | between this and conn_nread).                             |
 1695 | conn_write     | Writing a simple response (anything that doesn't involve  |
 1696 |                | sending back multiple lines of response data).            |
 1697 |----------------+-----------------------------------------------------------|
 1698 
 1699 TLS statistics
 1700 --------------
 1701 
 1702 TLS is a compile-time opt-in feature available in versions 1.5.13 and later.
 1703 When compiled with TLS support and TLS termination is enabled at runtime, the
 1704 following additional statistics are available via the "stats" command.
 1705 
 1706 |--------------------------------+----------+--------------------------------|
 1707 | Name                           | Type     | Meaning                        |
 1708 |--------------------------------+----------+--------------------------------|
 1709 | ssl_handshake_errors           | 64u      | Number of times the server has |
 1710 |                                |          | encountered an OpenSSL error   |
 1711 |                                |          | during handshake (SSL_accept). |
 1712 | ssl_min_version                | char     | Minimum supported TLS version  |
 1713 |                                |          | for client handshakes.         |
 1714 | ssl_new_sessions               | 64u      | When SSL session caching is    |
 1715 |                                |          | enabled, the number of newly   |
 1716 |                                |          | created server-side sessions.  |
 1717 |                                |          | Available only when compiled   |
 1718 |                                |          | with OpenSSL 1.1.1 or newer.   |
 1719 | time_since_server_cert_refresh | 32u      | Number of seconds that have    |
 1720 |                                |          | elapsed since the last time    |
 1721 |                                |          | certs were reloaded from disk. |
 1722 |--------------------------------+----------+--------------------------------|
 1723 
 1724 
 1725 Other commands
 1726 --------------
 1727 
 1728 "flush_all" is a command with an optional numeric argument. It always
 1729 succeeds, and the server sends "OK\r\n" in response (unless "noreply"
 1730 is given as the last parameter). Its effect is to invalidate all
 1731 existing items immediately (by default) or after the expiration
 1732 specified.  After invalidation none of the items will be returned in
 1733 response to a retrieval command (unless it's stored again under the
 1734 same key *after* flush_all has invalidated the items). flush_all
 1735 doesn't actually free all the memory taken up by existing items; that
 1736 will happen gradually as new items are stored. The most precise
 1737 definition of what flush_all does is the following: it causes all
 1738 items whose update time is earlier than the time at which flush_all
 1739 was set to be executed to be ignored for retrieval purposes.
 1740 
 1741 The intent of flush_all with a delay, was that in a setting where you
 1742 have a pool of memcached servers, and you need to flush all content,
 1743 you have the option of not resetting all memcached servers at the
 1744 same time (which could e.g. cause a spike in database load with all
 1745 clients suddenly needing to recreate content that would otherwise
 1746 have been found in the memcached daemon).
 1747 
 1748 The delay option allows you to have them reset in e.g. 10 second
 1749 intervals (by passing 0 to the first, 10 to the second, 20 to the
 1750 third, etc. etc.).
 1751 
 1752 "cache_memlimit" is a command with a numeric argument. This allows runtime
 1753 adjustments of the cache memory limit. It returns "OK\r\n" or an error (unless
 1754 "noreply" is given as the last parameter). If the new memory limit is higher
 1755 than the old one, the server may start requesting more memory from the OS. If
 1756 the limit is lower, and slabs_reassign+automove are enabled, free memory may
 1757 be released back to the OS asynchronously.
 1758 
 1759 The argument is in megabytes, not bytes. Input gets multiplied out into
 1760 megabytes internally.
 1761 
 1762 "shutdown" is a command with an optional argument used to stop memcached with
 1763 a kill signal. By default, "shutdown" alone raises SIGINT, though "graceful"
 1764 may be specified as the single argument to instead trigger a graceful shutdown
 1765 with SIGUSR1. The shutdown command is disabled by default, and can be enabled
 1766 with the -A/--enable-shutdown flag.
 1767 
 1768 "version" is a command with no arguments:
 1769 
 1770 version\r\n
 1771 
 1772 In response, the server sends
 1773 
 1774 "VERSION <version>\r\n", where <version> is the version string for the
 1775 server.
 1776 
 1777 "verbosity" is a command with a numeric argument. It always succeeds,
 1778 and the server sends "OK\r\n" in response (unless "noreply" is given
 1779 as the last parameter). Its effect is to set the verbosity level of
 1780 the logging output.
 1781 
 1782 "quit" is a command with no arguments:
 1783 
 1784 quit\r\n
 1785 
 1786 Upon receiving this command, the server closes the
 1787 connection. However, the client may also simply close the connection
 1788 when it no longer needs it, without issuing this command.
 1789 
 1790 Security restrictions
 1791 ---------------------
 1792 
 1793 In the debug build the following commands are available for testing the
 1794 security restrictions:
 1795 
 1796 "misbehave" is a command with no arguments:
 1797 
 1798 misbehave\r\n
 1799 
 1800 This command causes the worker thread to attempt a) opening a new socket, and
 1801 b) executing a shell command. If either one is successful, an error is
 1802 returned. Otherwise memcached returns OK.
 1803 The check is available only in Linux builds with seccomp enabled.
 1804 
 1805 
 1806 UDP protocol
 1807 ------------
 1808 
 1809 For very large installations where the number of clients is high enough
 1810 that the number of TCP connections causes scaling difficulties, there is
 1811 also a UDP-based interface. The UDP interface does not provide guaranteed
 1812 delivery, so should only be used for operations that aren't required to
 1813 succeed; typically it is used for "get" requests where a missing or
 1814 incomplete response can simply be treated as a cache miss.
 1815 
 1816 Each UDP datagram contains a simple frame header, followed by data in the
 1817 same format as the TCP protocol described above. In the current
 1818 implementation, requests must be contained in a single UDP datagram, but
 1819 responses may span several datagrams. (The only common requests that would
 1820 span multiple datagrams are huge multi-key "get" requests and "set"
 1821 requests, both of which are more suitable to TCP transport for reliability
 1822 reasons anyway.)
 1823 
 1824 The frame header is 8 bytes long, as follows (all values are 16-bit integers
 1825 in network byte order, high byte first):
 1826 
 1827 0-1 Request ID
 1828 2-3 Sequence number
 1829 4-5 Total number of datagrams in this message
 1830 6-7 Reserved for future use; must be 0
 1831 
 1832 The request ID is supplied by the client. Typically it will be a
 1833 monotonically increasing value starting from a random seed, but the client
 1834 is free to use whatever request IDs it likes. The server's response will
 1835 contain the same ID as the incoming request. The client uses the request ID
 1836 to differentiate between responses to outstanding requests if there are
 1837 several pending from the same server; any datagrams with an unknown request
 1838 ID are probably delayed responses to an earlier request and should be
 1839 discarded.
 1840 
 1841 The sequence number ranges from 0 to n-1, where n is the total number of
 1842 datagrams in the message. The client should concatenate the payloads of the
 1843 datagrams for a given response in sequence number order; the resulting byte
 1844 stream will contain a complete response in the same format as the TCP
 1845 protocol (including terminating \r\n sequences).