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="none">
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>[email protected]</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>[email protected]</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
318Field        (offset) (value)
319Magic        (0)    : 0x81
320Opcode       (1)    : 0x00
321Key length   (2,3)  : 0x0000
322Extra length (4)    : 0x00
323Data type    (5)    : 0x00
324Status       (6,7)  : 0x0001
325Total body   (8-11) : 0x00000009
326Opaque       (12-15): 0x00000000
327CAS          (16-23): 0x0000000000000000
328Extras              : None
329Key                 : None
330Value        (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        <list style="symbols">
350          <t>4 byte flags</t>
351        </list>
352        </t>
353
354        <t>
355            Response (if found):
356        </t>
357        <t>
358        <list style="empty">
359          <t>MUST have extras.</t>
360          <t>MAY have key.</t>
361          <t>MAY have value.</t>
362        </list>
363        </t>
364
365        <t>
366        <list style="symbols">
367          <t>4 byte flags</t>
368        </list>
369        </t>
370
371        <t>
372        <figure>
373          <preamble>Extra data for the get commands:</preamble>
374          <artwork>
375  Byte/     0       |       1       |       2       |       3       |
376     /              |               |               |               |
377    |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|
378    +---------------+---------------+---------------+---------------+
379   0| Flags                                                         |
380    +---------------+---------------+---------------+---------------+
381
382    Total 4 bytes
383          </artwork>
384        </figure>
385        </t>
386
387        <t>
388          The get command gets a single key. The getq command is both mum
389          on cache miss and quiet, holding its response until a non-quiet
390          command is issued. Getk and getkq differs from get and getq by
391          adding the key into the response packet.
392        </t>
393
394        <t>
395          You're not guaranteed a response to a getq/getkq cache hit until
396          you send a non-getq/getkq command later, which uncorks the
397          server and bundles up IOs to send to the client in one go.
398        </t>
399
400        <t>
401          Clients should implement multi-get (still important for
402          reducing network roundtrips!) as n pipelined requests, the
403          first n-1 being getq/getkq, the last being a regular
404          get/getk.  That way you're guaranteed to get a response, and
405          you know when the server's done.  You can also do the naive
406          thing and send n pipelined get/getks, but then you could potentially
407          get back a lot of "NOT_FOUND" error code packets.
408          Alternatively, you can send 'n' getq/getkqs, followed by a
409          'noop' command.
410        </t>
411
412        <section anchor="command-get-example" title="Example">
413          <t>
414           To request the data associated with the key "Hello" the
415           following fields must be specified in the packet.
416          </t>
417          <figure>
418            <preamble>get request:</preamble>
419            <artwork>
420  Byte/     0       |       1       |       2       |       3       |
421     /              |               |               |               |
422    |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|
423    +---------------+---------------+---------------+---------------+
424   0| 0x80          | 0x00          | 0x00          | 0x05          |
425    +---------------+---------------+---------------+---------------+
426   4| 0x00          | 0x00          | 0x00          | 0x00          |
427    +---------------+---------------+---------------+---------------+
428   8| 0x00          | 0x00          | 0x00          | 0x05          |
429    +---------------+---------------+---------------+---------------+
430  12| 0x00          | 0x00          | 0x00          | 0x00          |
431    +---------------+---------------+---------------+---------------+
432  16| 0x00          | 0x00          | 0x00          | 0x00          |
433    +---------------+---------------+---------------+---------------+
434  20| 0x00          | 0x00          | 0x00          | 0x00          |
435    +---------------+---------------+---------------+---------------+
436  24| 0x48 ('H')    | 0x65 ('e')    | 0x6c ('l')    | 0x6c ('l')    |
437    +---------------+---------------+---------------+---------------+
438  28| 0x6f ('o')    |
439    +---------------+
440
441    Total 29 bytes (24 byte header, and 5 bytes key)
442
443Field        (offset) (value)
444Magic        (0)    : 0x80
445Opcode       (1)    : 0x00
446Key length   (2,3)  : 0x0005
447Extra length (4)    : 0x00
448Data type    (5)    : 0x00
449Reserved     (6,7)  : 0x0000
450Total body   (8-11) : 0x00000005
451Opaque       (12-15): 0x00000000
452CAS          (16-23): 0x0000000000000000
453Extras              : None
454Key          (24-29): The textual string: "Hello"
455Value               : None
456            </artwork>
457          </figure>
458          <t>If the item exist on the server the following packet is returned,
459          otherwise a packet with status code != 0 will be returned (see
460           <xref target="command-introduction">Introduction</xref>)
461          </t>
462          <figure>
463            <preamble>get/getq response:</preamble>
464            <artwork>
465
466  Byte/     0       |       1       |       2       |       3       |
467     /              |               |               |               |
468    |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|
469    +---------------+---------------+---------------+---------------+
470   0| 0x81          | 0x00          | 0x00          | 0x00          |
471    +---------------+---------------+---------------+---------------+
472   4| 0x04          | 0x00          | 0x00          | 0x00          |
473    +---------------+---------------+---------------+---------------+
474   8| 0x00          | 0x00          | 0x00          | 0x09          |
475    +---------------+---------------+---------------+---------------+
476  12| 0x00          | 0x00          | 0x00          | 0x00          |
477    +---------------+---------------+---------------+---------------+
478  16| 0x00          | 0x00          | 0x00          | 0x00          |
479    +---------------+---------------+---------------+---------------+
480  20| 0x00          | 0x00          | 0x00          | 0x01          |
481    +---------------+---------------+---------------+---------------+
482  24| 0xde          | 0xad          | 0xbe          | 0xef          |
483    +---------------+---------------+---------------+---------------+
484  28| 0x57 ('W')    | 0x6f ('o')    | 0x72 ('r')    | 0x6c ('l')    |
485    +---------------+---------------+---------------+---------------+
486  32| 0x64 ('d')    |
487    +---------------+
488
489    Total 33 bytes (24 byte header, 4 byte extras and 5 byte value)
490
491Field        (offset) (value)
492Magic        (0)    : 0x81
493Opcode       (1)    : 0x00
494Key length   (2,3)  : 0x0000
495Extra length (4)    : 0x04
496Data type    (5)    : 0x00
497Status       (6,7)  : 0x0000
498Total body   (8-11) : 0x00000009
499Opaque       (12-15): 0x00000000
500CAS          (16-23): 0x0000000000000001
501Extras              :
502  Flags      (24-27): 0xdeadbeef
503Key                 : None
504Value        (28-32): The textual string "World"
505            </artwork>
506          </figure>
507          <figure>
508            <preamble>getk/getkq response:</preamble>
509            <artwork>
510
511  Byte/     0       |       1       |       2       |       3       |
512     /              |               |               |               |
513    |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|
514    +---------------+---------------+---------------+---------------+
515   0| 0x81          | 0x00          | 0x00          | 0x05          |
516    +---------------+---------------+---------------+---------------+
517   4| 0x04          | 0x00          | 0x00          | 0x00          |
518    +---------------+---------------+---------------+---------------+
519   8| 0x00          | 0x00          | 0x00          | 0x09          |
520    +---------------+---------------+---------------+---------------+
521  12| 0x00          | 0x00          | 0x00          | 0x00          |
522    +---------------+---------------+---------------+---------------+
523  16| 0x00          | 0x00          | 0x00          | 0x00          |
524    +---------------+---------------+---------------+---------------+
525  20| 0x00          | 0x00          | 0x00          | 0x01          |
526    +---------------+---------------+---------------+---------------+
527  24| 0xde          | 0xad          | 0xbe          | 0xef          |
528    +---------------+---------------+---------------+---------------+
529  28| 0x48 ('H')    | 0x65 ('e')    | 0x6c ('l')    | 0x6c ('l')    |
530    +---------------+---------------+---------------+---------------+
531  32| 0x6f ('o')    | 0x57 ('W')    | 0x6f ('o')    | 0x72 ('r')    |
532    +---------------+---------------+---------------+---------------+
533  36| 0x6c ('l')    | 0x64 ('d')    |
534    +---------------+---------------+
535
536    Total 38 bytes (24 byte header, 4 byte extras, 5 byte key
537                    and 5 byte value)
538
539Field        (offset) (value)
540Magic        (0)    : 0x81
541Opcode       (1)    : 0x00
542Key length   (2,3)  : 0x0005
543Extra length (4)    : 0x04
544Data type    (5)    : 0x00
545Status       (6,7)  : 0x0000
546Total body   (8-11) : 0x00000009
547Opaque       (12-15): 0x00000000
548CAS          (16-23): 0x0000000000000001
549Extras              :
550  Flags      (24-27): 0xdeadbeef
551Key          (28-32): The textual string: "Hello"
552Value        (33-37): The textual string: "World"
553            </artwork>
554          </figure>
555        </section>
556      </section>
557
558      <section anchor="command-set" title="Set, Add, Replace">
559        <t>
560        <list style="empty">
561          <t>MUST have extras.</t>
562          <t>MUST have key.</t>
563          <t>MUST have value.</t>
564        </list>
565        </t>
566
567        <t>
568          <list style="symbols">
569            <t>4 byte flags</t>
570            <t>4 byte expiration time</t>
571          </list>
572        </t>
573
574        <figure>
575          <preamble>Extra data for set/add/replace:</preamble>
576          <artwork>
577  Byte/     0       |       1       |       2       |       3       |
578     /              |               |               |               |
579    |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|
580    +---------------+---------------+---------------+---------------+
581   0| Flags                                                         |
582    +---------------+---------------+---------------+---------------+
583   4| Expiration                                                    |
584    +---------------+---------------+---------------+---------------+
585    Total 8 bytes
586          </artwork>
587        </figure>
588
589        <t>
590        If the Data Version Check (CAS) is nonzero, the requested
591        operation MUST only succeed if the item exists and has a CAS value
592        identical to the provided value.
593        </t>
594
595        <t>
596        Add MUST fail if the item already exist.
597        </t>
598
599        <t>
600        Replace MUST fail if the item doesn't exist.
601        </t>
602
603        <t>
604        Set should store the data unconditionally if the item exists
605        or not.
606        </t>
607
608        <t>
609          Quiet mutations only return responses on failure.  Success
610          is considered the general case and is suppressed when in
611          quiet mode, but errors should not be allowed to go
612          unnoticed.
613        </t>
614
615        <section anchor="command-set-example" title="Example">
616            <t>The following figure shows an add-command for
617                <list style="empty">
618                  <t>Key: "Hello"</t>
619                  <t>Value: "World"</t>
620                  <t>Flags: 0xdeadbeef</t>
621                  <t>Expiry: in two hours</t>
622                </list>
623            </t>
624           <figure>
625             <preamble>Add request:</preamble>
626             <artwork>
627
628  Byte/     0       |       1       |       2       |       3       |
629     /              |               |               |               |
630    |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|
631    +---------------+---------------+---------------+---------------+
632   0| 0x80          | 0x02          | 0x00          | 0x05          |
633    +---------------+---------------+---------------+---------------+
634   4| 0x08          | 0x00          | 0x00          | 0x00          |
635    +---------------+---------------+---------------+---------------+
636   8| 0x00          | 0x00          | 0x00          | 0x12          |
637    +---------------+---------------+---------------+---------------+
638  12| 0x00          | 0x00          | 0x00          | 0x00          |
639    +---------------+---------------+---------------+---------------+
640  16| 0x00          | 0x00          | 0x00          | 0x00          |
641    +---------------+---------------+---------------+---------------+
642  20| 0x00          | 0x00          | 0x00          | 0x00          |
643    +---------------+---------------+---------------+---------------+
644  24| 0xde          | 0xad          | 0xbe          | 0xef          |
645    +---------------+---------------+---------------+---------------+
646  28| 0x00          | 0x00          | 0x0e          | 0x10          |
647    +---------------+---------------+---------------+---------------+
648  32| 0x48 ('H')    | 0x65 ('e')    | 0x6c ('l')    | 0x6c ('l')    |
649    +---------------+---------------+---------------+---------------+
650  36| 0x6f ('o')    | 0x57 ('W')    | 0x6f ('o')    | 0x72 ('r')    |
651    +---------------+---------------+---------------+---------------+
652  40| 0x6c ('l')    | 0x64 ('d')    |
653    +---------------+---------------+
654
655    Total 42 bytes (24 byte header, 8 byte extras, 5 byte key and
656                    5 byte value)
657
658Field        (offset) (value)
659Magic        (0)    : 0x80
660Opcode       (1)    : 0x02
661Key length   (2,3)  : 0x0005
662Extra length (4)    : 0x08
663Data type    (5)    : 0x00
664Reserved     (6,7)  : 0x0000
665Total body   (8-11) : 0x00000012
666Opaque       (12-15): 0x00000000
667CAS          (16-23): 0x0000000000000000
668Extras              :
669  Flags      (24-27): 0xdeadbeef
670  Expiry     (28-31): 0x00000e10
671Key          (32-36): The textual string "Hello"
672Value        (37-41): The textual string "World"
673             </artwork>
674           </figure>
675           <t>
676        The response-packet contains no extra data, and the result of the
677        operation is signaled through the status code. If the command
678        succeeds, the CAS value for the item is returned in the CAS-field
679        of the packet.
680           </t>
681           <figure>
682             <preamble>Successful add response:</preamble>
683             <artwork>
684
685  Byte/     0       |       1       |       2       |       3       |
686     /              |               |               |               |
687    |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|
688    +---------------+---------------+---------------+---------------+
689   0| 0x81          | 0x02          | 0x00          | 0x00          |
690    +---------------+---------------+---------------+---------------+
691   4| 0x00          | 0x00          | 0x00          | 0x00          |
692    +---------------+---------------+---------------+---------------+
693   8| 0x00          | 0x00          | 0x00          | 0x00          |
694    +---------------+---------------+---------------+---------------+
695  12| 0x00          | 0x00          | 0x00          | 0x00          |
696    +---------------+---------------+---------------+---------------+
697  16| 0x00          | 0x00          | 0x00          | 0x00          |
698    +---------------+---------------+---------------+---------------+
699  20| 0x00          | 0x00          | 0x00          | 0x01          |
700    +---------------+---------------+---------------+---------------+
701
702    Total 24 bytes
703
704Field        (offset) (value)
705Magic        (0)    : 0x81
706Opcode       (1)    : 0x02
707Key length   (2,3)  : 0x0000
708Extra length (4)    : 0x00
709Data type    (5)    : 0x00
710Status       (6,7)  : 0x0000
711Total body   (8-11) : 0x00000000
712Opaque       (12-15): 0x00000000
713CAS          (16-23): 0x0000000000000001
714Extras              : None
715Key                 : None
716Value               : None
717             </artwork>
718           </figure>
719         </section>
720      </section>
721
722      <section anchor="command-delete" title="Delete">
723        <t>
724        <list style="empty">
725          <t>MUST NOT have extras.</t>
726          <t>MUST have key.</t>
727          <t>MUST NOT have value.</t>
728        </list>
729        </t>
730
731        <t>
732	  Delete the item with the specific key.
733        </t>
734
735        <section anchor="command-delete-example" title="Example">
736          <t>The following figure shows a delete message for the
737            item "Hello".</t>
738          <figure>
739            <preamble>Delete request:</preamble>
740            <artwork>
741  Byte/     0       |       1       |       2       |       3       |
742     /              |               |               |               |
743    |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|
744    +---------------+---------------+---------------+---------------+
745   0| 0x80          | 0x04          | 0x00          | 0x05          |
746    +---------------+---------------+---------------+---------------+
747   4| 0x00          | 0x00          | 0x00          | 0x00          |
748    +---------------+---------------+---------------+---------------+
749   8| 0x00          | 0x00          | 0x00          | 0x05          |
750    +---------------+---------------+---------------+---------------+
751  12| 0x00          | 0x00          | 0x00          | 0x00          |
752    +---------------+---------------+---------------+---------------+
753  16| 0x00          | 0x00          | 0x00          | 0x00          |
754    +---------------+---------------+---------------+---------------+
755  20| 0x00          | 0x00          | 0x00          | 0x00          |
756    +---------------+---------------+---------------+---------------+
757  24| 0x48 ('H')    | 0x65 ('e')    | 0x6c ('l')    | 0x6c ('l')    |
758    +---------------+---------------+---------------+---------------+
759  28| 0x6f ('o')    |
760    +---------------+
761
762    Total 29 bytes (24 byte header, 5 byte value)
763
764Field        (offset) (value)
765Magic        (0)    : 0x80
766Opcode       (1)    : 0x04
767Key length   (2,3)  : 0x0005
768Extra length (4)    : 0x00
769Data type    (5)    : 0x00
770Reserved     (6,7)  : 0x0000
771Total body   (8-11) : 0x00000005
772Opaque       (12-15): 0x00000000
773CAS          (16-23): 0x0000000000000000
774Extras              : None
775Key                 : The textual string "Hello"
776Value               : None
777            </artwork>
778          </figure>
779          <t>
780            The response-packet contains no extra data, and the result of the
781            operation is signaled through the status code.
782          </t>
783        </section>
784      </section>
785
786      <section anchor="command-incr" title="Increment, Decrement">
787        <t>
788          <list style="empty">
789            <t>MUST have extras.</t>
790            <t>MUST have key.</t>
791            <t>MUST NOT have value.</t>
792          </list>
793        </t>
794
795        <t>
796          <list style="symbols">
797            <t>8 byte value to add / subtract</t>
798            <t>8 byte initial value (unsigned)</t>
799            <t>4 byte expiration time</t>
800          </list>
801        </t>
802        <figure>
803          <preamble>Extra data for incr/decr:</preamble>
804          <artwork>
805  Byte/     0       |       1       |       2       |       3       |
806     /              |               |               |               |
807    |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|
808    +---------------+---------------+---------------+---------------+
809   0| Amount to add                                                 |
810    |                                                               |
811    +---------------+---------------+---------------+---------------+
812   8| Initial value                                                 |
813    |                                                               |
814    +---------------+---------------+---------------+---------------+
815  16| Expiration                                                    |
816    +---------------+---------------+---------------+---------------+
817    Total 20 bytes
818          </artwork>
819        </figure>
820
821        <t>
822          These commands will either add or remove the specified
823          amount to the requested counter.
824        </t>
825        <t>
826          If the counter does not exist, one of two things may happen:
827        </t>
828        <t>
829          <list style="numbers">
830          <t>If the expiration value is all one-bits (0xffffffff), the
831             operation will fail with NOT_FOUND.</t>
832          <t>For all other expiration values, the operation will succeed
833             by seeding the value for this key with the provided initial
834             value to expire with the provided expiration time. The flags
835             will be set to zero.</t>
836          </list>
837        </t>
838        <figure>
839          <preamble>incr/decr response body:</preamble>
840          <artwork>
841  Byte/     0       |       1       |       2       |       3       |
842     /              |               |               |               |
843    |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|
844    +---------------+---------------+---------------+---------------+
845   0| 64-bit unsigned response.                                     |
846    |                                                               |
847    +---------------+---------------+---------------+---------------+
848    Total 8 bytes
849          </artwork>
850        </figure>
851        <section anchor="command-incr-example" title="Example">
852            <t>The following figure shows an incr-command for
853                <list style="empty">
854                  <t>Key: "counter"</t>
855                  <t>Delta: 0x01</t>
856                  <t>Initial: 0x00</t>
857                  <t>Expiry: in two hours</t>
858                </list>
859            </t>
860            <figure>
861              <preamble>Increment request:</preamble>
862              <artwork>
863
864  Byte/     0       |       1       |       2       |       3       |
865     /              |               |               |               |
866    |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|
867    +---------------+---------------+---------------+---------------+
868   0| 0x80          | 0x05          | 0x00          | 0x07          |
869    +---------------+---------------+---------------+---------------+
870   4| 0x14          | 0x00          | 0x00          | 0x00          |
871    +---------------+---------------+---------------+---------------+
872   8| 0x00          | 0x00          | 0x00          | 0x1b          |
873    +---------------+---------------+---------------+---------------+
874  12| 0x00          | 0x00          | 0x00          | 0x00          |
875    +---------------+---------------+---------------+---------------+
876  16| 0x00          | 0x00          | 0x00          | 0x00          |
877    +---------------+---------------+---------------+---------------+
878  20| 0x00          | 0x00          | 0x00          | 0x00          |
879    +---------------+---------------+---------------+---------------+
880  24| 0x00          | 0x00          | 0x00          | 0x00          |
881    +---------------+---------------+---------------+---------------+
882  28| 0x00          | 0x00          | 0x00          | 0x01          |
883    +---------------+---------------+---------------+---------------+
884  32| 0x00          | 0x00          | 0x00          | 0x00          |
885    +---------------+---------------+---------------+---------------+
886  36| 0x00          | 0x00          | 0x00          | 0x00          |
887    +---------------+---------------+---------------+---------------+
888  40| 0x00          | 0x00          | 0x0e          | 0x10          |
889    +---------------+---------------+---------------+---------------+
890  44| 0x63 ('c')    | 0x6f ('o')    | 0x75 ('u')    | 0x6e ('n')    |
891    +---------------+---------------+---------------+---------------+
892  48| 0x74 ('t')    | 0x65 ('e')    | 0x72 ('r')    |
893    +---------------+---------------+---------------+
894    Total 51 bytes (24 byte header, 20 byte extras, 7 byte key)
895
896Field        (offset) (value)
897Magic        (0)    : 0x80
898Opcode       (1)    : 0x05
899Key length   (2,3)  : 0x0007
900Extra length (4)    : 0x14
901Data type    (5)    : 0x00
902Reserved     (6,7)  : 0x0000
903Total body   (8-11) : 0x0000001b
904Opaque       (12-15): 0x00000000
905CAS          (16-23): 0x0000000000000000
906Extras              :
907  delta      (24-31): 0x0000000000000001
908  initial    (32-39): 0x0000000000000000
909  exipration (40-43): 0x00000e10
910Key                 : Textual string "counter"
911Value               : None
912              </artwork>
913            </figure>
914            <t>
915             If the key doesn't exist, the server will respond with the
916             initial value. If not the incremented value will be returned.
917             Let's assume that the key didn't exist, so the initial value
918             is returned.
919            </t>
920            <figure>
921              <preamble>Increment response:</preamble>
922              <artwork>
923  Byte/     0       |       1       |       2       |       3       |
924     /              |               |               |               |
925    |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|
926    +---------------+---------------+---------------+---------------+
927   0| 0x81          | 0x05          | 0x00          | 0x00          |
928    +---------------+---------------+---------------+---------------+
929   4| 0x00          | 0x00          | 0x00          | 0x00          |
930    +---------------+---------------+---------------+---------------+
931   8| 0x00          | 0x00          | 0x00          | 0x08          |
932    +---------------+---------------+---------------+---------------+
933  12| 0x00          | 0x00          | 0x00          | 0x00          |
934    +---------------+---------------+---------------+---------------+
935  16| 0x00          | 0x00          | 0x00          | 0x00          |
936    +---------------+---------------+---------------+---------------+
937  20| 0x00          | 0x00          | 0x00          | 0x05          |
938    +---------------+---------------+---------------+---------------+
939  24| 0x00          | 0x00          | 0x00          | 0x00          |
940    +---------------+---------------+---------------+---------------+
941  28| 0x00          | 0x00          | 0x00          | 0x00          |
942    +---------------+---------------+---------------+---------------+
943    Total 32 bytes (24 byte header, 8 byte value)
944
945Field        (offset) (value)
946Magic        (0)    : 0x81
947Opcode       (1)    : 0x05
948Key length   (2,3)  : 0x0000
949Extra length (4)    : 0x00
950Data type    (5)    : 0x00
951Status       (6,7)  : 0x0000
952Total body   (8-11) : 0x00000008
953Opaque       (12-15): 0x00000000
954CAS          (16-23): 0x0000000000000005
955Extras              : None
956Key                 : None
957Value               : 0x0000000000000000
958              </artwork>
959            </figure>
960          </section>
961      </section>
962
963      <section anchor="command-quit" title="quit">
964        <t>
965        <list style="empty">
966          <t>MUST NOT have extras.</t>
967          <t>MUST NOT have key.</t>
968          <t>MUST NOT have value.</t>
969        </list>
970        </t>
971
972        <t>
973        Close the connection to the server.
974        </t>
975
976        <section anchor="command-quit-example" title="Example">
977          <figure>
978            <preamble>Quit request:</preamble>
979            <artwork>
980  Byte/     0       |       1       |       2       |       3       |
981     /              |               |               |               |
982    |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|
983    +---------------+---------------+---------------+---------------+
984   0| 0x80          | 0x07          | 0x00          | 0x00          |
985    +---------------+---------------+---------------+---------------+
986   4| 0x00          | 0x00          | 0x00          | 0x00          |
987    +---------------+---------------+---------------+---------------+
988   8| 0x00          | 0x00          | 0x00          | 0x00          |
989    +---------------+---------------+---------------+---------------+
990  12| 0x00          | 0x00          | 0x00          | 0x00          |
991    +---------------+---------------+---------------+---------------+
992  16| 0x00          | 0x00          | 0x00          | 0x00          |
993    +---------------+---------------+---------------+---------------+
994  20| 0x00          | 0x00          | 0x00          | 0x00          |
995    +---------------+---------------+---------------+---------------+
996    Total 24 bytes
997
998Field        (offset) (value)
999Magic        (0)    : 0x80
1000Opcode       (1)    : 0x07
1001Key length   (2,3)  : 0x0000
1002Extra length (4)    : 0x00
1003Data type    (5)    : 0x00
1004Reserved     (6,7)  : 0x0000
1005Total body   (8-11) : 0x00000000
1006Opaque       (12-15): 0x00000000
1007CAS          (16-23): 0x0000000000000000
1008Extras              : None
1009Key                 : None
1010Value               : None
1011            </artwork>
1012          </figure>
1013          <t>
1014            The response-packet contains no extra data, and the result of the
1015            operation is signaled through the status code. The server will
1016            then close the connection.
1017          </t>
1018        </section>
1019      </section>
1020
1021      <section anchor="command-flush" title="Flush">
1022        <t>
1023          <list style="empty">
1024            <t>MAY have extras.</t>
1025            <t>MUST NOT have key.</t>
1026            <t>MUST NOT have value.</t>
1027          </list>
1028        </t>
1029
1030        <t>
1031          <list style="symbols">
1032            <t>4 byte expiration time</t>
1033          </list>
1034        </t>
1035        <figure>
1036          <preamble>Extra data for flush:</preamble>
1037          <artwork>
1038  Byte/     0       |       1       |       2       |       3       |
1039     /              |               |               |               |
1040    |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|
1041    +---------------+---------------+---------------+---------------+
1042   0| Expiration                                                    |
1043    +---------------+---------------+---------------+---------------+
1044  Total 4 bytes
1045          </artwork>
1046        </figure>
1047        <t>
1048            Flush the items in the cache now or some time in the future as
1049            specified by the expiration field. See the documentation of the
1050            textual protocol for the full description on how to specify the
1051            expiration time.
1052        </t>
1053        <section anchor="command-flush-example" title="Example">
1054        <t>
1055            To flush the cache (delete all items) in two hours, the set
1056            the following values in the request
1057        </t>
1058        <figure>
1059          <preamble>Flush request:</preamble>
1060          <artwork>
1061  Byte/     0       |       1       |       2       |       3       |
1062     /              |               |               |               |
1063    |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|
1064    +---------------+---------------+---------------+---------------+
1065   0| 0x80          | 0x08          | 0x00          | 0x00          |
1066    +---------------+---------------+---------------+---------------+
1067   4| 0x04          | 0x00          | 0x00          | 0x00          |
1068    +---------------+---------------+---------------+---------------+
1069   8| 0x00          | 0x00          | 0x00          | 0x04          |
1070    +---------------+---------------+---------------+---------------+
1071  12| 0x00          | 0x00          | 0x00          | 0x00          |
1072    +---------------+---------------+---------------+---------------+
1073  16| 0x00          | 0x00          | 0x00          | 0x00          |
1074    +---------------+---------------+---------------+---------------+
1075  20| 0x00          | 0x00          | 0x00          | 0x00          |
1076    +---------------+---------------+---------------+---------------+
1077  24| 0x00          | 0x00          | 0x0e          | 0x10          |
1078    +---------------+---------------+---------------+---------------+
1079    Total 28 bytes (24 byte header, 4 byte body)
1080
1081Field        (offset) (value)
1082Magic        (0)    : 0x80
1083Opcode       (1)    : 0x08
1084Key length   (2,3)  : 0x0000
1085Extra length (4)    : 0x04
1086Data type    (5)    : 0x00
1087Reserved     (6,7)  : 0x0000
1088Total body   (8-11) : 0x00000004
1089Opaque       (12-15): 0x00000000
1090CAS          (16-23): 0x0000000000000000
1091Extras              :
1092   Expiry    (24-27): 0x000e10
1093Key                 : None
1094Value               : None
1095          </artwork>
1096        </figure>
1097          <t>
1098            The response-packet contains no extra data, and the result of the
1099            operation is signaled through the status code.
1100          </t>
1101        </section>
1102      </section>
1103      <section anchor="command-noop" title="noop">
1104        <t>
1105        <list style="empty">
1106          <t>MUST NOT have extras.</t>
1107          <t>MUST NOT have key.</t>
1108          <t>MUST NOT have value.</t>
1109        </list>
1110        </t>
1111
1112        <t>
1113        Used as a keep alive. Flushes outstanding getq/getkq's.
1114        </t>
1115        <section anchor="command-noop-example" title="Example">
1116          <figure>
1117            <preamble>Noop request:</preamble>
1118            <artwork>
1119  Byte/     0       |       1       |       2       |       3       |
1120     /              |               |               |               |
1121    |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|
1122    +---------------+---------------+---------------+---------------+
1123   0| 0x80          | 0x0a          | 0x00          | 0x00          |
1124    +---------------+---------------+---------------+---------------+
1125   4| 0x00          | 0x00          | 0x00          | 0x00          |
1126    +---------------+---------------+---------------+---------------+
1127   8| 0x00          | 0x00          | 0x00          | 0x00          |
1128    +---------------+---------------+---------------+---------------+
1129  12| 0x00          | 0x00          | 0x00          | 0x00          |
1130    +---------------+---------------+---------------+---------------+
1131  16| 0x00          | 0x00          | 0x00          | 0x00          |
1132    +---------------+---------------+---------------+---------------+
1133  20| 0x00          | 0x00          | 0x00          | 0x00          |
1134    +---------------+---------------+---------------+---------------+
1135    Total 24 bytes
1136
1137Field        (offset) (value)
1138Magic        (0)    : 0x80
1139Opcode       (1)    : 0x0a
1140Key length   (2,3)  : 0x0000
1141Extra length (4)    : 0x00
1142Data type    (5)    : 0x00
1143Reserved     (6,7)  : 0x0000
1144Total body   (8-11) : 0x00000000
1145Opaque       (12-15): 0x00000000
1146CAS          (16-23): 0x0000000000000000
1147Extras              : None
1148Key                 : None
1149Value               : None
1150            </artwork>
1151          </figure>
1152          <t>
1153            The response-packet contains no extra data, and the result of the
1154            operation is signaled through the status code.
1155          </t>
1156        </section>
1157      </section>
1158
1159      <section anchor="command-version" title="version">
1160        <t>
1161        <list style="empty">
1162          <t>MUST NOT have extras.</t>
1163          <t>MUST NOT have key.</t>
1164          <t>MUST NOT have value.</t>
1165        </list>
1166        </t>
1167
1168        <t>
1169          Request the server version.
1170        </t>
1171        <t>
1172	  The server responds with a packet containing the version string
1173	  in the body with the following format: "x.y.z"
1174        </t>
1175        <section anchor="command-version-example" title="Example">
1176          <figure>
1177            <preamble>Version request:</preamble>
1178            <artwork>
1179  Byte/     0       |       1       |       2       |       3       |
1180     /              |               |               |               |
1181    |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|
1182    +---------------+---------------+---------------+---------------+
1183   0| 0x80          | 0x0b          | 0x00          | 0x00          |
1184    +---------------+---------------+---------------+---------------+
1185   4| 0x00          | 0x00          | 0x00          | 0x00          |
1186    +---------------+---------------+---------------+---------------+
1187   8| 0x00          | 0x00          | 0x00          | 0x00          |
1188    +---------------+---------------+---------------+---------------+
1189  12| 0x00          | 0x00          | 0x00          | 0x00          |
1190    +---------------+---------------+---------------+---------------+
1191  16| 0x00          | 0x00          | 0x00          | 0x00          |
1192    +---------------+---------------+---------------+---------------+
1193  20| 0x00          | 0x00          | 0x00          | 0x00          |
1194    +---------------+---------------+---------------+---------------+
1195    Total 24 bytes
1196
1197Field        (offset) (value)
1198Magic        (0)    : 0x80
1199Opcode       (1)    : 0x0b
1200Key length   (2,3)  : 0x0000
1201Extra length (4)    : 0x00
1202Data type    (5)    : 0x00
1203Reserved     (6,7)  : 0x0000
1204Total body   (8-11) : 0x00000000
1205Opaque       (12-15): 0x00000000
1206CAS          (16-23): 0x0000000000000000
1207Extras              : None
1208            </artwork>
1209          </figure>
1210          <figure>
1211            <preamble>Version response:</preamble>
1212            <artwork>
1213  Byte/     0       |       1       |       2       |       3       |
1214     /              |               |               |               |
1215    |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|
1216    +---------------+---------------+---------------+---------------+
1217   0| 0x81          | 0x0b          | 0x00          | 0x00          |
1218    +---------------+---------------+---------------+---------------+
1219   4| 0x00          | 0x00          | 0x00          | 0x00          |
1220    +---------------+---------------+---------------+---------------+
1221   8| 0x00          | 0x00          | 0x00          | 0x05          |
1222    +---------------+---------------+---------------+---------------+
1223  12| 0x00          | 0x00          | 0x00          | 0x00          |
1224    +---------------+---------------+---------------+---------------+
1225  16| 0x00          | 0x00          | 0x00          | 0x00          |
1226    +---------------+---------------+---------------+---------------+
1227  20| 0x00          | 0x00          | 0x00          | 0x00          |
1228    +---------------+---------------+---------------+---------------+
1229  24| 0x31 ('1')    | 0x2e ('.')    | 0x33 ('3')    | 0x2e ('.')    |
1230    +---------------+---------------+---------------+---------------+
1231  28| 0x31 ('1')    |
1232    +---------------+
1233    Total 29 bytes (24 byte header, 5 byte body)
1234
1235Field        (offset) (value)
1236Magic        (0)    : 0x81
1237Opcode       (1)    : 0x0b
1238Key length   (2,3)  : 0x0000
1239Extra length (4)    : 0x00
1240Data type    (5)    : 0x00
1241Status       (6,7)  : 0x0000
1242Total body   (8-11) : 0x00000005
1243Opaque       (12-15): 0x00000000
1244CAS          (16-23): 0x0000000000000000
1245Extras              : None
1246Key                 : None
1247Value               : Textual string "1.3.1"
1248            </artwork>
1249          </figure>
1250        </section>
1251      </section>
1252
1253      <section anchor="command-append" title="Append, Prepend">
1254        <t>
1255        <list style="empty">
1256          <t>MUST NOT have extras.</t>
1257          <t>MUST have key.</t>
1258          <t>MUST have value.</t>
1259        </list>
1260        </t>
1261
1262        <t>
1263          These commands will either append or prepend the specified
1264          value to the requested key.
1265        </t>
1266
1267        <section anchor="command-append-example" title="Example">
1268          <t>The following example appends '!' to the 'Hello' key.</t>
1269          <figure>
1270            <preamble>Append request:</preamble>
1271            <artwork>
1272  Byte/     0       |       1       |       2       |       3       |
1273     /              |               |               |               |
1274    |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|
1275    +---------------+---------------+---------------+---------------+
1276   0| 0x80          | 0x0e          | 0x00          | 0x05          |
1277    +---------------+---------------+---------------+---------------+
1278   4| 0x00          | 0x00          | 0x00          | 0x00          |
1279    +---------------+---------------+---------------+---------------+
1280   8| 0x00          | 0x00          | 0x00          | 0x06          |
1281    +---------------+---------------+---------------+---------------+
1282  12| 0x00          | 0x00          | 0x00          | 0x00          |
1283    +---------------+---------------+---------------+---------------+
1284  16| 0x00          | 0x00          | 0x00          | 0x00          |
1285    +---------------+---------------+---------------+---------------+
1286  20| 0x00          | 0x00          | 0x00          | 0x00          |
1287    +---------------+---------------+---------------+---------------+
1288  24| 0x48 ('H')    | 0x65 ('e')    | 0x6c ('l')    | 0x6c ('l')    |
1289    +---------------+---------------+---------------+---------------+
1290  28| 0x6f ('o')    | 0x21 ('!')    |
1291    +---------------+---------------+
1292    Total 30 bytes (24 byte header, 5 byte key, 1 byte value)
1293
1294Field        (offset) (value)
1295Magic        (0)    : 0x80
1296Opcode       (1)    : 0x0e
1297Key length   (2,3)  : 0x0005
1298Extra length (4)    : 0x00
1299Data type    (5)    : 0x00
1300Reserved     (6,7)  : 0x0000
1301Total body   (8-11) : 0x00000006
1302Opaque       (12-15): 0x00000000
1303CAS          (16-23): 0x0000000000000000
1304Extras              : None
1305Key          (24-28): The textual string "Hello"
1306Value        (29)   : "!"
1307            </artwork>
1308          </figure>
1309          <t>
1310            The response-packet contains no extra data, and the result of the
1311            operation is signaled through the status code.
1312          </t>
1313        </section>
1314      </section>
1315
1316      <section anchor="command-stat" title="Stat">
1317        <t>
1318        <list style="empty">
1319          <t>MUST NOT have extras.</t>
1320          <t>MAY have key.</t>
1321          <t>MUST NOT have value.</t>
1322        </list>
1323        </t>
1324
1325        <t>
1326	  Request server statistics. Without a key specified the server will
1327          respond with a "default" set of statistics information. Each piece
1328          of statistical information is returned in its own packet (key
1329          contains the name of the statistical item and the body contains the
1330          value in ASCII format). The sequence of return packets is terminated
1331          with a packet that contains no key and no value.
1332        </t>
1333        <section anchor="command-stat-example" title="Example">
1334            <t>The following example requests all statistics from the server</t>
1335          <figure>
1336            <preamble>Stat request:</preamble>
1337            <artwork>
1338  Byte/     0       |       1       |       2       |       3       |
1339     /              |               |               |               |
1340    |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|
1341    +---------------+---------------+---------------+---------------+
1342   0| 0x80          | 0x10          | 0x00          | 0x00          |
1343    +---------------+---------------+---------------+---------------+
1344   4| 0x00          | 0x00          | 0x00          | 0x00          |
1345    +---------------+---------------+---------------+---------------+
1346   8| 0x00          | 0x00          | 0x00          | 0x00          |
1347    +---------------+---------------+---------------+---------------+
1348  12| 0x00          | 0x00          | 0x00          | 0x00          |
1349    +---------------+---------------+---------------+---------------+
1350  16| 0x00          | 0x00          | 0x00          | 0x00          |
1351    +---------------+---------------+---------------+---------------+
1352  20| 0x00          | 0x00          | 0x00          | 0x00          |
1353    +---------------+---------------+---------------+---------------+
1354    Total 24 bytes
1355
1356Field        (offset) (value)
1357Magic        (0)    : 0x80
1358Opcode       (1)    : 0x10
1359Key length   (2,3)  : 0x0000
1360Extra length (4)    : 0x00
1361Data type    (5)    : 0x00
1362Reserved     (6,7)  : 0x0000
1363Total body   (8-11) : 0x00000000
1364Opaque       (12-15): 0x00000000
1365CAS          (16-23): 0x0000000000000000
1366Extras              : None
1367Key                 : None
1368Value               : None
1369            </artwork>
1370          </figure>
1371          <t>
1372              The server will send each value in a separate packet with
1373              an "empty" packet (no key / no value) to terminate the sequence.
1374              Each of the response packets look like the following example:
1375         </t>
1376          <figure>
1377            <preamble>Stat response:</preamble>
1378            <artwork>
1379  Byte/     0       |       1       |       2       |       3       |
1380     /              |               |               |               |
1381    |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|
1382    +---------------+---------------+---------------+---------------+
1383   0| 0x81          | 0x10          | 0x00          | 0x03          |
1384    +---------------+---------------+---------------+---------------+
1385   4| 0x00          | 0x00          | 0x00          | 0x00          |
1386    +---------------+---------------+---------------+---------------+
1387   8| 0x00          | 0x00          | 0x00          | 0x07          |
1388    +---------------+---------------+---------------+---------------+
1389  12| 0x00          | 0x00          | 0x00          | 0x00          |
1390    +---------------+---------------+---------------+---------------+
1391  16| 0x00          | 0x00          | 0x00          | 0x00          |
1392    +---------------+---------------+---------------+---------------+
1393  20| 0x00          | 0x00          | 0x00          | 0x00          |
1394    +---------------+---------------+---------------+---------------+
1395  24| 0x70 ('p')    | 0x69 ('i')    | 0x64 ('d')    | 0x33 ('3')    |
1396    +---------------+---------------+---------------+---------------+
1397  28| 0x30 ('0')    | 0x37 ('7')    | 0x38 ('8')    |
1398    +---------------+---------------+---------------+
1399    Total 31 bytes (24 byte header, 3 byte key, 4 byte body)
1400
1401Field        (offset) (value)
1402Magic        (0)    : 0x81
1403Opcode       (1)    : 0x10
1404Key length   (2,3)  : 0x0003
1405Extra length (4)    : 0x00
1406Data type    (5)    : 0x00
1407Status       (6,7)  : 0x0000
1408Total body   (8-11) : 0x00000007
1409Opaque       (12-15): 0x00000000
1410CAS          (16-23): 0x0000000000000000
1411Exstras             : None
1412Key                 : The textual string "pid"
1413Value               : The textual string "3078"
1414            </artwork>
1415          </figure>
1416        </section>
1417      </section>
1418    </section>
1419    <section anchor="security" title="Security Considerations">
1420      <t>
1421      Memcache has no authentication or security layers whatsoever. It is
1422      RECOMMENDED that memcache be deployed strictly on closed, protected,
1423      back-end networks within a single data center, within a single cluster of
1424      servers, or even on a single host, providing shared caching for multiple
1425      applications. Memcache MUST NOT be made available on a public network.
1426      </t>
1427    </section>
1428
1429  </middle>
1430
1431  <back>
1432    <references title="Normative References">
1433      <reference anchor="LJ">
1434        <front>
1435          <title>LJ NEEDS MOAR SPEED</title>
1436          <author fullname="Brad Fitzpatrick">
1437            <organization>Danga Interactive</organization>
1438          </author>
1439          <date day="5" month="10" year="1999" />
1440          <abstract>
1441            <t>http://www.livejournal.com/</t>
1442          </abstract>
1443        </front>
1444      </reference>
1445      <dwdrfc-ref anchor="KEYWORDS" src='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'/>
1446    </references>
1447
1448    <section anchor="acknowledgments" title="Acknowledgments">
1449      <t>
1450      Thanks to Brad Fitzpatrick, Anatoly Vorobey, Steven Grimm, and Dustin
1451      Sallings, for their work on the memcached server.
1452      </t>
1453
1454      <t>
1455      Thanks to Sean Chittenden, Jonathan Steinert, Brian Aker, Evan Martin,
1456      Nathan Neulinger, Eric Hodel, Michael Johnson, Paul Querna, Jamie
1457      McCarthy, Philip Neustrom, Andrew O'Brien, Josh Rotenberg, Robin H.
1458      Johnson, Tim Yardley, Paolo Borelli, Eli Bingham, Jean-Francois
1459      Bustarret, Paul G, Paul Lindner, Alan Kasindorf, Chris Goffinet, Tomash
1460      Brechko, and others for their work reporting bugs and maintaining
1461      memcached client libraries and bindings in many languages.
1462      </t>
1463    </section>
1464  </back>
1465
1466</rfc>
1467
1468