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