"Fossies" - the Fresh Open Source Software Archive

Member "memcached-1.6.15/doc/protocol-binary.xml" (16 Jul 2020, 62850 Bytes) of package /linux/www/memcached-1.6.15.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) XML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <?xml version="1.0" encoding="US-ASCII"?>
    2 <!DOCTYPE rfc SYSTEM "xml2rfc/rfc2629.dtd">
    3 <?xml-stylesheet type='text/xsl' href='xml2rfc/rfc2629.xslt'?>
    4 <?rfc toc="yes"?>
    5 <?rfc strict="yes"?>
    6 <?rfc symrefs="yes"?>
    7 <?rfc sortrefs="yes" ?>
    8 <?rfc compact="yes" ?>
    9 <?rfc subcompact="yes" ?>
   10 <rfc category="info" docName="draft-stone-memcache-binary-01" ipr="trust200902">
   11   <front>
   12     <title> Memcache Binary Protocol </title>
   13 
   14     <author fullname="Aaron Stone" surname="Stone" role="editor">
   15       <organization>Six Apart, Ltd.</organization>
   16       <address>
   17         <postal>
   18           <street>548 4th Street</street>
   19           <city>San Francisco</city>
   20           <region>CA</region>
   21           <code>94107</code>
   22           <country>USA</country>
   23         </postal>
   24         <email>aaron@serendipity.palo-alto.ca.us</email>
   25       </address>
   26     </author>
   27     <author fullname="Trond Norbye" surname="Norbye" role="editor">
   28       <organization>Sun Microsystems, INC</organization>
   29       <address>
   30         <postal>
   31           <street>Haakon VII g. 7B</street>
   32           <city>Trondheim</city>
   33           <code>NO-7485 Trondheim</code>
   34           <country>Norway</country>
   35         </postal>
   36         <email>trond.norbye@sun.com</email>
   37       </address>
   38     </author>
   39     <date day="28" month="August" year="2008" />
   40     <area>Applications</area>
   41     <keyword>memcache memcached cache</keyword>
   42     <abstract>
   43       <t>
   44         This memo explains the memcache binary protocol for informational
   45         purposes.
   46       </t>
   47       <t>
   48         Memcache is a high performance key-value cache. It is intentionally a
   49         dumb cache, optimized for speed only. Applications using memcache do
   50         not rely on it for data -- a persistent database with guaranteed
   51         reliability is strongly recommended -- but applications can run much
   52         faster when cached data is available in memcache.
   53       </t>
   54     </abstract>
   55   </front>
   56 
   57   <middle>
   58     <section anchor="introduction" title="Introduction">
   59       <t>
   60         Memcache is a high performance key-value cache. It is intentionally a
   61         dumb cache, optimized for speed only. Applications using memcache should
   62         not rely on it for data -- a persistent database with guaranteed
   63         reliability is strongly recommended -- but applications can run much
   64         faster when cached data is available in memcache.
   65       </t>
   66       <t>
   67         Memcache was originally written to make
   68         <xref target="LJ">LiveJournal</xref> faster. It now powers all of
   69         the fastest web sites that you love.
   70       </t>
   71       <section anchor="conventions" title="Conventions Used In This Document">
   72         <t>
   73           The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   74           "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   75           document are to be interpreted as described in
   76           <xref target="KEYWORDS"/>.
   77         </t>
   78       </section>
   79     </section>
   80 
   81     <section anchor="packet" title="Packet Structure">
   82       <figure>
   83         <preamble>General format of a packet:</preamble>
   84         <artwork>
   85   Byte/     0       |       1       |       2       |       3       |
   86      /              |               |               |               |
   87     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
   88     +---------------+---------------+---------------+---------------+
   89    0/ HEADER                                                        /
   90     /                                                               /
   91     /                                                               /
   92     /                                                               /
   93     +---------------+---------------+---------------+---------------+
   94   24/ COMMAND-SPECIFIC EXTRAS (as needed)                           /
   95    +/  (note length in the extras length header field)              /
   96     +---------------+---------------+---------------+---------------+
   97    m/ Key (as needed)                                               /
   98    +/  (note length in key length header field)                     /
   99     +---------------+---------------+---------------+---------------+
  100    n/ Value (as needed)                                             /
  101    +/  (note length is total body length header field, minus        /
  102    +/   sum of the extras and key length body fields)               /
  103     +---------------+---------------+---------------+---------------+
  104     Total 24 bytes
  105         </artwork>
  106       </figure>
  107 
  108       <figure>
  109         <preamble>Request header:</preamble>
  110         <artwork>
  111   Byte/     0       |       1       |       2       |       3       |
  112      /              |               |               |               |
  113     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
  114     +---------------+---------------+---------------+---------------+
  115    0| Magic         | Opcode        | Key length                    |
  116     +---------------+---------------+---------------+---------------+
  117    4| Extras length | Data type     | Reserved                      |
  118     +---------------+---------------+---------------+---------------+
  119    8| Total body length                                             |
  120     +---------------+---------------+---------------+---------------+
  121   12| Opaque                                                        |
  122     +---------------+---------------+---------------+---------------+
  123   16| CAS                                                           |
  124     |                                                               |
  125     +---------------+---------------+---------------+---------------+
  126     Total 24 bytes
  127         </artwork>
  128       </figure>
  129 
  130       <figure>
  131         <preamble>Response header:</preamble>
  132         <artwork>
  133   Byte/     0       |       1       |       2       |       3       |
  134      /              |               |               |               |
  135     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
  136     +---------------+---------------+---------------+---------------+
  137    0| Magic         | Opcode        | Key Length                    |
  138     +---------------+---------------+---------------+---------------+
  139    4| Extras length | Data type     | Status                        |
  140     +---------------+---------------+---------------+---------------+
  141    8| Total body length                                             |
  142     +---------------+---------------+---------------+---------------+
  143   12| Opaque                                                        |
  144     +---------------+---------------+---------------+---------------+
  145   16| CAS                                                           |
  146     |                                                               |
  147     +---------------+---------------+---------------+---------------+
  148     Total 24 bytes
  149         </artwork>
  150       </figure>
  151 
  152       <t>
  153         Header fields:
  154         <list hangIndent="20" style="hanging">
  155           <t hangText="Magic">Magic number.</t>
  156           <t hangText="Opcode">Command code.</t>
  157           <t hangText="Key length">Length in bytes of the text key that follows the command extras.</t>
  158           <t hangText="Status">Status of the response (non-zero on error).</t>
  159           <t hangText="Extras length">Length in bytes of the command extras.</t>
  160           <t hangText="Data type">Reserved for future use (Sean is using this soon).</t>
  161           <t hangText="Reserved">Really reserved for future use (up for grabs).</t>
  162           <t hangText="Total body length">Length in bytes of extra + key + value.</t>
  163           <t hangText="Opaque">Will be copied back to you in the response.</t>
  164           <t hangText="CAS">Data version check.</t>
  165         </list>
  166       </t>
  167     </section>
  168 
  169     <section anchor="values" title="Defined Values">
  170       <section anchor="value-magic" title="Magic Byte">
  171         <t>
  172         <list hangIndent="8" style="hanging">
  173           <t hangText="0x80">Request packet for this protocol version</t>
  174           <t hangText="0x81">Response packet for this protocol version</t>
  175         </list>
  176         </t>
  177 
  178         <t>
  179           Magic byte / version. For each version of the protocol, we'll use a
  180           different request/response value pair. This is useful for protocol
  181           analyzers to distinguish the nature of the packet from the direction
  182           which it is moving. Note, it is common to run a memcached instance on
  183       a host that also runs an application server. Such a host will both
  184       send and receive memcache packets.
  185         </t>
  186 
  187         <t>
  188           The version should hopefully correspond only to different meanings of
  189           the command byte. In an ideal world, we will not change the header
  190           format. As reserved bytes are given defined meaning, the protocol
  191           version / magic byte values should be incremented.
  192         </t>
  193 
  194         <t>
  195           Traffic analysis tools are encouraged to identify memcache packets
  196           and provide detailed interpretation if the magic bytes are recognized
  197           and otherwise to provide a generic breakdown of the packet. Note, that
  198           the key and value positions can always be identified even if the magic
  199           byte or command opcode are not recognized.
  200         </t>
  201       </section>
  202 
  203       <section anchor="value-status" title="Response Status">
  204         <t>
  205         Possible values of this two-byte field:
  206         <list hangIndent="8" style="hanging">
  207           <t hangText="0x0000">No error</t>
  208           <t hangText="0x0001">Key not found</t>
  209           <t hangText="0x0002">Key exists</t>
  210           <t hangText="0x0003">Value too large</t>
  211           <t hangText="0x0004">Invalid arguments</t>
  212           <t hangText="0x0005">Item not stored</t>
  213           <t hangText="0x0006">Incr/Decr on non-numeric value.</t>
  214           <t hangText="0x0081">Unknown command</t>
  215           <t hangText="0x0082">Out of memory</t>
  216         </list>
  217         </t>
  218       </section>
  219 
  220       <section anchor="value-opcodes" title="Command Opcodes">
  221         <t>
  222         Possible values of the one-byte field:
  223         <list hangIndent="8" style="hanging">
  224           <t hangText="0x00">Get</t>
  225           <t hangText="0x01">Set</t>
  226           <t hangText="0x02">Add</t>
  227           <t hangText="0x03">Replace</t>
  228           <t hangText="0x04">Delete</t>
  229           <t hangText="0x05">Increment</t>
  230           <t hangText="0x06">Decrement</t>
  231           <t hangText="0x07">Quit</t>
  232           <t hangText="0x08">Flush</t>
  233           <t hangText="0x09">GetQ</t>
  234           <t hangText="0x0A">No-op</t>
  235           <t hangText="0x0B">Version</t>
  236           <t hangText="0x0C">GetK</t>
  237           <t hangText="0x0D">GetKQ</t>
  238           <t hangText="0x0E">Append</t>
  239           <t hangText="0x0F">Prepend</t>
  240       <t hangText="0x10">Stat</t>
  241           <t hangText="0x11">SetQ</t>
  242           <t hangText="0x12">AddQ</t>
  243           <t hangText="0x13">ReplaceQ</t>
  244           <t hangText="0x14">DeleteQ</t>
  245           <t hangText="0x15">IncrementQ</t>
  246           <t hangText="0x16">DecrementQ</t>
  247           <t hangText="0x17">QuitQ</t>
  248           <t hangText="0x18">FlushQ</t>
  249           <t hangText="0x19">AppendQ</t>
  250           <t hangText="0x1A">PrependQ</t>
  251         </list>
  252         </t>
  253           <t>
  254             As a convention all of the commands ending with "Q" for
  255             Quiet.  A quiet version of a command will omit responses
  256             that are considered uninteresting.  Whether a given response
  257             is interesting is dependent upon the command.  See the
  258             descriptions of the
  259             <xref target="command-get">set commands</xref>
  260             and <xref target="command-set">set commands</xref> for
  261             examples of commands that include quiet variants.
  262           </t>
  263       </section>
  264 
  265       <section anchor="value-types" title="Data Types">
  266         <t>
  267         Possible values of the one-byte field:
  268         <list hangIndent="8" style="hanging">
  269           <t hangText="0x00">Raw bytes</t>
  270         </list>
  271         </t>
  272       </section>
  273     </section>
  274 
  275     <section title="Commands">
  276       <section anchor="command-introduction" title="Introduction">
  277         <t>
  278         All communication is initiated by a request from the client,
  279         and the server will respond to each request with zero or
  280     multiple packets for each request. If the status code of a response
  281     packet is non-nil, the body of the packet will contain a textual error
  282     message. If the status code is nil, the command opcode will define the
  283     layout of the body of the message.
  284         </t>
  285         <section anchor="command-introduction-example" title="Example">
  286             <t>
  287                 The following figure illustrates the packet layout for
  288                 a packet with an error message.
  289             </t>
  290           <figure>
  291             <preamble>Packet layout:</preamble>
  292             <artwork>
  293 
  294   Byte/     0       |       1       |       2       |       3       |
  295      /              |               |               |               |
  296     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
  297     +---------------+---------------+---------------+---------------+
  298    0| 0x81          | 0x00          | 0x00          | 0x00          |
  299     +---------------+---------------+---------------+---------------+
  300    4| 0x00          | 0x00          | 0x00          | 0x01          |
  301     +---------------+---------------+---------------+---------------+
  302    8| 0x00          | 0x00          | 0x00          | 0x09          |
  303     +---------------+---------------+---------------+---------------+
  304   12| 0x00          | 0x00          | 0x00          | 0x00          |
  305     +---------------+---------------+---------------+---------------+
  306   16| 0x00          | 0x00          | 0x00          | 0x00          |
  307     +---------------+---------------+---------------+---------------+
  308   20| 0x00          | 0x00          | 0x00          | 0x00          |
  309     +---------------+---------------+---------------+---------------+
  310   24| 0x4e ('N')    | 0x6f ('o')    | 0x74 ('t')    | 0x20 (' ')    |
  311     +---------------+---------------+---------------+---------------+
  312   28| 0x66 ('f')    | 0x6f ('o')    | 0x75 ('u')    | 0x6e ('n')    |
  313     +---------------+---------------+---------------+---------------+
  314   32| 0x64 ('d')    |
  315     +---------------+
  316     Total 33 bytes (24 byte header, and 9 bytes value)
  317 
  318 Field        (offset) (value)
  319 Magic        (0)    : 0x81
  320 Opcode       (1)    : 0x00
  321 Key length   (2,3)  : 0x0000
  322 Extra length (4)    : 0x00
  323 Data type    (5)    : 0x00
  324 Status       (6,7)  : 0x0001
  325 Total body   (8-11) : 0x00000009
  326 Opaque       (12-15): 0x00000000
  327 CAS          (16-23): 0x0000000000000000
  328 Extras              : None
  329 Key                 : None
  330 Value        (24-32): The textual string "Not found"
  331             </artwork>
  332           </figure>
  333         </section>
  334       </section>
  335 
  336       <section anchor="command-get" title="Get, Get Quietly, Get Key, Get Key Quietly">
  337         <t>
  338             Request:
  339         </t>
  340         <t>
  341         <list style="empty">
  342           <t>MUST NOT have extras.</t>
  343           <t>MUST have key.</t>
  344           <t>MUST NOT have value.</t>
  345         </list>
  346         </t>
  347 
  348         <t>
  349             Response (if found):
  350         </t>
  351         <t>
  352         <list style="empty">
  353           <t>MUST have extras.</t>
  354           <t>MAY have key.</t>
  355           <t>MAY have value.</t>
  356         </list>
  357         </t>
  358 
  359         <t>
  360         <list style="symbols">
  361           <t>4 byte flags</t>
  362         </list>
  363         </t>
  364 
  365         <t>
  366         <figure>
  367           <preamble>Extra data for the get commands:</preamble>
  368           <artwork>
  369   Byte/     0       |       1       |       2       |       3       |
  370      /              |               |               |               |
  371     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
  372     +---------------+---------------+---------------+---------------+
  373    0| Flags                                                         |
  374     +---------------+---------------+---------------+---------------+
  375 
  376     Total 4 bytes
  377           </artwork>
  378         </figure>
  379         </t>
  380 
  381         <t>
  382           The get command gets a single key. The getq command is both mum
  383           on cache miss and quiet, holding its response until a non-quiet
  384           command is issued. Getk and getkq differs from get and getq by
  385           adding the key into the response packet.
  386         </t>
  387 
  388         <t>
  389           You're not guaranteed a response to a getq/getkq cache hit until
  390           you send a non-getq/getkq command later, which uncorks the
  391           server and bundles up IOs to send to the client in one go.
  392         </t>
  393 
  394         <t>
  395           Clients should implement multi-get (still important for
  396           reducing network roundtrips!) as n pipelined requests, the
  397           first n-1 being getq/getkq, the last being a regular
  398           get/getk.  That way you're guaranteed to get a response, and
  399           you know when the server's done.  You can also do the naive
  400           thing and send n pipelined get/getks, but then you could potentially
  401           get back a lot of "NOT_FOUND" error code packets.
  402           Alternatively, you can send 'n' getq/getkqs, followed by a
  403           'noop' command.
  404         </t>
  405 
  406         <section anchor="command-get-example" title="Example">
  407           <t>
  408            To request the data associated with the key "Hello" the
  409            following fields must be specified in the packet.
  410           </t>
  411           <figure>
  412             <preamble>get request:</preamble>
  413             <artwork>
  414   Byte/     0       |       1       |       2       |       3       |
  415      /              |               |               |               |
  416     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
  417     +---------------+---------------+---------------+---------------+
  418    0| 0x80          | 0x00          | 0x00          | 0x05          |
  419     +---------------+---------------+---------------+---------------+
  420    4| 0x00          | 0x00          | 0x00          | 0x00          |
  421     +---------------+---------------+---------------+---------------+
  422    8| 0x00          | 0x00          | 0x00          | 0x05          |
  423     +---------------+---------------+---------------+---------------+
  424   12| 0x00          | 0x00          | 0x00          | 0x00          |
  425     +---------------+---------------+---------------+---------------+
  426   16| 0x00          | 0x00          | 0x00          | 0x00          |
  427     +---------------+---------------+---------------+---------------+
  428   20| 0x00          | 0x00          | 0x00          | 0x00          |
  429     +---------------+---------------+---------------+---------------+
  430   24| 0x48 ('H')    | 0x65 ('e')    | 0x6c ('l')    | 0x6c ('l')    |
  431     +---------------+---------------+---------------+---------------+
  432   28| 0x6f ('o')    |
  433     +---------------+
  434 
  435     Total 29 bytes (24 byte header, and 5 bytes key)
  436 
  437 Field        (offset) (value)
  438 Magic        (0)    : 0x80
  439 Opcode       (1)    : 0x00
  440 Key length   (2,3)  : 0x0005
  441 Extra length (4)    : 0x00
  442 Data type    (5)    : 0x00
  443 Reserved     (6,7)  : 0x0000
  444 Total body   (8-11) : 0x00000005
  445 Opaque       (12-15): 0x00000000
  446 CAS          (16-23): 0x0000000000000000
  447 Extras              : None
  448 Key          (24-29): The textual string: "Hello"
  449 Value               : None
  450             </artwork>
  451           </figure>
  452           <t>If the item exist on the server the following packet is returned,
  453           otherwise a packet with status code != 0 will be returned (see
  454            <xref target="command-introduction">Introduction</xref>)
  455           </t>
  456           <figure>
  457             <preamble>get/getq response:</preamble>
  458             <artwork>
  459 
  460   Byte/     0       |       1       |       2       |       3       |
  461      /              |               |               |               |
  462     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
  463     +---------------+---------------+---------------+---------------+
  464    0| 0x81          | 0x00          | 0x00          | 0x00          |
  465     +---------------+---------------+---------------+---------------+
  466    4| 0x04          | 0x00          | 0x00          | 0x00          |
  467     +---------------+---------------+---------------+---------------+
  468    8| 0x00          | 0x00          | 0x00          | 0x09          |
  469     +---------------+---------------+---------------+---------------+
  470   12| 0x00          | 0x00          | 0x00          | 0x00          |
  471     +---------------+---------------+---------------+---------------+
  472   16| 0x00          | 0x00          | 0x00          | 0x00          |
  473     +---------------+---------------+---------------+---------------+
  474   20| 0x00          | 0x00          | 0x00          | 0x01          |
  475     +---------------+---------------+---------------+---------------+
  476   24| 0xde          | 0xad          | 0xbe          | 0xef          |
  477     +---------------+---------------+---------------+---------------+
  478   28| 0x57 ('W')    | 0x6f ('o')    | 0x72 ('r')    | 0x6c ('l')    |
  479     +---------------+---------------+---------------+---------------+
  480   32| 0x64 ('d')    |
  481     +---------------+
  482 
  483     Total 33 bytes (24 byte header, 4 byte extras and 5 byte value)
  484 
  485 Field        (offset) (value)
  486 Magic        (0)    : 0x81
  487 Opcode       (1)    : 0x00
  488 Key length   (2,3)  : 0x0000
  489 Extra length (4)    : 0x04
  490 Data type    (5)    : 0x00
  491 Status       (6,7)  : 0x0000
  492 Total body   (8-11) : 0x00000009
  493 Opaque       (12-15): 0x00000000
  494 CAS          (16-23): 0x0000000000000001
  495 Extras              :
  496   Flags      (24-27): 0xdeadbeef
  497 Key                 : None
  498 Value        (28-32): The textual string "World"
  499             </artwork>
  500           </figure>
  501           <figure>
  502             <preamble>getk/getkq response:</preamble>
  503             <artwork>
  504 
  505   Byte/     0       |       1       |       2       |       3       |
  506      /              |               |               |               |
  507     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
  508     +---------------+---------------+---------------+---------------+
  509    0| 0x81          | 0x00          | 0x00          | 0x05          |
  510     +---------------+---------------+---------------+---------------+
  511    4| 0x04          | 0x00          | 0x00          | 0x00          |
  512     +---------------+---------------+---------------+---------------+
  513    8| 0x00          | 0x00          | 0x00          | 0x09          |
  514     +---------------+---------------+---------------+---------------+
  515   12| 0x00          | 0x00          | 0x00          | 0x00          |
  516     +---------------+---------------+---------------+---------------+
  517   16| 0x00          | 0x00          | 0x00          | 0x00          |
  518     +---------------+---------------+---------------+---------------+
  519   20| 0x00          | 0x00          | 0x00          | 0x01          |
  520     +---------------+---------------+---------------+---------------+
  521   24| 0xde          | 0xad          | 0xbe          | 0xef          |
  522     +---------------+---------------+---------------+---------------+
  523   28| 0x48 ('H')    | 0x65 ('e')    | 0x6c ('l')    | 0x6c ('l')    |
  524     +---------------+---------------+---------------+---------------+
  525   32| 0x6f ('o')    | 0x57 ('W')    | 0x6f ('o')    | 0x72 ('r')    |
  526     +---------------+---------------+---------------+---------------+
  527   36| 0x6c ('l')    | 0x64 ('d')    |
  528     +---------------+---------------+
  529 
  530     Total 38 bytes (24 byte header, 4 byte extras, 5 byte key
  531                     and 5 byte value)
  532 
  533 Field        (offset) (value)
  534 Magic        (0)    : 0x81
  535 Opcode       (1)    : 0x00
  536 Key length   (2,3)  : 0x0005
  537 Extra length (4)    : 0x04
  538 Data type    (5)    : 0x00
  539 Status       (6,7)  : 0x0000
  540 Total body   (8-11) : 0x0000000E
  541 Opaque       (12-15): 0x00000000
  542 CAS          (16-23): 0x0000000000000001
  543 Extras              :
  544   Flags      (24-27): 0xdeadbeef
  545 Key          (28-32): The textual string: "Hello"
  546 Value        (33-37): The textual string: "World"
  547             </artwork>
  548           </figure>
  549         </section>
  550       </section>
  551 
  552       <section anchor="command-set" title="Set, Add, Replace">
  553         <t>
  554         <list style="empty">
  555           <t>MUST have extras.</t>
  556           <t>MUST have key.</t>
  557           <t>MUST have value.</t>
  558         </list>
  559         </t>
  560 
  561         <t>
  562           <list style="symbols">
  563             <t>4 byte flags</t>
  564             <t>4 byte expiration time</t>
  565           </list>
  566         </t>
  567 
  568         <figure>
  569           <preamble>Extra data for set/add/replace:</preamble>
  570           <artwork>
  571   Byte/     0       |       1       |       2       |       3       |
  572      /              |               |               |               |
  573     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
  574     +---------------+---------------+---------------+---------------+
  575    0| Flags                                                         |
  576     +---------------+---------------+---------------+---------------+
  577    4| Expiration                                                    |
  578     +---------------+---------------+---------------+---------------+
  579     Total 8 bytes
  580           </artwork>
  581         </figure>
  582 
  583         <t>
  584         If the Data Version Check (CAS) is nonzero, the requested
  585         operation MUST only succeed if the item exists and has a CAS value
  586         identical to the provided value.
  587         </t>
  588 
  589         <t>
  590         Add MUST fail if the item already exist.
  591         </t>
  592 
  593         <t>
  594         Replace MUST fail if the item doesn't exist.
  595         </t>
  596 
  597         <t>
  598         Set should store the data unconditionally if the item exists
  599         or not.
  600         </t>
  601 
  602         <t>
  603           Quiet mutations only return responses on failure.  Success
  604           is considered the general case and is suppressed when in
  605           quiet mode, but errors should not be allowed to go
  606           unnoticed.
  607         </t>
  608 
  609         <section anchor="command-set-example" title="Example">
  610             <t>The following figure shows an add-command for
  611                 <list style="empty">
  612                   <t>Key: "Hello"</t>
  613                   <t>Value: "World"</t>
  614                   <t>Flags: 0xdeadbeef</t>
  615                   <t>Expiry: in two hours</t>
  616                 </list>
  617             </t>
  618            <figure>
  619              <preamble>Add request:</preamble>
  620              <artwork>
  621 
  622   Byte/     0       |       1       |       2       |       3       |
  623      /              |               |               |               |
  624     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
  625     +---------------+---------------+---------------+---------------+
  626    0| 0x80          | 0x02          | 0x00          | 0x05          |
  627     +---------------+---------------+---------------+---------------+
  628    4| 0x08          | 0x00          | 0x00          | 0x00          |
  629     +---------------+---------------+---------------+---------------+
  630    8| 0x00          | 0x00          | 0x00          | 0x12          |
  631     +---------------+---------------+---------------+---------------+
  632   12| 0x00          | 0x00          | 0x00          | 0x00          |
  633     +---------------+---------------+---------------+---------------+
  634   16| 0x00          | 0x00          | 0x00          | 0x00          |
  635     +---------------+---------------+---------------+---------------+
  636   20| 0x00          | 0x00          | 0x00          | 0x00          |
  637     +---------------+---------------+---------------+---------------+
  638   24| 0xde          | 0xad          | 0xbe          | 0xef          |
  639     +---------------+---------------+---------------+---------------+
  640   28| 0x00          | 0x00          | 0x1c          | 0x20          |
  641     +---------------+---------------+---------------+---------------+
  642   32| 0x48 ('H')    | 0x65 ('e')    | 0x6c ('l')    | 0x6c ('l')    |
  643     +---------------+---------------+---------------+---------------+
  644   36| 0x6f ('o')    | 0x57 ('W')    | 0x6f ('o')    | 0x72 ('r')    |
  645     +---------------+---------------+---------------+---------------+
  646   40| 0x6c ('l')    | 0x64 ('d')    |
  647     +---------------+---------------+
  648 
  649     Total 42 bytes (24 byte header, 8 byte extras, 5 byte key and
  650                     5 byte value)
  651 
  652 Field        (offset) (value)
  653 Magic        (0)    : 0x80
  654 Opcode       (1)    : 0x02
  655 Key length   (2,3)  : 0x0005
  656 Extra length (4)    : 0x08
  657 Data type    (5)    : 0x00
  658 Reserved     (6,7)  : 0x0000
  659 Total body   (8-11) : 0x00000012
  660 Opaque       (12-15): 0x00000000
  661 CAS          (16-23): 0x0000000000000000
  662 Extras              :
  663   Flags      (24-27): 0xdeadbeef
  664   Expiry     (28-31): 0x00001c20
  665 Key          (32-36): The textual string "Hello"
  666 Value        (37-41): The textual string "World"
  667              </artwork>
  668            </figure>
  669            <t>
  670         The response-packet contains no extra data, and the result of the
  671         operation is signaled through the status code. If the command
  672         succeeds, the CAS value for the item is returned in the CAS-field
  673         of the packet.
  674            </t>
  675            <figure>
  676              <preamble>Successful add response:</preamble>
  677              <artwork>
  678 
  679   Byte/     0       |       1       |       2       |       3       |
  680      /              |               |               |               |
  681     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
  682     +---------------+---------------+---------------+---------------+
  683    0| 0x81          | 0x02          | 0x00          | 0x00          |
  684     +---------------+---------------+---------------+---------------+
  685    4| 0x00          | 0x00          | 0x00          | 0x00          |
  686     +---------------+---------------+---------------+---------------+
  687    8| 0x00          | 0x00          | 0x00          | 0x00          |
  688     +---------------+---------------+---------------+---------------+
  689   12| 0x00          | 0x00          | 0x00          | 0x00          |
  690     +---------------+---------------+---------------+---------------+
  691   16| 0x00          | 0x00          | 0x00          | 0x00          |
  692     +---------------+---------------+---------------+---------------+
  693   20| 0x00          | 0x00          | 0x00          | 0x01          |
  694     +---------------+---------------+---------------+---------------+
  695 
  696     Total 24 bytes
  697 
  698 Field        (offset) (value)
  699 Magic        (0)    : 0x81
  700 Opcode       (1)    : 0x02
  701 Key length   (2,3)  : 0x0000
  702 Extra length (4)    : 0x00
  703 Data type    (5)    : 0x00
  704 Status       (6,7)  : 0x0000
  705 Total body   (8-11) : 0x00000000
  706 Opaque       (12-15): 0x00000000
  707 CAS          (16-23): 0x0000000000000001
  708 Extras              : None
  709 Key                 : None
  710 Value               : None
  711              </artwork>
  712            </figure>
  713          </section>
  714       </section>
  715 
  716       <section anchor="command-delete" title="Delete">
  717         <t>
  718         <list style="empty">
  719           <t>MUST NOT have extras.</t>
  720           <t>MUST have key.</t>
  721           <t>MUST NOT have value.</t>
  722         </list>
  723         </t>
  724 
  725         <t>
  726       Delete the item with the specific key.
  727         </t>
  728 
  729         <section anchor="command-delete-example" title="Example">
  730           <t>The following figure shows a delete message for the
  731             item "Hello".</t>
  732           <figure>
  733             <preamble>Delete request:</preamble>
  734             <artwork>
  735   Byte/     0       |       1       |       2       |       3       |
  736      /              |               |               |               |
  737     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
  738     +---------------+---------------+---------------+---------------+
  739    0| 0x80          | 0x04          | 0x00          | 0x05          |
  740     +---------------+---------------+---------------+---------------+
  741    4| 0x00          | 0x00          | 0x00          | 0x00          |
  742     +---------------+---------------+---------------+---------------+
  743    8| 0x00          | 0x00          | 0x00          | 0x05          |
  744     +---------------+---------------+---------------+---------------+
  745   12| 0x00          | 0x00          | 0x00          | 0x00          |
  746     +---------------+---------------+---------------+---------------+
  747   16| 0x00          | 0x00          | 0x00          | 0x00          |
  748     +---------------+---------------+---------------+---------------+
  749   20| 0x00          | 0x00          | 0x00          | 0x00          |
  750     +---------------+---------------+---------------+---------------+
  751   24| 0x48 ('H')    | 0x65 ('e')    | 0x6c ('l')    | 0x6c ('l')    |
  752     +---------------+---------------+---------------+---------------+
  753   28| 0x6f ('o')    |
  754     +---------------+
  755 
  756     Total 29 bytes (24 byte header, 5 byte value)
  757 
  758 Field        (offset) (value)
  759 Magic        (0)    : 0x80
  760 Opcode       (1)    : 0x04
  761 Key length   (2,3)  : 0x0005
  762 Extra length (4)    : 0x00
  763 Data type    (5)    : 0x00
  764 Reserved     (6,7)  : 0x0000
  765 Total body   (8-11) : 0x00000005
  766 Opaque       (12-15): 0x00000000
  767 CAS          (16-23): 0x0000000000000000
  768 Extras              : None
  769 Key                 : The textual string "Hello"
  770 Value               : None
  771             </artwork>
  772           </figure>
  773           <t>
  774             The response-packet contains no extra data, and the result of the
  775             operation is signaled through the status code.
  776           </t>
  777         </section>
  778       </section>
  779 
  780       <section anchor="command-incr" title="Increment, Decrement">
  781         <t>
  782           <list style="empty">
  783             <t>MUST have extras.</t>
  784             <t>MUST have key.</t>
  785             <t>MUST NOT have value.</t>
  786           </list>
  787         </t>
  788 
  789         <t>
  790           <list style="symbols">
  791             <t>8 byte value to add / subtract</t>
  792             <t>8 byte initial value (unsigned)</t>
  793             <t>4 byte expiration time</t>
  794           </list>
  795         </t>
  796         <figure>
  797           <preamble>Extra data for incr/decr:</preamble>
  798           <artwork>
  799   Byte/     0       |       1       |       2       |       3       |
  800      /              |               |               |               |
  801     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
  802     +---------------+---------------+---------------+---------------+
  803    0| Amount to add                                                 |
  804     |                                                               |
  805     +---------------+---------------+---------------+---------------+
  806    8| Initial value                                                 |
  807     |                                                               |
  808     +---------------+---------------+---------------+---------------+
  809   16| Expiration                                                    |
  810     +---------------+---------------+---------------+---------------+
  811     Total 20 bytes
  812           </artwork>
  813         </figure>
  814 
  815         <t>
  816           These commands will either add or remove the specified
  817           amount to the requested counter.
  818         </t>
  819         <t>
  820           If the counter does not exist, one of two things may happen:
  821         </t>
  822         <t>
  823           <list style="numbers">
  824           <t>If the expiration value is all one-bits (0xffffffff), the
  825              operation will fail with NOT_FOUND.</t>
  826           <t>For all other expiration values, the operation will succeed
  827              by seeding the value for this key with the provided initial
  828              value to expire with the provided expiration time. The flags
  829              will be set to zero.</t>
  830           </list>
  831         </t>
  832         <figure>
  833           <preamble>incr/decr response body:</preamble>
  834           <artwork>
  835   Byte/     0       |       1       |       2       |       3       |
  836      /              |               |               |               |
  837     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
  838     +---------------+---------------+---------------+---------------+
  839    0| 64-bit unsigned response.                                     |
  840     |                                                               |
  841     +---------------+---------------+---------------+---------------+
  842     Total 8 bytes
  843           </artwork>
  844         </figure>
  845         <section anchor="command-incr-example" title="Example">
  846             <t>The following figure shows an incr-command for
  847                 <list style="empty">
  848                   <t>Key: "counter"</t>
  849                   <t>Delta: 0x01</t>
  850                   <t>Initial: 0x00</t>
  851                   <t>Expiry: in two hours</t>
  852                 </list>
  853             </t>
  854             <figure>
  855               <preamble>Increment request:</preamble>
  856               <artwork>
  857 
  858   Byte/     0       |       1       |       2       |       3       |
  859      /              |               |               |               |
  860     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
  861     +---------------+---------------+---------------+---------------+
  862    0| 0x80          | 0x05          | 0x00          | 0x07          |
  863     +---------------+---------------+---------------+---------------+
  864    4| 0x14          | 0x00          | 0x00          | 0x00          |
  865     +---------------+---------------+---------------+---------------+
  866    8| 0x00          | 0x00          | 0x00          | 0x1b          |
  867     +---------------+---------------+---------------+---------------+
  868   12| 0x00          | 0x00          | 0x00          | 0x00          |
  869     +---------------+---------------+---------------+---------------+
  870   16| 0x00          | 0x00          | 0x00          | 0x00          |
  871     +---------------+---------------+---------------+---------------+
  872   20| 0x00          | 0x00          | 0x00          | 0x00          |
  873     +---------------+---------------+---------------+---------------+
  874   24| 0x00          | 0x00          | 0x00          | 0x00          |
  875     +---------------+---------------+---------------+---------------+
  876   28| 0x00          | 0x00          | 0x00          | 0x01          |
  877     +---------------+---------------+---------------+---------------+
  878   32| 0x00          | 0x00          | 0x00          | 0x00          |
  879     +---------------+---------------+---------------+---------------+
  880   36| 0x00          | 0x00          | 0x00          | 0x00          |
  881     +---------------+---------------+---------------+---------------+
  882   40| 0x00          | 0x00          | 0x1c          | 0x20          |
  883     +---------------+---------------+---------------+---------------+
  884   44| 0x63 ('c')    | 0x6f ('o')    | 0x75 ('u')    | 0x6e ('n')    |
  885     +---------------+---------------+---------------+---------------+
  886   48| 0x74 ('t')    | 0x65 ('e')    | 0x72 ('r')    |
  887     +---------------+---------------+---------------+
  888     Total 51 bytes (24 byte header, 20 byte extras, 7 byte key)
  889 
  890 Field        (offset) (value)
  891 Magic        (0)    : 0x80
  892 Opcode       (1)    : 0x05
  893 Key length   (2,3)  : 0x0007
  894 Extra length (4)    : 0x14
  895 Data type    (5)    : 0x00
  896 Reserved     (6,7)  : 0x0000
  897 Total body   (8-11) : 0x0000001b
  898 Opaque       (12-15): 0x00000000
  899 CAS          (16-23): 0x0000000000000000
  900 Extras              :
  901   delta      (24-31): 0x0000000000000001
  902   initial    (32-39): 0x0000000000000000
  903   expiration (40-43): 0x00001c20
  904 Key                 : Textual string "counter"
  905 Value               : None
  906               </artwork>
  907             </figure>
  908             <t>
  909              If the key doesn't exist, the server will respond with the
  910              initial value. If not the incremented value will be returned.
  911              Let's assume that the key didn't exist, so the initial value
  912              is returned.
  913             </t>
  914             <figure>
  915               <preamble>Increment response:</preamble>
  916               <artwork>
  917   Byte/     0       |       1       |       2       |       3       |
  918      /              |               |               |               |
  919     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
  920     +---------------+---------------+---------------+---------------+
  921    0| 0x81          | 0x05          | 0x00          | 0x00          |
  922     +---------------+---------------+---------------+---------------+
  923    4| 0x00          | 0x00          | 0x00          | 0x00          |
  924     +---------------+---------------+---------------+---------------+
  925    8| 0x00          | 0x00          | 0x00          | 0x08          |
  926     +---------------+---------------+---------------+---------------+
  927   12| 0x00          | 0x00          | 0x00          | 0x00          |
  928     +---------------+---------------+---------------+---------------+
  929   16| 0x00          | 0x00          | 0x00          | 0x00          |
  930     +---------------+---------------+---------------+---------------+
  931   20| 0x00          | 0x00          | 0x00          | 0x05          |
  932     +---------------+---------------+---------------+---------------+
  933   24| 0x00          | 0x00          | 0x00          | 0x00          |
  934     +---------------+---------------+---------------+---------------+
  935   28| 0x00          | 0x00          | 0x00          | 0x00          |
  936     +---------------+---------------+---------------+---------------+
  937     Total 32 bytes (24 byte header, 8 byte value)
  938 
  939 Field        (offset) (value)
  940 Magic        (0)    : 0x81
  941 Opcode       (1)    : 0x05
  942 Key length   (2,3)  : 0x0000
  943 Extra length (4)    : 0x00
  944 Data type    (5)    : 0x00
  945 Status       (6,7)  : 0x0000
  946 Total body   (8-11) : 0x00000008
  947 Opaque       (12-15): 0x00000000
  948 CAS          (16-23): 0x0000000000000005
  949 Extras              : None
  950 Key                 : None
  951 Value               : 0x0000000000000000
  952               </artwork>
  953             </figure>
  954           </section>
  955       </section>
  956 
  957       <section anchor="command-quit" title="quit">
  958         <t>
  959         <list style="empty">
  960           <t>MUST NOT have extras.</t>
  961           <t>MUST NOT have key.</t>
  962           <t>MUST NOT have value.</t>
  963         </list>
  964         </t>
  965 
  966         <t>
  967         Close the connection to the server.
  968         </t>
  969 
  970         <section anchor="command-quit-example" title="Example">
  971           <figure>
  972             <preamble>Quit request:</preamble>
  973             <artwork>
  974   Byte/     0       |       1       |       2       |       3       |
  975      /              |               |               |               |
  976     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
  977     +---------------+---------------+---------------+---------------+
  978    0| 0x80          | 0x07          | 0x00          | 0x00          |
  979     +---------------+---------------+---------------+---------------+
  980    4| 0x00          | 0x00          | 0x00          | 0x00          |
  981     +---------------+---------------+---------------+---------------+
  982    8| 0x00          | 0x00          | 0x00          | 0x00          |
  983     +---------------+---------------+---------------+---------------+
  984   12| 0x00          | 0x00          | 0x00          | 0x00          |
  985     +---------------+---------------+---------------+---------------+
  986   16| 0x00          | 0x00          | 0x00          | 0x00          |
  987     +---------------+---------------+---------------+---------------+
  988   20| 0x00          | 0x00          | 0x00          | 0x00          |
  989     +---------------+---------------+---------------+---------------+
  990     Total 24 bytes
  991 
  992 Field        (offset) (value)
  993 Magic        (0)    : 0x80
  994 Opcode       (1)    : 0x07
  995 Key length   (2,3)  : 0x0000
  996 Extra length (4)    : 0x00
  997 Data type    (5)    : 0x00
  998 Reserved     (6,7)  : 0x0000
  999 Total body   (8-11) : 0x00000000
 1000 Opaque       (12-15): 0x00000000
 1001 CAS          (16-23): 0x0000000000000000
 1002 Extras              : None
 1003 Key                 : None
 1004 Value               : None
 1005             </artwork>
 1006           </figure>
 1007           <t>
 1008             The response-packet contains no extra data, and the result of the
 1009             operation is signaled through the status code. The server will
 1010             then close the connection.
 1011           </t>
 1012         </section>
 1013       </section>
 1014 
 1015       <section anchor="command-flush" title="Flush">
 1016         <t>
 1017           <list style="empty">
 1018             <t>MAY have extras.</t>
 1019             <t>MUST NOT have key.</t>
 1020             <t>MUST NOT have value.</t>
 1021           </list>
 1022         </t>
 1023 
 1024         <t>
 1025           <list style="symbols">
 1026             <t>4 byte expiration time</t>
 1027           </list>
 1028         </t>
 1029         <figure>
 1030           <preamble>Extra data for flush:</preamble>
 1031           <artwork>
 1032   Byte/     0       |       1       |       2       |       3       |
 1033      /              |               |               |               |
 1034     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
 1035     +---------------+---------------+---------------+---------------+
 1036    0| Expiration                                                    |
 1037     +---------------+---------------+---------------+---------------+
 1038   Total 4 bytes
 1039           </artwork>
 1040         </figure>
 1041         <t>
 1042             Flush the items in the cache now or some time in the future as
 1043             specified by the expiration field. See the documentation of the
 1044             textual protocol for the full description on how to specify the
 1045             expiration time.
 1046         </t>
 1047         <section anchor="command-flush-example" title="Example">
 1048         <t>
 1049             To flush the cache (delete all items) in two hours, the set
 1050             the following values in the request
 1051         </t>
 1052         <figure>
 1053           <preamble>Flush request:</preamble>
 1054           <artwork>
 1055   Byte/     0       |       1       |       2       |       3       |
 1056      /              |               |               |               |
 1057     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
 1058     +---------------+---------------+---------------+---------------+
 1059    0| 0x80          | 0x08          | 0x00          | 0x00          |
 1060     +---------------+---------------+---------------+---------------+
 1061    4| 0x04          | 0x00          | 0x00          | 0x00          |
 1062     +---------------+---------------+---------------+---------------+
 1063    8| 0x00          | 0x00          | 0x00          | 0x04          |
 1064     +---------------+---------------+---------------+---------------+
 1065   12| 0x00          | 0x00          | 0x00          | 0x00          |
 1066     +---------------+---------------+---------------+---------------+
 1067   16| 0x00          | 0x00          | 0x00          | 0x00          |
 1068     +---------------+---------------+---------------+---------------+
 1069   20| 0x00          | 0x00          | 0x00          | 0x00          |
 1070     +---------------+---------------+---------------+---------------+
 1071   24| 0x00          | 0x00          | 0x1c          | 0x20          |
 1072     +---------------+---------------+---------------+---------------+
 1073     Total 28 bytes (24 byte header, 4 byte body)
 1074 
 1075 Field        (offset) (value)
 1076 Magic        (0)    : 0x80
 1077 Opcode       (1)    : 0x08
 1078 Key length   (2,3)  : 0x0000
 1079 Extra length (4)    : 0x04
 1080 Data type    (5)    : 0x00
 1081 Reserved     (6,7)  : 0x0000
 1082 Total body   (8-11) : 0x00000004
 1083 Opaque       (12-15): 0x00000000
 1084 CAS          (16-23): 0x0000000000000000
 1085 Extras              :
 1086    Expiry    (24-27): 0x00001c20
 1087 Key                 : None
 1088 Value               : None
 1089           </artwork>
 1090         </figure>
 1091           <t>
 1092             The response-packet contains no extra data, and the result of the
 1093             operation is signaled through the status code.
 1094           </t>
 1095         </section>
 1096       </section>
 1097       <section anchor="command-noop" title="noop">
 1098         <t>
 1099         <list style="empty">
 1100           <t>MUST NOT have extras.</t>
 1101           <t>MUST NOT have key.</t>
 1102           <t>MUST NOT have value.</t>
 1103         </list>
 1104         </t>
 1105 
 1106         <t>
 1107         Used as a keep alive. Flushes outstanding getq/getkq's.
 1108         </t>
 1109         <section anchor="command-noop-example" title="Example">
 1110           <figure>
 1111             <preamble>Noop request:</preamble>
 1112             <artwork>
 1113   Byte/     0       |       1       |       2       |       3       |
 1114      /              |               |               |               |
 1115     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
 1116     +---------------+---------------+---------------+---------------+
 1117    0| 0x80          | 0x0a          | 0x00          | 0x00          |
 1118     +---------------+---------------+---------------+---------------+
 1119    4| 0x00          | 0x00          | 0x00          | 0x00          |
 1120     +---------------+---------------+---------------+---------------+
 1121    8| 0x00          | 0x00          | 0x00          | 0x00          |
 1122     +---------------+---------------+---------------+---------------+
 1123   12| 0x00          | 0x00          | 0x00          | 0x00          |
 1124     +---------------+---------------+---------------+---------------+
 1125   16| 0x00          | 0x00          | 0x00          | 0x00          |
 1126     +---------------+---------------+---------------+---------------+
 1127   20| 0x00          | 0x00          | 0x00          | 0x00          |
 1128     +---------------+---------------+---------------+---------------+
 1129     Total 24 bytes
 1130 
 1131 Field        (offset) (value)
 1132 Magic        (0)    : 0x80
 1133 Opcode       (1)    : 0x0a
 1134 Key length   (2,3)  : 0x0000
 1135 Extra length (4)    : 0x00
 1136 Data type    (5)    : 0x00
 1137 Reserved     (6,7)  : 0x0000
 1138 Total body   (8-11) : 0x00000000
 1139 Opaque       (12-15): 0x00000000
 1140 CAS          (16-23): 0x0000000000000000
 1141 Extras              : None
 1142 Key                 : None
 1143 Value               : None
 1144             </artwork>
 1145           </figure>
 1146           <t>
 1147             The response-packet contains no extra data, and the result of the
 1148             operation is signaled through the status code.
 1149           </t>
 1150         </section>
 1151       </section>
 1152 
 1153       <section anchor="command-version" title="version">
 1154         <t>
 1155         <list style="empty">
 1156           <t>MUST NOT have extras.</t>
 1157           <t>MUST NOT have key.</t>
 1158           <t>MUST NOT have value.</t>
 1159         </list>
 1160         </t>
 1161 
 1162         <t>
 1163           Request the server version.
 1164         </t>
 1165         <t>
 1166       The server responds with a packet containing the version string
 1167       in the body with the following format: "x.y.z"
 1168         </t>
 1169         <section anchor="command-version-example" title="Example">
 1170           <figure>
 1171             <preamble>Version request:</preamble>
 1172             <artwork>
 1173   Byte/     0       |       1       |       2       |       3       |
 1174      /              |               |               |               |
 1175     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
 1176     +---------------+---------------+---------------+---------------+
 1177    0| 0x80          | 0x0b          | 0x00          | 0x00          |
 1178     +---------------+---------------+---------------+---------------+
 1179    4| 0x00          | 0x00          | 0x00          | 0x00          |
 1180     +---------------+---------------+---------------+---------------+
 1181    8| 0x00          | 0x00          | 0x00          | 0x00          |
 1182     +---------------+---------------+---------------+---------------+
 1183   12| 0x00          | 0x00          | 0x00          | 0x00          |
 1184     +---------------+---------------+---------------+---------------+
 1185   16| 0x00          | 0x00          | 0x00          | 0x00          |
 1186     +---------------+---------------+---------------+---------------+
 1187   20| 0x00          | 0x00          | 0x00          | 0x00          |
 1188     +---------------+---------------+---------------+---------------+
 1189     Total 24 bytes
 1190 
 1191 Field        (offset) (value)
 1192 Magic        (0)    : 0x80
 1193 Opcode       (1)    : 0x0b
 1194 Key length   (2,3)  : 0x0000
 1195 Extra length (4)    : 0x00
 1196 Data type    (5)    : 0x00
 1197 Reserved     (6,7)  : 0x0000
 1198 Total body   (8-11) : 0x00000000
 1199 Opaque       (12-15): 0x00000000
 1200 CAS          (16-23): 0x0000000000000000
 1201 Extras              : None
 1202             </artwork>
 1203           </figure>
 1204           <figure>
 1205             <preamble>Version response:</preamble>
 1206             <artwork>
 1207   Byte/     0       |       1       |       2       |       3       |
 1208      /              |               |               |               |
 1209     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
 1210     +---------------+---------------+---------------+---------------+
 1211    0| 0x81          | 0x0b          | 0x00          | 0x00          |
 1212     +---------------+---------------+---------------+---------------+
 1213    4| 0x00          | 0x00          | 0x00          | 0x00          |
 1214     +---------------+---------------+---------------+---------------+
 1215    8| 0x00          | 0x00          | 0x00          | 0x05          |
 1216     +---------------+---------------+---------------+---------------+
 1217   12| 0x00          | 0x00          | 0x00          | 0x00          |
 1218     +---------------+---------------+---------------+---------------+
 1219   16| 0x00          | 0x00          | 0x00          | 0x00          |
 1220     +---------------+---------------+---------------+---------------+
 1221   20| 0x00          | 0x00          | 0x00          | 0x00          |
 1222     +---------------+---------------+---------------+---------------+
 1223   24| 0x31 ('1')    | 0x2e ('.')    | 0x33 ('3')    | 0x2e ('.')    |
 1224     +---------------+---------------+---------------+---------------+
 1225   28| 0x31 ('1')    |
 1226     +---------------+
 1227     Total 29 bytes (24 byte header, 5 byte body)
 1228 
 1229 Field        (offset) (value)
 1230 Magic        (0)    : 0x81
 1231 Opcode       (1)    : 0x0b
 1232 Key length   (2,3)  : 0x0000
 1233 Extra length (4)    : 0x00
 1234 Data type    (5)    : 0x00
 1235 Status       (6,7)  : 0x0000
 1236 Total body   (8-11) : 0x00000005
 1237 Opaque       (12-15): 0x00000000
 1238 CAS          (16-23): 0x0000000000000000
 1239 Extras              : None
 1240 Key                 : None
 1241 Value               : Textual string "1.3.1"
 1242             </artwork>
 1243           </figure>
 1244         </section>
 1245       </section>
 1246 
 1247       <section anchor="command-append" title="Append, Prepend">
 1248         <t>
 1249         <list style="empty">
 1250           <t>MUST NOT have extras.</t>
 1251           <t>MUST have key.</t>
 1252           <t>MUST have value.</t>
 1253         </list>
 1254         </t>
 1255 
 1256         <t>
 1257           These commands will either append or prepend the specified
 1258           value to the requested key.
 1259         </t>
 1260 
 1261         <section anchor="command-append-example" title="Example">
 1262           <t>The following example appends '!' to the 'Hello' key.</t>
 1263           <figure>
 1264             <preamble>Append request:</preamble>
 1265             <artwork>
 1266   Byte/     0       |       1       |       2       |       3       |
 1267      /              |               |               |               |
 1268     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
 1269     +---------------+---------------+---------------+---------------+
 1270    0| 0x80          | 0x0e          | 0x00          | 0x05          |
 1271     +---------------+---------------+---------------+---------------+
 1272    4| 0x00          | 0x00          | 0x00          | 0x00          |
 1273     +---------------+---------------+---------------+---------------+
 1274    8| 0x00          | 0x00          | 0x00          | 0x06          |
 1275     +---------------+---------------+---------------+---------------+
 1276   12| 0x00          | 0x00          | 0x00          | 0x00          |
 1277     +---------------+---------------+---------------+---------------+
 1278   16| 0x00          | 0x00          | 0x00          | 0x00          |
 1279     +---------------+---------------+---------------+---------------+
 1280   20| 0x00          | 0x00          | 0x00          | 0x00          |
 1281     +---------------+---------------+---------------+---------------+
 1282   24| 0x48 ('H')    | 0x65 ('e')    | 0x6c ('l')    | 0x6c ('l')    |
 1283     +---------------+---------------+---------------+---------------+
 1284   28| 0x6f ('o')    | 0x21 ('!')    |
 1285     +---------------+---------------+
 1286     Total 30 bytes (24 byte header, 5 byte key, 1 byte value)
 1287 
 1288 Field        (offset) (value)
 1289 Magic        (0)    : 0x80
 1290 Opcode       (1)    : 0x0e
 1291 Key length   (2,3)  : 0x0005
 1292 Extra length (4)    : 0x00
 1293 Data type    (5)    : 0x00
 1294 Reserved     (6,7)  : 0x0000
 1295 Total body   (8-11) : 0x00000006
 1296 Opaque       (12-15): 0x00000000
 1297 CAS          (16-23): 0x0000000000000000
 1298 Extras              : None
 1299 Key          (24-28): The textual string "Hello"
 1300 Value        (29)   : "!"
 1301             </artwork>
 1302           </figure>
 1303           <t>
 1304             The response-packet contains no extra data, and the result of the
 1305             operation is signaled through the status code.
 1306           </t>
 1307         </section>
 1308       </section>
 1309 
 1310       <section anchor="command-stat" title="Stat">
 1311         <t>
 1312         <list style="empty">
 1313           <t>MUST NOT have extras.</t>
 1314           <t>MAY have key.</t>
 1315           <t>MUST NOT have value.</t>
 1316         </list>
 1317         </t>
 1318 
 1319         <t>
 1320       Request server statistics. Without a key specified the server will
 1321           respond with a "default" set of statistics information. Each piece
 1322           of statistical information is returned in its own packet (key
 1323           contains the name of the statistical item and the body contains the
 1324           value in ASCII format). The sequence of return packets is terminated
 1325           with a packet that contains no key and no value.
 1326         </t>
 1327         <section anchor="command-stat-example" title="Example">
 1328             <t>The following example requests all statistics from the server</t>
 1329           <figure>
 1330             <preamble>Stat request:</preamble>
 1331             <artwork>
 1332   Byte/     0       |       1       |       2       |       3       |
 1333      /              |               |               |               |
 1334     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
 1335     +---------------+---------------+---------------+---------------+
 1336    0| 0x80          | 0x10          | 0x00          | 0x00          |
 1337     +---------------+---------------+---------------+---------------+
 1338    4| 0x00          | 0x00          | 0x00          | 0x00          |
 1339     +---------------+---------------+---------------+---------------+
 1340    8| 0x00          | 0x00          | 0x00          | 0x00          |
 1341     +---------------+---------------+---------------+---------------+
 1342   12| 0x00          | 0x00          | 0x00          | 0x00          |
 1343     +---------------+---------------+---------------+---------------+
 1344   16| 0x00          | 0x00          | 0x00          | 0x00          |
 1345     +---------------+---------------+---------------+---------------+
 1346   20| 0x00          | 0x00          | 0x00          | 0x00          |
 1347     +---------------+---------------+---------------+---------------+
 1348     Total 24 bytes
 1349 
 1350 Field        (offset) (value)
 1351 Magic        (0)    : 0x80
 1352 Opcode       (1)    : 0x10
 1353 Key length   (2,3)  : 0x0000
 1354 Extra length (4)    : 0x00
 1355 Data type    (5)    : 0x00
 1356 Reserved     (6,7)  : 0x0000
 1357 Total body   (8-11) : 0x00000000
 1358 Opaque       (12-15): 0x00000000
 1359 CAS          (16-23): 0x0000000000000000
 1360 Extras              : None
 1361 Key                 : None
 1362 Value               : None
 1363             </artwork>
 1364           </figure>
 1365           <t>
 1366               The server will send each value in a separate packet with
 1367               an "empty" packet (no key / no value) to terminate the sequence.
 1368               Each of the response packets look like the following example:
 1369          </t>
 1370           <figure>
 1371             <preamble>Stat response:</preamble>
 1372             <artwork>
 1373   Byte/     0       |       1       |       2       |       3       |
 1374      /              |               |               |               |
 1375     |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
 1376     +---------------+---------------+---------------+---------------+
 1377    0| 0x81          | 0x10          | 0x00          | 0x03          |
 1378     +---------------+---------------+---------------+---------------+
 1379    4| 0x00          | 0x00          | 0x00          | 0x00          |
 1380     +---------------+---------------+---------------+---------------+
 1381    8| 0x00          | 0x00          | 0x00          | 0x07          |
 1382     +---------------+---------------+---------------+---------------+
 1383   12| 0x00          | 0x00          | 0x00          | 0x00          |
 1384     +---------------+---------------+---------------+---------------+
 1385   16| 0x00          | 0x00          | 0x00          | 0x00          |
 1386     +---------------+---------------+---------------+---------------+
 1387   20| 0x00          | 0x00          | 0x00          | 0x00          |
 1388     +---------------+---------------+---------------+---------------+
 1389   24| 0x70 ('p')    | 0x69 ('i')    | 0x64 ('d')    | 0x33 ('3')    |
 1390     +---------------+---------------+---------------+---------------+
 1391   28| 0x30 ('0')    | 0x37 ('7')    | 0x38 ('8')    |
 1392     +---------------+---------------+---------------+
 1393     Total 31 bytes (24 byte header, 3 byte key, 4 byte body)
 1394 
 1395 Field        (offset) (value)
 1396 Magic        (0)    : 0x81
 1397 Opcode       (1)    : 0x10
 1398 Key length   (2,3)  : 0x0003
 1399 Extra length (4)    : 0x00
 1400 Data type    (5)    : 0x00
 1401 Status       (6,7)  : 0x0000
 1402 Total body   (8-11) : 0x00000007
 1403 Opaque       (12-15): 0x00000000
 1404 CAS          (16-23): 0x0000000000000000
 1405 Extras              : None
 1406 Key                 : The textual string "pid"
 1407 Value               : The textual string "3078"
 1408             </artwork>
 1409           </figure>
 1410         </section>
 1411       </section>
 1412     </section>
 1413     <section anchor="security" title="Security Considerations">
 1414       <t>
 1415       Memcache has few authentication and no security layers whatsoever. It is
 1416       RECOMMENDED that memcache be deployed strictly on closed, protected,
 1417       back-end networks within a single data center, within a single cluster of
 1418       servers, or even on a single host, providing shared caching for multiple
 1419       applications. Memcache MUST NOT be made available on a public network.
 1420       </t>
 1421 
 1422       <t>
 1423       SASL is supported as an authentication mechanism. See the wiki for more
 1424       information.
 1425       </t>
 1426     </section>
 1427 
 1428   </middle>
 1429 
 1430   <back>
 1431     <references title="Normative References">
 1432       <reference anchor="LJ">
 1433         <front>
 1434           <title>LJ NEEDS MOAR SPEED</title>
 1435           <author fullname="Brad Fitzpatrick">
 1436             <organization>Danga Interactive</organization>
 1437           </author>
 1438           <date day="5" month="10" year="1999" />
 1439           <abstract>
 1440             <t>http://www.livejournal.com/</t>
 1441           </abstract>
 1442         </front>
 1443       </reference>
 1444       <dwdrfc-ref anchor="KEYWORDS" src='reference.RFC.2119.xml'/>
 1445     </references>
 1446 
 1447     <section anchor="acknowledgments" title="Acknowledgments">
 1448       <t>
 1449       Thanks to Brad Fitzpatrick, Anatoly Vorobey, Steven Grimm, and Dustin
 1450       Sallings, for their work on the memcached server.
 1451       </t>
 1452 
 1453       <t>
 1454       Thanks to Sean Chittenden, Jonathan Steinert, Brian Aker, Evan Martin,
 1455       Nathan Neulinger, Eric Hodel, Michael Johnson, Paul Querna, Jamie
 1456       McCarthy, Philip Neustrom, Andrew O'Brien, Josh Rotenberg, Robin H.
 1457       Johnson, Tim Yardley, Paolo Borelli, Eli Bingham, Jean-Francois
 1458       Bustarret, Paul G, Paul Lindner, Alan Kasindorf, Chris Goffinet, Tomash
 1459       Brechko, and others for their work reporting bugs and maintaining
 1460       memcached client libraries and bindings in many languages.
 1461       </t>
 1462     </section>
 1463   </back>
 1464 
 1465 </rfc>
 1466