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