"Fossies" - the Fresh Open Source Software Archive

Member "memcached-1.6.9/doc/protocol.txt" (21 Nov 2020, 76293 Bytes) of package /linux/www/memcached-1.6.9.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. For more information about "protocol.txt" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 1.6.8_vs_1.6.9.

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