<rfc category="info" docName="draft-stone-memcache-binary-01" ipr="trust200902">

  <front>

    <title> Memcache Binary Protocol </title>

    <author fullname="Aaron Stone" surname="Stone" role="editor">

      <organization>Six Apart, Ltd.</organization>

      <address>

        <postal>

          <street>548 4th Street</street>

          <city>San Francisco</city>

          <region>CA</region>

          94107

          <country>USA</country>

        </postal>

        <email>aaron@serendipity.palo-alto.ca.us</email>

      </address>

    </author>

    <author fullname="Trond Norbye" surname="Norbye" role="editor">

      <organization>Sun Microsystems, INC</organization>

      <address>

        <postal>

          <street>Haakon VII g. 7B</street>

          <city>Trondheim</city>

          NO-7485 Trondheim

          <country>Norway</country>

        </postal>

        <email>trond.norbye@sun.com</email>

      </address>

    </author>

    <date day="28" month="August" year="2008" />

    <area>Applications</area>

    <keyword>memcache memcached cache</keyword>

    <abstract>

      <t>

        This memo explains the memcache binary protocol for informational

        purposes.

      </t>

      <t>

        Memcache is a high performance key-value cache. It is intentionally a

        dumb cache, optimized for speed only. Applications using memcache do

        not rely on it for data -- a persistent database with guaranteed

        reliability is strongly recommended -- but applications can run much

        faster when cached data is available in memcache.

      </t>

    </abstract>

  </front>

  <middle>

    <section anchor="introduction" title="Introduction">

      <t>

        Memcache is a high performance key-value cache. It is intentionally a

        dumb cache, optimized for speed only. Applications using memcache should

        not rely on it for data -- a persistent database with guaranteed

        reliability is strongly recommended -- but applications can run much

        faster when cached data is available in memcache.

      </t>

      <t>

        Memcache was originally written to make

        <xref target="LJ">LiveJournal</xref> faster. It now powers all of

        the fastest web sites that you love.

      </t>

      <section anchor="conventions" title="Conventions Used In This Document">

        <t>

          The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",

          "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this

          document are to be interpreted as described in

          <xref target="KEYWORDS"/>.

        </t>

      </section>

    </section>

    <section anchor="packet" title="Packet Structure">

      <figure>

        <preamble>General format of a packet:</preamble>

        <artwork>

  Byte/     0       |       1       |       2       |       3       |

     /              |               |               |               |

    |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|

    +---------------+---------------+---------------+---------------+

   0/ HEADER                                                        /

    /                                                               /

    /                                                               /

    /                                                               /

    +---------------+---------------+---------------+---------------+

  24/ COMMAND-SPECIFIC EXTRAS (as needed)                           /

   +/  (note length in the extras length header field)              /

    +---------------+---------------+---------------+---------------+

   m/ Key (as needed)                                               /

   +/  (note length in key length header field)                     /

    +---------------+---------------+---------------+---------------+

   n/ Value (as needed)                                             /

   +/  (note length is total body length header field, minus        /

   +/   sum of the extras and key length body fields)               /

    +---------------+---------------+---------------+---------------+

    Total 24 bytes

        </artwork>

      </figure>

      <figure>

        <preamble>Request header:</preamble>

        <artwork>

  Byte/     0       |       1       |       2       |       3       |

     /              |               |               |               |

    |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|

    +---------------+---------------+---------------+---------------+

   0| Magic         | Opcode        | Key length                    |

    +---------------+---------------+---------------+---------------+

   4| Extras length | Data type     | Reserved                      |

    +---------------+---------------+---------------+---------------+

   8| Total body length                                             |

    +---------------+---------------+---------------+---------------+

  12| Opaque                                                        |

    +---------------+---------------+---------------+---------------+

  16| CAS                                                           |

    |                                                               |

    +---------------+---------------+---------------+---------------+

    Total 24 bytes

        </artwork>

      </figure>

      <figure>

        <preamble>Response header:</preamble>

        <artwork>

  Byte/     0       |       1       |       2       |       3       |

     /              |               |               |               |

    |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|

    +---------------+---------------+---------------+---------------+

   0| Magic         | Opcode        | Key Length                    |

    +---------------+---------------+---------------+---------------+

   4| Extras length | Data type     | Status                        |

    +---------------+---------------+---------------+---------------+

   8| Total body length                                             |

    +---------------+---------------+---------------+---------------+

  12| Opaque                                                        |

    +---------------+---------------+---------------+---------------+

  16| CAS                                                           |

    |                                                               |

    +---------------+---------------+---------------+---------------+

    Total 24 bytes

        </artwork>

      </figure>

      <t>

        Header fields:

        <list hangIndent="20" style="hanging">

          <t hangText="Magic">Magic number.</t>

          <t hangText="Opcode">Command code.</t>

          <t hangText="Key length">Length in bytes of the text key that follows the command extras.</t>

          <t hangText="Status">Status of the response (non-zero on error).</t>

          <t hangText="Extras length">Length in bytes of the command extras.</t>

          <t hangText="Data type">Reserved for future use (Sean is using this soon).</t>

          <t hangText="Reserved">Really reserved for future use (up for grabs).</t>

          <t hangText="Total body length">Length in bytes of extra + key + value.</t>

          <t hangText="Opaque">Will be copied back to you in the response.</t>

          <t hangText="CAS">Data version check.</t>

        </list>

      </t>

    </section>

    <section anchor="values" title="Defined Values">

      <section anchor="value-magic" title="Magic Byte">

        <t>

        <list hangIndent="8" style="hanging">

          <t hangText="0x80">Request packet for this protocol version</t>

          <t hangText="0x81">Response packet for this protocol version</t>

        </list>

        </t>

        <t>

          Magic byte / version. For each version of the protocol, we'll use a

          different request/response value pair. This is useful for protocol

          analyzers to distinguish the nature of the packet from the direction

          which it is moving. Note, it is common to run a memcached instance on

	  a host that also runs an application server. Such a host will both

	  send and receive memcache packets.

        </t>

        <t>

          The version should hopefully correspond only to different meanings of

          the command byte. In an ideal world, we will not change the header

          format. As reserved bytes are given defined meaning, the protocol

          version / magic byte values should be incremented.

        </t>

        <t>

          Traffic analysis tools are encouraged to identify memcache packets

          and provide detailed interpretation if the magic bytes are recognized

          and otherwise to provide a generic breakdown of the packet. Note, that

          the key and value positions can always be identified even if the magic

          byte or command opcode are not recognized.

        </t>

      </section>

      <section anchor="value-status" title="Response Status">

        <t>

        Possible values of this two-byte field:

        <list hangIndent="8" style="hanging">

          <t hangText="0x0000">No error</t>

          <t hangText="0x0001">Key not found</t>

          <t hangText="0x0002">Key exists</t>

          <t hangText="0x0003">Value too large</t>

          <t hangText="0x0004">Invalid arguments</t>

          <t hangText="0x0005">Item not stored</t>

          <t hangText="0x0006">Incr/Decr on non-numeric value.</t>

          <t hangText="0x0081">Unknown command</t>

          <t hangText="0x0082">Out of memory</t>

        </list>

        </t>

      </section>

      <section anchor="value-opcodes" title="Command Opcodes">

        <t>

        Possible values of the one-byte field:

        <list hangIndent="8" style="hanging">

          <t hangText="0x00">Get</t>

          <t hangText="0x01">Set</t>

          <t hangText="0x02">Add</t>

          <t hangText="0x03">Replace</t>

          <t hangText="0x04">Delete</t>

          <t hangText="0x05">Increment</t>

          <t hangText="0x06">Decrement</t>

          <t hangText="0x07">Quit</t>

          <t hangText="0x08">Flush</t>

          <t hangText="0x09">GetQ</t>

          <t hangText="0x0A">No-op</t>

          <t hangText="0x0B">Version</t>

          <t hangText="0x0C">GetK</t>

          <t hangText="0x0D">GetKQ</t>

          <t hangText="0x0E">Append</t>

          <t hangText="0x0F">Prepend</t>

	  <t hangText="0x10">Stat</t>

          <t hangText="0x11">SetQ</t>

          <t hangText="0x12">AddQ</t>

          <t hangText="0x13">ReplaceQ</t>

          <t hangText="0x14">DeleteQ</t>

          <t hangText="0x15">IncrementQ</t>

          <t hangText="0x16">DecrementQ</t>

          <t hangText="0x17">QuitQ</t>

          <t hangText="0x18">FlushQ</t>

          <t hangText="0x19">AppendQ</t>

          <t hangText="0x1A">PrependQ</t>

        </list>

        </t>

	      <t>

	        As a convention all of the commands ending with "Q" for

	        Quiet.  A quiet version of a command will omit responses

	        that are considered uninteresting.  Whether a given response

	        is interesting is dependent upon the command.  See the

	        descriptions of the

	        <xref target="command-get">set commands</xref>

	        and <xref target="command-set">set commands</xref> for

	        examples of commands that include quiet variants.

	      </t>

      </section>

      <section anchor="value-types" title="Data Types">

        <t>

        Possible values of the one-byte field:

        <list hangIndent="8" style="hanging">

          <t hangText="0x00">Raw bytes</t>

        </list>

        </t>

      </section>

    </section>

    <section title="Commands">

      <section anchor="command-introduction" title="Introduction">

        <t>

        All communication is initiated by a request from the client,

        and the server will respond to each request with zero or

	multiple packets for each request. If the status code of a response

	packet is non-nil, the body of the packet will contain a textual error

	message. If the status code is nil, the command opcode will define the

	layout of the body of the message.

        </t>

        <section anchor="command-introduction-example" title="Example">

            <t>

                The following figure illustrates the packet layout for

                a packet with an error message.

            </t>

          <figure>

            <preamble>Packet layout:</preamble>

            <artwork>

  Byte/     0       |       1       |       2       |       3       |

     /              |               |               |               |

    |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|

    +---------------+---------------+---------------+---------------+

   0| 0x81          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

   4| 0x00          | 0x00          | 0x00          | 0x01          |

    +---------------+---------------+---------------+---------------+

   8| 0x00          | 0x00          | 0x00          | 0x09          |

    +---------------+---------------+---------------+---------------+

  12| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

  16| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

  20| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

  24| 0x4e ('N')    | 0x6f ('o')    | 0x74 ('t')    | 0x20 (' ')    |

    +---------------+---------------+---------------+---------------+

  28| 0x66 ('f')    | 0x6f ('o')    | 0x75 ('u')    | 0x6e ('n')    |

    +---------------+---------------+---------------+---------------+

  32| 0x64 ('d')    |

    +---------------+

    Total 33 bytes (24 byte header, and 9 bytes value)

Field        (offset) (value)

Magic        (0)    : 0x81

Opcode       (1)    : 0x00

Key length   (2,3)  : 0x0000

Extra length (4)    : 0x00

Data type    (5)    : 0x00

Status       (6,7)  : 0x0001

Total body   (8-11) : 0x00000009

Opaque       (12-15): 0x00000000

CAS          (16-23): 0x0000000000000000

Extras              : None

Key                 : None

Value        (24-32): The textual string "Not found"

            </artwork>

          </figure>

        </section>

      </section>

      <section anchor="command-get" title="Get, Get Quietly, Get Key, Get Key Quietly">

        <t>

            Request:

        </t>

        <t>

        <list style="empty">

          <t>MUST NOT have extras.</t>

          <t>MUST have key.</t>

          <t>MUST NOT have value.</t>

        </list>

        </t>

        <t>

            Response (if found):

        </t>

        <t>

        <list style="empty">

          <t>MUST have extras.</t>

          <t>MAY have key.</t>

          <t>MAY have value.</t>

        </list>

        </t>

        <t>

        <list style="symbols">

          <t>4 byte flags</t>

        </list>

        </t>

        <t>

        <figure>

          <preamble>Extra data for the get commands:</preamble>

          <artwork>

  Byte/     0       |       1       |       2       |       3       |

     /              |               |               |               |

    |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|

    +---------------+---------------+---------------+---------------+

   0| Flags                                                         |

    +---------------+---------------+---------------+---------------+

    Total 4 bytes

          </artwork>

        </figure>

        </t>

        <t>

          The get command gets a single key. The getq command is both mum

          on cache miss and quiet, holding its response until a non-quiet

          command is issued. Getk and getkq differs from get and getq by

          adding the key into the response packet.

        </t>

        <t>

          You're not guaranteed a response to a getq/getkq cache hit until

          you send a non-getq/getkq command later, which uncorks the

          server and bundles up IOs to send to the client in one go.

        </t>

        <t>

          Clients should implement multi-get (still important for

          reducing network roundtrips!) as n pipelined requests, the

          first n-1 being getq/getkq, the last being a regular

          get/getk.  That way you're guaranteed to get a response, and

          you know when the server's done.  You can also do the naive

          thing and send n pipelined get/getks, but then you could potentially

          get back a lot of "NOT_FOUND" error code packets.

          Alternatively, you can send 'n' getq/getkqs, followed by a

          'noop' command.

        </t>

        <section anchor="command-get-example" title="Example">

          <t>

           To request the data associated with the key "Hello" the

           following fields must be specified in the packet.

          </t>

          <figure>

            <preamble>get request:</preamble>

            <artwork>

  Byte/     0       |       1       |       2       |       3       |

     /              |               |               |               |

    |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|

    +---------------+---------------+---------------+---------------+

   0| 0x80          | 0x00          | 0x00          | 0x05          |

    +---------------+---------------+---------------+---------------+

   4| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

   8| 0x00          | 0x00          | 0x00          | 0x05          |

    +---------------+---------------+---------------+---------------+

  12| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

  16| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

  20| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

  24| 0x48 ('H')    | 0x65 ('e')    | 0x6c ('l')    | 0x6c ('l')    |

    +---------------+---------------+---------------+---------------+

  28| 0x6f ('o')    |

    +---------------+

    Total 29 bytes (24 byte header, and 5 bytes key)

Field        (offset) (value)

Magic        (0)    : 0x80

Opcode       (1)    : 0x00

Key length   (2,3)  : 0x0005

Extra length (4)    : 0x00

Data type    (5)    : 0x00

Reserved     (6,7)  : 0x0000

Total body   (8-11) : 0x00000005

Opaque       (12-15): 0x00000000

CAS          (16-23): 0x0000000000000000

Extras              : None

Key          (24-29): The textual string: "Hello"

Value               : None

            </artwork>

          </figure>

          <t>If the item exist on the server the following packet is returned,

          otherwise a packet with status code != 0 will be returned (see

           <xref target="command-introduction">Introduction</xref>)

          </t>

          <figure>

            <preamble>get/getq response:</preamble>

            <artwork>

  Byte/     0       |       1       |       2       |       3       |

     /              |               |               |               |

    |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|

    +---------------+---------------+---------------+---------------+

   0| 0x81          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

   4| 0x04          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

   8| 0x00          | 0x00          | 0x00          | 0x09          |

    +---------------+---------------+---------------+---------------+

  12| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

  16| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

  20| 0x00          | 0x00          | 0x00          | 0x01          |

    +---------------+---------------+---------------+---------------+

  24| 0xde          | 0xad          | 0xbe          | 0xef          |

    +---------------+---------------+---------------+---------------+

  28| 0x57 ('W')    | 0x6f ('o')    | 0x72 ('r')    | 0x6c ('l')    |

    +---------------+---------------+---------------+---------------+

  32| 0x64 ('d')    |

    +---------------+

    Total 33 bytes (24 byte header, 4 byte extras and 5 byte value)

Field        (offset) (value)

Magic        (0)    : 0x81

Opcode       (1)    : 0x00

Key length   (2,3)  : 0x0000

Extra length (4)    : 0x04

Data type    (5)    : 0x00

Status       (6,7)  : 0x0000

Total body   (8-11) : 0x00000009

Opaque       (12-15): 0x00000000

CAS          (16-23): 0x0000000000000001

Extras              :

  Flags      (24-27): 0xdeadbeef

Key                 : None

Value        (28-32): The textual string "World"

            </artwork>

          </figure>

          <figure>

            <preamble>getk/getkq response:</preamble>

            <artwork>

  Byte/     0       |       1       |       2       |       3       |

     /              |               |               |               |

    |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|

    +---------------+---------------+---------------+---------------+

   0| 0x81          | 0x00          | 0x00          | 0x05          |

    +---------------+---------------+---------------+---------------+

   4| 0x04          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

   8| 0x00          | 0x00          | 0x00          | 0x09          |

    +---------------+---------------+---------------+---------------+

  12| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

  16| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

  20| 0x00          | 0x00          | 0x00          | 0x01          |

    +---------------+---------------+---------------+---------------+

  24| 0xde          | 0xad          | 0xbe          | 0xef          |

    +---------------+---------------+---------------+---------------+

  28| 0x48 ('H')    | 0x65 ('e')    | 0x6c ('l')    | 0x6c ('l')    |

    +---------------+---------------+---------------+---------------+

  32| 0x6f ('o')    | 0x57 ('W')    | 0x6f ('o')    | 0x72 ('r')    |

    +---------------+---------------+---------------+---------------+

  36| 0x6c ('l')    | 0x64 ('d')    |

    +---------------+---------------+

    Total 38 bytes (24 byte header, 4 byte extras, 5 byte key

                    and 5 byte value)

Field        (offset) (value)

Magic        (0)    : 0x81

Opcode       (1)    : 0x00

Key length   (2,3)  : 0x0005

Extra length (4)    : 0x04

Data type    (5)    : 0x00

Status       (6,7)  : 0x0000

Total body   (8-11) : 0x0000000E

Opaque       (12-15): 0x00000000

CAS          (16-23): 0x0000000000000001

Extras              :

  Flags      (24-27): 0xdeadbeef

Key          (28-32): The textual string: "Hello"

Value        (33-37): The textual string: "World"

            </artwork>

          </figure>

        </section>

      </section>

      <section anchor="command-set" title="Set, Add, Replace">

        <t>

        <list style="empty">

          <t>MUST have extras.</t>

          <t>MUST have key.</t>

          <t>MUST have value.</t>

        </list>

        </t>

        <t>

          <list style="symbols">

            <t>4 byte flags</t>

            <t>4 byte expiration time</t>

          </list>

        </t>

        <figure>

          <preamble>Extra data for set/add/replace:</preamble>

          <artwork>

  Byte/     0       |       1       |       2       |       3       |

     /              |               |               |               |

    |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|

    +---------------+---------------+---------------+---------------+

   0| Flags                                                         |

    +---------------+---------------+---------------+---------------+

   4| Expiration                                                    |

    +---------------+---------------+---------------+---------------+

    Total 8 bytes

          </artwork>

        </figure>

        <t>

        If the Data Version Check (CAS) is nonzero, the requested

        operation MUST only succeed if the item exists and has a CAS value

        identical to the provided value.

        </t>

        <t>

        Add MUST fail if the item already exist.

        </t>

        <t>

        Replace MUST fail if the item doesn't exist.

        </t>

        <t>

        Set should store the data unconditionally if the item exists

        or not.

        </t>

        <t>

          Quiet mutations only return responses on failure.  Success

          is considered the general case and is suppressed when in

          quiet mode, but errors should not be allowed to go

          unnoticed.

        </t>

        <section anchor="command-set-example" title="Example">

            <t>The following figure shows an add-command for

                <list style="empty">

                  <t>Key: "Hello"</t>

                  <t>Value: "World"</t>

                  <t>Flags: 0xdeadbeef</t>

                  <t>Expiry: in two hours</t>

                </list>

            </t>

           <figure>

             <preamble>Add request:</preamble>

             <artwork>

  Byte/     0       |       1       |       2       |       3       |

     /              |               |               |               |

    |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|

    +---------------+---------------+---------------+---------------+

   0| 0x80          | 0x02          | 0x00          | 0x05          |

    +---------------+---------------+---------------+---------------+

   4| 0x08          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

   8| 0x00          | 0x00          | 0x00          | 0x12          |

    +---------------+---------------+---------------+---------------+

  12| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

  16| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

  20| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

  24| 0xde          | 0xad          | 0xbe          | 0xef          |

    +---------------+---------------+---------------+---------------+

  28| 0x00          | 0x00          | 0x1c          | 0x20          |

    +---------------+---------------+---------------+---------------+

  32| 0x48 ('H')    | 0x65 ('e')    | 0x6c ('l')    | 0x6c ('l')    |

    +---------------+---------------+---------------+---------------+

  36| 0x6f ('o')    | 0x57 ('W')    | 0x6f ('o')    | 0x72 ('r')    |

    +---------------+---------------+---------------+---------------+

  40| 0x6c ('l')    | 0x64 ('d')    |

    +---------------+---------------+

    Total 42 bytes (24 byte header, 8 byte extras, 5 byte key and

                    5 byte value)

Field        (offset) (value)

Magic        (0)    : 0x80

Opcode       (1)    : 0x02

Key length   (2,3)  : 0x0005

Extra length (4)    : 0x08

Data type    (5)    : 0x00

Reserved     (6,7)  : 0x0000

Total body   (8-11) : 0x00000012

Opaque       (12-15): 0x00000000

CAS          (16-23): 0x0000000000000000

Extras              :

  Flags      (24-27): 0xdeadbeef

  Expiry     (28-31): 0x00001c20

Key          (32-36): The textual string "Hello"

Value        (37-41): The textual string "World"

             </artwork>

           </figure>

           <t>

        The response-packet contains no extra data, and the result of the

        operation is signaled through the status code. If the command

        succeeds, the CAS value for the item is returned in the CAS-field

        of the packet.

           </t>

           <figure>

             <preamble>Successful add response:</preamble>

             <artwork>

  Byte/     0       |       1       |       2       |       3       |

     /              |               |               |               |

    |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|

    +---------------+---------------+---------------+---------------+

   0| 0x81          | 0x02          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

   4| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

   8| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

  12| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

  16| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

  20| 0x00          | 0x00          | 0x00          | 0x01          |

    +---------------+---------------+---------------+---------------+

    Total 24 bytes

Field        (offset) (value)

Magic        (0)    : 0x81

Opcode       (1)    : 0x02

Key length   (2,3)  : 0x0000

Extra length (4)    : 0x00

Data type    (5)    : 0x00

Status       (6,7)  : 0x0000

Total body   (8-11) : 0x00000000

Opaque       (12-15): 0x00000000

CAS          (16-23): 0x0000000000000001

Extras              : None

Key                 : None

Value               : None

             </artwork>

           </figure>

         </section>

      </section>

      <section anchor="command-delete" title="Delete">

        <t>

        <list style="empty">

          <t>MUST NOT have extras.</t>

          <t>MUST have key.</t>

          <t>MUST NOT have value.</t>

        </list>

        </t>

        <t>

	  Delete the item with the specific key.

        </t>

        <section anchor="command-delete-example" title="Example">

          <t>The following figure shows a delete message for the

            item "Hello".</t>

          <figure>

            <preamble>Delete request:</preamble>

            <artwork>

  Byte/     0       |       1       |       2       |       3       |

     /              |               |               |               |

    |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|

    +---------------+---------------+---------------+---------------+

   0| 0x80          | 0x04          | 0x00          | 0x05          |

    +---------------+---------------+---------------+---------------+

   4| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

   8| 0x00          | 0x00          | 0x00          | 0x05          |

    +---------------+---------------+---------------+---------------+

  12| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

  16| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

  20| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

  24| 0x48 ('H')    | 0x65 ('e')    | 0x6c ('l')    | 0x6c ('l')    |

    +---------------+---------------+---------------+---------------+

  28| 0x6f ('o')    |

    +---------------+

    Total 29 bytes (24 byte header, 5 byte value)

Field        (offset) (value)

Magic        (0)    : 0x80

Opcode       (1)    : 0x04

Key length   (2,3)  : 0x0005

Extra length (4)    : 0x00

Data type    (5)    : 0x00

Reserved     (6,7)  : 0x0000

Total body   (8-11) : 0x00000005

Opaque       (12-15): 0x00000000

CAS          (16-23): 0x0000000000000000

Extras              : None

Key                 : The textual string "Hello"

Value               : None

            </artwork>

          </figure>

          <t>

            The response-packet contains no extra data, and the result of the

            operation is signaled through the status code.

          </t>

        </section>

      </section>

      <section anchor="command-incr" title="Increment, Decrement">

        <t>

          <list style="empty">

            <t>MUST have extras.</t>

            <t>MUST have key.</t>

            <t>MUST NOT have value.</t>

          </list>

        </t>

        <t>

          <list style="symbols">

            <t>8 byte value to add / subtract</t>

            <t>8 byte initial value (unsigned)</t>

            <t>4 byte expiration time</t>

          </list>

        </t>

        <figure>

          <preamble>Extra data for incr/decr:</preamble>

          <artwork>

  Byte/     0       |       1       |       2       |       3       |

     /              |               |               |               |

    |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|

    +---------------+---------------+---------------+---------------+

   0| Amount to add                                                 |

    |                                                               |

    +---------------+---------------+---------------+---------------+

   8| Initial value                                                 |

    |                                                               |

    +---------------+---------------+---------------+---------------+

  16| Expiration                                                    |

    +---------------+---------------+---------------+---------------+

    Total 20 bytes

          </artwork>

        </figure>

        <t>

          These commands will either add or remove the specified

          amount to the requested counter.

        </t>

        <t>

          If the counter does not exist, one of two things may happen:

        </t>

        <t>

          <list style="numbers">

          <t>If the expiration value is all one-bits (0xffffffff), the

             operation will fail with NOT_FOUND.</t>

          <t>For all other expiration values, the operation will succeed

             by seeding the value for this key with the provided initial

             value to expire with the provided expiration time. The flags

             will be set to zero.</t>

          </list>

        </t>

        <figure>

          <preamble>incr/decr response body:</preamble>

          <artwork>

  Byte/     0       |       1       |       2       |       3       |

     /              |               |               |               |

    |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|

    +---------------+---------------+---------------+---------------+

   0| 64-bit unsigned response.                                     |

    |                                                               |

    +---------------+---------------+---------------+---------------+

    Total 8 bytes

          </artwork>

        </figure>

        <section anchor="command-incr-example" title="Example">

            <t>The following figure shows an incr-command for

                <list style="empty">

                  <t>Key: "counter"</t>

                  <t>Delta: 0x01</t>

                  <t>Initial: 0x00</t>

                  <t>Expiry: in two hours</t>

                </list>

            </t>

            <figure>

              <preamble>Increment request:</preamble>

              <artwork>

  Byte/     0       |       1       |       2       |       3       |

     /              |               |               |               |

    |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|

    +---------------+---------------+---------------+---------------+

   0| 0x80          | 0x05          | 0x00          | 0x07          |

    +---------------+---------------+---------------+---------------+

   4| 0x14          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

   8| 0x00          | 0x00          | 0x00          | 0x1b          |

    +---------------+---------------+---------------+---------------+

  12| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

  16| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

  20| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

  24| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

  28| 0x00          | 0x00          | 0x00          | 0x01          |

    +---------------+---------------+---------------+---------------+

  32| 0x00          | 0x00          | 0x00          | 0x00          |

    +---------------+---------------+---------------+---------------+

  36| 0x00          | 0x00          | 0x00          | 0x00          |