projects / awesomized / libmemcached / blob
? search:


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