+++ /dev/null
-<?xml version="1.0" encoding="US-ASCII"?>
-<!DOCTYPE rfc SYSTEM "xml2rfc/rfc2629.dtd">
-<?xml-stylesheet type='text/xsl' href='xml2rfc/rfc2629.xslt'?>
-<?rfc toc="yes"?>
-<?rfc strict="yes"?>
-<?rfc symrefs="yes"?>
-<?rfc sortrefs="yes" ?>
-<?rfc compact="yes" ?>
-<?rfc subcompact="yes" ?>
-<rfc category="info" docName="draft-stone-memcache-binary-01" ipr="none">
- <front>
- <title> Memcache Binary Protocol </title>
-
- <author fullname="Aaron Stone" surname="Stone" role="editor">
- <organization>Six Apart, Ltd.</organization>
- <address>
- <postal>
- <street>548 4th Street</street>
- <city>San Francisco</city>
- <region>CA</region>
- <code>94107</code>
- <country>USA</country>
- </postal>
- <email>aaron@serendipity.palo-alto.ca.us</email>
- </address>
- </author>
- <author fullname="Trond Norbye" surname="Norbye" role="editor">
- <organization>Sun Microsystems, INC</organization>
- <address>
- <postal>
- <street>Haakon VII g. 7B</street>
- <city>Trondheim</city>
- <code>NO-7485 Trondheim</code>
- <country>Norway</country>
- </postal>
- <email>trond.norbye@sun.com</email>
- </address>
- </author>
- <date day="28" month="August" year="2008" />
- <area>Applications</area>
- <keyword>memcache memcached cache</keyword>
- <abstract>
- <t>
- This memo explains the memcache binary protocol for informational
- purposes.
- </t>
- <t>
- Memcache is a high performance key-value cache. It is intentionally a
- dumb cache, optimized for speed only. Applications using memcache do
- not rely on it for data -- a persistent database with guaranteed
- reliability is strongly recommended -- but applications can run much
- faster when cached data is available in memcache.
- </t>
- </abstract>
- </front>
-
- <middle>
- <section anchor="introduction" title="Introduction">
- <t>
- Memcache is a high performance key-value cache. It is intentionally a
- dumb cache, optimized for speed only. Applications using memcache should
- not rely on it for data -- a persistent database with guaranteed
- reliability is strongly recommended -- but applications can run much
- faster when cached data is available in memcache.
- </t>
- <t>
- Memcache was originally written to make
- <xref target="LJ">LiveJournal</xref> faster. It now powers all of
- the fastest web sites that you love.
- </t>
- <section anchor="conventions" title="Conventions Used In This Document">
- <t>
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
- document are to be interpreted as described in
- <xref target="KEYWORDS"/>.
- </t>
- </section>
- </section>
-
- <section anchor="packet" title="Packet Structure">
- <figure>
- <preamble>General format of a packet:</preamble>
- <artwork>
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0/ HEADER /
- / /
- / /
- / /
- +---------------+---------------+---------------+---------------+
- 24/ COMMAND-SPECIFIC EXTRAS (as needed) /
- +/ (note length in the extras length header field) /
- +---------------+---------------+---------------+---------------+
- m/ Key (as needed) /
- +/ (note length in key length header field) /
- +---------------+---------------+---------------+---------------+
- n/ Value (as needed) /
- +/ (note length is total body length header field, minus /
- +/ sum of the extras and key length body fields) /
- +---------------+---------------+---------------+---------------+
- Total 24 bytes
- </artwork>
- </figure>
-
- <figure>
- <preamble>Request header:</preamble>
- <artwork>
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0| Magic | Opcode | Key length |
- +---------------+---------------+---------------+---------------+
- 4| Extras length | Data type | Reserved |
- +---------------+---------------+---------------+---------------+
- 8| Total body length |
- +---------------+---------------+---------------+---------------+
- 12| Opaque |
- +---------------+---------------+---------------+---------------+
- 16| CAS |
- | |
- +---------------+---------------+---------------+---------------+
- Total 24 bytes
- </artwork>
- </figure>
-
- <figure>
- <preamble>Response header:</preamble>
- <artwork>
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0| Magic | Opcode | Key Length |
- +---------------+---------------+---------------+---------------+
- 4| Extras length | Data type | Status |
- +---------------+---------------+---------------+---------------+
- 8| Total body length |
- +---------------+---------------+---------------+---------------+
- 12| Opaque |
- +---------------+---------------+---------------+---------------+
- 16| CAS |
- | |
- +---------------+---------------+---------------+---------------+
- Total 24 bytes
- </artwork>
- </figure>
-
- <t>
- Header fields:
- <list hangIndent="20" style="hanging">
- <t hangText="Magic">Magic number.</t>
- <t hangText="Opcode">Command code.</t>
- <t hangText="Key length">Length in bytes of the text key that follows the command extras.</t>
- <t hangText="Status">Status of the response (non-zero on error).</t>
- <t hangText="Extras length">Length in bytes of the command extras.</t>
- <t hangText="Data type">Reserved for future use (Sean is using this soon).</t>
- <t hangText="Reserved">Really reserved for future use (up for grabs).</t>
- <t hangText="Total body length">Length in bytes of extra + key + value.</t>
- <t hangText="Opaque">Will be copied back to you in the response.</t>
- <t hangText="CAS">Data version check.</t>
- </list>
- </t>
- </section>
-
- <section anchor="values" title="Defined Values">
- <section anchor="value-magic" title="Magic Byte">
- <t>
- <list hangIndent="8" style="hanging">
- <t hangText="0x80">Request packet for this protocol version</t>
- <t hangText="0x81">Response packet for this protocol version</t>
- </list>
- </t>
-
- <t>
- Magic byte / version. For each version of the protocol, we'll use a
- different request/response value pair. This is useful for protocol
- analyzers to distinguish the nature of the packet from the direction
- which it is moving. Note, it is common to run a memcached instance on
- a host that also runs an application server. Such a host will both
- send and receive memcache packets.
- </t>
-
- <t>
- The version should hopefully correspond only to different meanings of
- the command byte. In an ideal world, we will not change the header
- format. As reserved bytes are given defined meaning, the protocol
- version / magic byte values should be incremented.
- </t>
-
- <t>
- Traffic analysis tools are encouraged to identify memcache packets
- and provide detailed interpretation if the magic bytes are recognized
- and otherwise to provide a generic breakdown of the packet. Note, that
- the key and value positions can always be identified even if the magic
- byte or command opcode are not recognized.
- </t>
- </section>
-
- <section anchor="value-status" title="Response Status">
- <t>
- Possible values of this two-byte field:
- <list hangIndent="8" style="hanging">
- <t hangText="0x0000">No error</t>
- <t hangText="0x0001">Key not found</t>
- <t hangText="0x0002">Key exists</t>
- <t hangText="0x0003">Value too large</t>
- <t hangText="0x0004">Invalid arguments</t>
- <t hangText="0x0005">Item not stored</t>
- <t hangText="0x0006">Incr/Decr on non-numeric value.</t>
- <t hangText="0x0081">Unknown command</t>
- <t hangText="0x0082">Out of memory</t>
- </list>
- </t>
- </section>
-
- <section anchor="value-opcodes" title="Command Opcodes">
- <t>
- Possible values of the one-byte field:
- <list hangIndent="8" style="hanging">
- <t hangText="0x00">Get</t>
- <t hangText="0x01">Set</t>
- <t hangText="0x02">Add</t>
- <t hangText="0x03">Replace</t>
- <t hangText="0x04">Delete</t>
- <t hangText="0x05">Increment</t>
- <t hangText="0x06">Decrement</t>
- <t hangText="0x07">Quit</t>
- <t hangText="0x08">Flush</t>
- <t hangText="0x09">GetQ</t>
- <t hangText="0x0A">No-op</t>
- <t hangText="0x0B">Version</t>
- <t hangText="0x0C">GetK</t>
- <t hangText="0x0D">GetKQ</t>
- <t hangText="0x0E">Append</t>
- <t hangText="0x0F">Prepend</t>
- <t hangText="0x10">Stat</t>
- <t hangText="0x11">SetQ</t>
- <t hangText="0x12">AddQ</t>
- <t hangText="0x13">ReplaceQ</t>
- <t hangText="0x14">DeleteQ</t>
- <t hangText="0x15">IncrementQ</t>
- <t hangText="0x16">DecrementQ</t>
- <t hangText="0x17">QuitQ</t>
- <t hangText="0x18">FlushQ</t>
- <t hangText="0x19">AppendQ</t>
- <t hangText="0x1A">PrependQ</t>
- </list>
- </t>
- <t>
- As a convention all of the commands ending with "Q" for
- Quiet. A quiet version of a command will omit responses
- that are considered uninteresting. Whether a given response
- is interesting is dependent upon the command. See the
- descriptions of the
- <xref target="command-get">set commands</xref>
- and <xref target="command-set">set commands</xref> for
- examples of commands that include quiet variants.
- </t>
- </section>
-
- <section anchor="value-types" title="Data Types">
- <t>
- Possible values of the one-byte field:
- <list hangIndent="8" style="hanging">
- <t hangText="0x00">Raw bytes</t>
- </list>
- </t>
- </section>
- </section>
-
- <section title="Commands">
- <section anchor="command-introduction" title="Introduction">
- <t>
- All communication is initiated by a request from the client,
- and the server will respond to each request with zero or
- multiple packets for each request. If the status code of a response
- packet is non-nil, the body of the packet will contain a textual error
- message. If the status code is nil, the command opcode will define the
- layout of the body of the message.
- </t>
- <section anchor="command-introduction-example" title="Example">
- <t>
- The following figure illustrates the packet layout for
- a packet with an error message.
- </t>
- <figure>
- <preamble>Packet layout:</preamble>
- <artwork>
-
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0| 0x81 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 4| 0x00 | 0x00 | 0x00 | 0x01 |
- +---------------+---------------+---------------+---------------+
- 8| 0x00 | 0x00 | 0x00 | 0x09 |
- +---------------+---------------+---------------+---------------+
- 12| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 16| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 20| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 24| 0x4e ('N') | 0x6f ('o') | 0x74 ('t') | 0x20 (' ') |
- +---------------+---------------+---------------+---------------+
- 28| 0x66 ('f') | 0x6f ('o') | 0x75 ('u') | 0x6e ('n') |
- +---------------+---------------+---------------+---------------+
- 32| 0x64 ('d') |
- +---------------+
- Total 33 bytes (24 byte header, and 9 bytes value)
-
-Field (offset) (value)
-Magic (0) : 0x81
-Opcode (1) : 0x00
-Key length (2,3) : 0x0000
-Extra length (4) : 0x00
-Data type (5) : 0x00
-Status (6,7) : 0x0001
-Total body (8-11) : 0x00000009
-Opaque (12-15): 0x00000000
-CAS (16-23): 0x0000000000000000
-Extras : None
-Key : None
-Value (24-32): The textual string "Not found"
- </artwork>
- </figure>
- </section>
- </section>
-
- <section anchor="command-get" title="Get, Get Quietly, Get Key, Get Key Quietly">
- <t>
- Request:
- </t>
- <t>
- <list style="empty">
- <t>MUST NOT have extras.</t>
- <t>MUST have key.</t>
- <t>MUST NOT have value.</t>
- </list>
- </t>
-
- <t>
- Response (if found):
- </t>
- <t>
- <list style="empty">
- <t>MUST have extras.</t>
- <t>MAY have key.</t>
- <t>MAY have value.</t>
- </list>
- </t>
-
- <t>
- <list style="symbols">
- <t>4 byte flags</t>
- </list>
- </t>
-
- <t>
- <figure>
- <preamble>Extra data for the get commands:</preamble>
- <artwork>
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0| Flags |
- +---------------+---------------+---------------+---------------+
-
- Total 4 bytes
- </artwork>
- </figure>
- </t>
-
- <t>
- The get command gets a single key. The getq command is both mum
- on cache miss and quiet, holding its response until a non-quiet
- command is issued. Getk and getkq differs from get and getq by
- adding the key into the response packet.
- </t>
-
- <t>
- You're not guaranteed a response to a getq/getkq cache hit until
- you send a non-getq/getkq command later, which uncorks the
- server and bundles up IOs to send to the client in one go.
- </t>
-
- <t>
- Clients should implement multi-get (still important for
- reducing network roundtrips!) as n pipelined requests, the
- first n-1 being getq/getkq, the last being a regular
- get/getk. That way you're guaranteed to get a response, and
- you know when the server's done. You can also do the naive
- thing and send n pipelined get/getks, but then you could potentially
- get back a lot of "NOT_FOUND" error code packets.
- Alternatively, you can send 'n' getq/getkqs, followed by a
- 'noop' command.
- </t>
-
- <section anchor="command-get-example" title="Example">
- <t>
- To request the data associated with the key "Hello" the
- following fields must be specified in the packet.
- </t>
- <figure>
- <preamble>get request:</preamble>
- <artwork>
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0| 0x80 | 0x00 | 0x00 | 0x05 |
- +---------------+---------------+---------------+---------------+
- 4| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 8| 0x00 | 0x00 | 0x00 | 0x05 |
- +---------------+---------------+---------------+---------------+
- 12| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 16| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 20| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') |
- +---------------+---------------+---------------+---------------+
- 28| 0x6f ('o') |
- +---------------+
-
- Total 29 bytes (24 byte header, and 5 bytes key)
-
-Field (offset) (value)
-Magic (0) : 0x80
-Opcode (1) : 0x00
-Key length (2,3) : 0x0005
-Extra length (4) : 0x00
-Data type (5) : 0x00
-Reserved (6,7) : 0x0000
-Total body (8-11) : 0x00000005
-Opaque (12-15): 0x00000000
-CAS (16-23): 0x0000000000000000
-Extras : None
-Key (24-29): The textual string: "Hello"
-Value : None
- </artwork>
- </figure>
- <t>If the item exist on the server the following packet is returned,
- otherwise a packet with status code != 0 will be returned (see
- <xref target="command-introduction">Introduction</xref>)
- </t>
- <figure>
- <preamble>get/getq response:</preamble>
- <artwork>
-
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0| 0x81 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 4| 0x04 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 8| 0x00 | 0x00 | 0x00 | 0x09 |
- +---------------+---------------+---------------+---------------+
- 12| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 16| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 20| 0x00 | 0x00 | 0x00 | 0x01 |
- +---------------+---------------+---------------+---------------+
- 24| 0xde | 0xad | 0xbe | 0xef |
- +---------------+---------------+---------------+---------------+
- 28| 0x57 ('W') | 0x6f ('o') | 0x72 ('r') | 0x6c ('l') |
- +---------------+---------------+---------------+---------------+
- 32| 0x64 ('d') |
- +---------------+
-
- Total 33 bytes (24 byte header, 4 byte extras and 5 byte value)
-
-Field (offset) (value)
-Magic (0) : 0x81
-Opcode (1) : 0x00
-Key length (2,3) : 0x0000
-Extra length (4) : 0x04
-Data type (5) : 0x00
-Status (6,7) : 0x0000
-Total body (8-11) : 0x00000009
-Opaque (12-15): 0x00000000
-CAS (16-23): 0x0000000000000001
-Extras :
- Flags (24-27): 0xdeadbeef
-Key : None
-Value (28-32): The textual string "World"
- </artwork>
- </figure>
- <figure>
- <preamble>getk/getkq response:</preamble>
- <artwork>
-
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0| 0x81 | 0x00 | 0x00 | 0x05 |
- +---------------+---------------+---------------+---------------+
- 4| 0x04 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 8| 0x00 | 0x00 | 0x00 | 0x09 |
- +---------------+---------------+---------------+---------------+
- 12| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 16| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 20| 0x00 | 0x00 | 0x00 | 0x01 |
- +---------------+---------------+---------------+---------------+
- 24| 0xde | 0xad | 0xbe | 0xef |
- +---------------+---------------+---------------+---------------+
- 28| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') |
- +---------------+---------------+---------------+---------------+
- 32| 0x6f ('o') | 0x57 ('W') | 0x6f ('o') | 0x72 ('r') |
- +---------------+---------------+---------------+---------------+
- 36| 0x6c ('l') | 0x64 ('d') |
- +---------------+---------------+
-
- Total 38 bytes (24 byte header, 4 byte extras, 5 byte key
- and 5 byte value)
-
-Field (offset) (value)
-Magic (0) : 0x81
-Opcode (1) : 0x00
-Key length (2,3) : 0x0005
-Extra length (4) : 0x04
-Data type (5) : 0x00
-Status (6,7) : 0x0000
-Total body (8-11) : 0x00000009
-Opaque (12-15): 0x00000000
-CAS (16-23): 0x0000000000000001
-Extras :
- Flags (24-27): 0xdeadbeef
-Key (28-32): The textual string: "Hello"
-Value (33-37): The textual string: "World"
- </artwork>
- </figure>
- </section>
- </section>
-
- <section anchor="command-set" title="Set, Add, Replace">
- <t>
- <list style="empty">
- <t>MUST have extras.</t>
- <t>MUST have key.</t>
- <t>MUST have value.</t>
- </list>
- </t>
-
- <t>
- <list style="symbols">
- <t>4 byte flags</t>
- <t>4 byte expiration time</t>
- </list>
- </t>
-
- <figure>
- <preamble>Extra data for set/add/replace:</preamble>
- <artwork>
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0| Flags |
- +---------------+---------------+---------------+---------------+
- 4| Expiration |
- +---------------+---------------+---------------+---------------+
- Total 8 bytes
- </artwork>
- </figure>
-
- <t>
- If the Data Version Check (CAS) is nonzero, the requested
- operation MUST only succeed if the item exists and has a CAS value
- identical to the provided value.
- </t>
-
- <t>
- Add MUST fail if the item already exist.
- </t>
-
- <t>
- Replace MUST fail if the item doesn't exist.
- </t>
-
- <t>
- Set should store the data unconditionally if the item exists
- or not.
- </t>
-
- <t>
- Quiet mutations only return responses on failure. Success
- is considered the general case and is suppressed when in
- quiet mode, but errors should not be allowed to go
- unnoticed.
- </t>
-
- <section anchor="command-set-example" title="Example">
- <t>The following figure shows an add-command for
- <list style="empty">
- <t>Key: "Hello"</t>
- <t>Value: "World"</t>
- <t>Flags: 0xdeadbeef</t>
- <t>Expiry: in two hours</t>
- </list>
- </t>
- <figure>
- <preamble>Add request:</preamble>
- <artwork>
-
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0| 0x80 | 0x02 | 0x00 | 0x05 |
- +---------------+---------------+---------------+---------------+
- 4| 0x08 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 8| 0x00 | 0x00 | 0x00 | 0x12 |
- +---------------+---------------+---------------+---------------+
- 12| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 16| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 20| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 24| 0xde | 0xad | 0xbe | 0xef |
- +---------------+---------------+---------------+---------------+
- 28| 0x00 | 0x00 | 0x0e | 0x10 |
- +---------------+---------------+---------------+---------------+
- 32| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') |
- +---------------+---------------+---------------+---------------+
- 36| 0x6f ('o') | 0x57 ('W') | 0x6f ('o') | 0x72 ('r') |
- +---------------+---------------+---------------+---------------+
- 40| 0x6c ('l') | 0x64 ('d') |
- +---------------+---------------+
-
- Total 42 bytes (24 byte header, 8 byte extras, 5 byte key and
- 5 byte value)
-
-Field (offset) (value)
-Magic (0) : 0x80
-Opcode (1) : 0x02
-Key length (2,3) : 0x0005
-Extra length (4) : 0x08
-Data type (5) : 0x00
-Reserved (6,7) : 0x0000
-Total body (8-11) : 0x00000012
-Opaque (12-15): 0x00000000
-CAS (16-23): 0x0000000000000000
-Extras :
- Flags (24-27): 0xdeadbeef
- Expiry (28-31): 0x00000e10
-Key (32-36): The textual string "Hello"
-Value (37-41): The textual string "World"
- </artwork>
- </figure>
- <t>
- The response-packet contains no extra data, and the result of the
- operation is signaled through the status code. If the command
- succeeds, the CAS value for the item is returned in the CAS-field
- of the packet.
- </t>
- <figure>
- <preamble>Successful add response:</preamble>
- <artwork>
-
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0| 0x81 | 0x02 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 4| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 8| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 12| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 16| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 20| 0x00 | 0x00 | 0x00 | 0x01 |
- +---------------+---------------+---------------+---------------+
-
- Total 24 bytes
-
-Field (offset) (value)
-Magic (0) : 0x81
-Opcode (1) : 0x02
-Key length (2,3) : 0x0000
-Extra length (4) : 0x00
-Data type (5) : 0x00
-Status (6,7) : 0x0000
-Total body (8-11) : 0x00000000
-Opaque (12-15): 0x00000000
-CAS (16-23): 0x0000000000000001
-Extras : None
-Key : None
-Value : None
- </artwork>
- </figure>
- </section>
- </section>
-
- <section anchor="command-delete" title="Delete">
- <t>
- <list style="empty">
- <t>MUST NOT have extras.</t>
- <t>MUST have key.</t>
- <t>MUST NOT have value.</t>
- </list>
- </t>
-
- <t>
- Delete the item with the specific key.
- </t>
-
- <section anchor="command-delete-example" title="Example">
- <t>The following figure shows a delete message for the
- item "Hello".</t>
- <figure>
- <preamble>Delete request:</preamble>
- <artwork>
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0| 0x80 | 0x04 | 0x00 | 0x05 |
- +---------------+---------------+---------------+---------------+
- 4| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 8| 0x00 | 0x00 | 0x00 | 0x05 |
- +---------------+---------------+---------------+---------------+
- 12| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 16| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 20| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') |
- +---------------+---------------+---------------+---------------+
- 28| 0x6f ('o') |
- +---------------+
-
- Total 29 bytes (24 byte header, 5 byte value)
-
-Field (offset) (value)
-Magic (0) : 0x80
-Opcode (1) : 0x04
-Key length (2,3) : 0x0005
-Extra length (4) : 0x00
-Data type (5) : 0x00
-Reserved (6,7) : 0x0000
-Total body (8-11) : 0x00000005
-Opaque (12-15): 0x00000000
-CAS (16-23): 0x0000000000000000
-Extras : None
-Key : The textual string "Hello"
-Value : None
- </artwork>
- </figure>
- <t>
- The response-packet contains no extra data, and the result of the
- operation is signaled through the status code.
- </t>
- </section>
- </section>
-
- <section anchor="command-incr" title="Increment, Decrement">
- <t>
- <list style="empty">
- <t>MUST have extras.</t>
- <t>MUST have key.</t>
- <t>MUST NOT have value.</t>
- </list>
- </t>
-
- <t>
- <list style="symbols">
- <t>8 byte value to add / subtract</t>
- <t>8 byte initial value (unsigned)</t>
- <t>4 byte expiration time</t>
- </list>
- </t>
- <figure>
- <preamble>Extra data for incr/decr:</preamble>
- <artwork>
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0| Amount to add |
- | |
- +---------------+---------------+---------------+---------------+
- 8| Initial value |
- | |
- +---------------+---------------+---------------+---------------+
- 16| Expiration |
- +---------------+---------------+---------------+---------------+
- Total 20 bytes
- </artwork>
- </figure>
-
- <t>
- These commands will either add or remove the specified
- amount to the requested counter.
- </t>
- <t>
- If the counter does not exist, one of two things may happen:
- </t>
- <t>
- <list style="numbers">
- <t>If the expiration value is all one-bits (0xffffffff), the
- operation will fail with NOT_FOUND.</t>
- <t>For all other expiration values, the operation will succeed
- by seeding the value for this key with the provided initial
- value to expire with the provided expiration time. The flags
- will be set to zero.</t>
- </list>
- </t>
- <figure>
- <preamble>incr/decr response body:</preamble>
- <artwork>
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0| 64-bit unsigned response. |
- | |
- +---------------+---------------+---------------+---------------+
- Total 8 bytes
- </artwork>
- </figure>
- <section anchor="command-incr-example" title="Example">
- <t>The following figure shows an incr-command for
- <list style="empty">
- <t>Key: "counter"</t>
- <t>Delta: 0x01</t>
- <t>Initial: 0x00</t>
- <t>Expiry: in two hours</t>
- </list>
- </t>
- <figure>
- <preamble>Increment request:</preamble>
- <artwork>
-
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0| 0x80 | 0x05 | 0x00 | 0x07 |
- +---------------+---------------+---------------+---------------+
- 4| 0x14 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 8| 0x00 | 0x00 | 0x00 | 0x1b |
- +---------------+---------------+---------------+---------------+
- 12| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 16| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 20| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 24| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 28| 0x00 | 0x00 | 0x00 | 0x01 |
- +---------------+---------------+---------------+---------------+
- 32| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 36| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 40| 0x00 | 0x00 | 0x0e | 0x10 |
- +---------------+---------------+---------------+---------------+
- 44| 0x63 ('c') | 0x6f ('o') | 0x75 ('u') | 0x6e ('n') |
- +---------------+---------------+---------------+---------------+
- 48| 0x74 ('t') | 0x65 ('e') | 0x72 ('r') |
- +---------------+---------------+---------------+
- Total 51 bytes (24 byte header, 20 byte extras, 7 byte key)
-
-Field (offset) (value)
-Magic (0) : 0x80
-Opcode (1) : 0x05
-Key length (2,3) : 0x0007
-Extra length (4) : 0x14
-Data type (5) : 0x00
-Reserved (6,7) : 0x0000
-Total body (8-11) : 0x0000001b
-Opaque (12-15): 0x00000000
-CAS (16-23): 0x0000000000000000
-Extras :
- delta (24-31): 0x0000000000000001
- initial (32-39): 0x0000000000000000
- exipration (40-43): 0x00000e10
-Key : Textual string "counter"
-Value : None
- </artwork>
- </figure>
- <t>
- If the key doesn't exist, the server will respond with the
- initial value. If not the incremented value will be returned.
- Let's assume that the key didn't exist, so the initial value
- is returned.
- </t>
- <figure>
- <preamble>Increment response:</preamble>
- <artwork>
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0| 0x81 | 0x05 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 4| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 8| 0x00 | 0x00 | 0x00 | 0x08 |
- +---------------+---------------+---------------+---------------+
- 12| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 16| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 20| 0x00 | 0x00 | 0x00 | 0x05 |
- +---------------+---------------+---------------+---------------+
- 24| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 28| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- Total 32 bytes (24 byte header, 8 byte value)
-
-Field (offset) (value)
-Magic (0) : 0x81
-Opcode (1) : 0x05
-Key length (2,3) : 0x0000
-Extra length (4) : 0x00
-Data type (5) : 0x00
-Status (6,7) : 0x0000
-Total body (8-11) : 0x00000008
-Opaque (12-15): 0x00000000
-CAS (16-23): 0x0000000000000005
-Extras : None
-Key : None
-Value : 0x0000000000000000
- </artwork>
- </figure>
- </section>
- </section>
-
- <section anchor="command-quit" title="quit">
- <t>
- <list style="empty">
- <t>MUST NOT have extras.</t>
- <t>MUST NOT have key.</t>
- <t>MUST NOT have value.</t>
- </list>
- </t>
-
- <t>
- Close the connection to the server.
- </t>
-
- <section anchor="command-quit-example" title="Example">
- <figure>
- <preamble>Quit request:</preamble>
- <artwork>
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0| 0x80 | 0x07 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 4| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 8| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 12| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 16| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 20| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- Total 24 bytes
-
-Field (offset) (value)
-Magic (0) : 0x80
-Opcode (1) : 0x07
-Key length (2,3) : 0x0000
-Extra length (4) : 0x00
-Data type (5) : 0x00
-Reserved (6,7) : 0x0000
-Total body (8-11) : 0x00000000
-Opaque (12-15): 0x00000000
-CAS (16-23): 0x0000000000000000
-Extras : None
-Key : None
-Value : None
- </artwork>
- </figure>
- <t>
- The response-packet contains no extra data, and the result of the
- operation is signaled through the status code. The server will
- then close the connection.
- </t>
- </section>
- </section>
-
- <section anchor="command-flush" title="Flush">
- <t>
- <list style="empty">
- <t>MAY have extras.</t>
- <t>MUST NOT have key.</t>
- <t>MUST NOT have value.</t>
- </list>
- </t>
-
- <t>
- <list style="symbols">
- <t>4 byte expiration time</t>
- </list>
- </t>
- <figure>
- <preamble>Extra data for flush:</preamble>
- <artwork>
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0| Expiration |
- +---------------+---------------+---------------+---------------+
- Total 4 bytes
- </artwork>
- </figure>
- <t>
- Flush the items in the cache now or some time in the future as
- specified by the expiration field. See the documentation of the
- textual protocol for the full description on how to specify the
- expiration time.
- </t>
- <section anchor="command-flush-example" title="Example">
- <t>
- To flush the cache (delete all items) in two hours, the set
- the following values in the request
- </t>
- <figure>
- <preamble>Flush request:</preamble>
- <artwork>
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0| 0x80 | 0x08 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 4| 0x04 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 8| 0x00 | 0x00 | 0x00 | 0x04 |
- +---------------+---------------+---------------+---------------+
- 12| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 16| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 20| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 24| 0x00 | 0x00 | 0x0e | 0x10 |
- +---------------+---------------+---------------+---------------+
- Total 28 bytes (24 byte header, 4 byte body)
-
-Field (offset) (value)
-Magic (0) : 0x80
-Opcode (1) : 0x08
-Key length (2,3) : 0x0000
-Extra length (4) : 0x04
-Data type (5) : 0x00
-Reserved (6,7) : 0x0000
-Total body (8-11) : 0x00000004
-Opaque (12-15): 0x00000000
-CAS (16-23): 0x0000000000000000
-Extras :
- Expiry (24-27): 0x000e10
-Key : None
-Value : None
- </artwork>
- </figure>
- <t>
- The response-packet contains no extra data, and the result of the
- operation is signaled through the status code.
- </t>
- </section>
- </section>
- <section anchor="command-noop" title="noop">
- <t>
- <list style="empty">
- <t>MUST NOT have extras.</t>
- <t>MUST NOT have key.</t>
- <t>MUST NOT have value.</t>
- </list>
- </t>
-
- <t>
- Used as a keep alive. Flushes outstanding getq/getkq's.
- </t>
- <section anchor="command-noop-example" title="Example">
- <figure>
- <preamble>Noop request:</preamble>
- <artwork>
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0| 0x80 | 0x0a | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 4| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 8| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 12| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 16| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 20| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- Total 24 bytes
-
-Field (offset) (value)
-Magic (0) : 0x80
-Opcode (1) : 0x0a
-Key length (2,3) : 0x0000
-Extra length (4) : 0x00
-Data type (5) : 0x00
-Reserved (6,7) : 0x0000
-Total body (8-11) : 0x00000000
-Opaque (12-15): 0x00000000
-CAS (16-23): 0x0000000000000000
-Extras : None
-Key : None
-Value : None
- </artwork>
- </figure>
- <t>
- The response-packet contains no extra data, and the result of the
- operation is signaled through the status code.
- </t>
- </section>
- </section>
-
- <section anchor="command-version" title="version">
- <t>
- <list style="empty">
- <t>MUST NOT have extras.</t>
- <t>MUST NOT have key.</t>
- <t>MUST NOT have value.</t>
- </list>
- </t>
-
- <t>
- Request the server version.
- </t>
- <t>
- The server responds with a packet containing the version string
- in the body with the following format: "x.y.z"
- </t>
- <section anchor="command-version-example" title="Example">
- <figure>
- <preamble>Version request:</preamble>
- <artwork>
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0| 0x80 | 0x0b | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 4| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 8| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 12| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 16| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 20| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- Total 24 bytes
-
-Field (offset) (value)
-Magic (0) : 0x80
-Opcode (1) : 0x0b
-Key length (2,3) : 0x0000
-Extra length (4) : 0x00
-Data type (5) : 0x00
-Reserved (6,7) : 0x0000
-Total body (8-11) : 0x00000000
-Opaque (12-15): 0x00000000
-CAS (16-23): 0x0000000000000000
-Extras : None
- </artwork>
- </figure>
- <figure>
- <preamble>Version response:</preamble>
- <artwork>
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0| 0x81 | 0x0b | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 4| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 8| 0x00 | 0x00 | 0x00 | 0x05 |
- +---------------+---------------+---------------+---------------+
- 12| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 16| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 20| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 24| 0x31 ('1') | 0x2e ('.') | 0x33 ('3') | 0x2e ('.') |
- +---------------+---------------+---------------+---------------+
- 28| 0x31 ('1') |
- +---------------+
- Total 29 bytes (24 byte header, 5 byte body)
-
-Field (offset) (value)
-Magic (0) : 0x81
-Opcode (1) : 0x0b
-Key length (2,3) : 0x0000
-Extra length (4) : 0x00
-Data type (5) : 0x00
-Status (6,7) : 0x0000
-Total body (8-11) : 0x00000005
-Opaque (12-15): 0x00000000
-CAS (16-23): 0x0000000000000000
-Extras : None
-Key : None
-Value : Textual string "1.3.1"
- </artwork>
- </figure>
- </section>
- </section>
-
- <section anchor="command-append" title="Append, Prepend">
- <t>
- <list style="empty">
- <t>MUST NOT have extras.</t>
- <t>MUST have key.</t>
- <t>MUST have value.</t>
- </list>
- </t>
-
- <t>
- These commands will either append or prepend the specified
- value to the requested key.
- </t>
-
- <section anchor="command-append-example" title="Example">
- <t>The following example appends '!' to the 'Hello' key.</t>
- <figure>
- <preamble>Append request:</preamble>
- <artwork>
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0| 0x80 | 0x0e | 0x00 | 0x05 |
- +---------------+---------------+---------------+---------------+
- 4| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 8| 0x00 | 0x00 | 0x00 | 0x06 |
- +---------------+---------------+---------------+---------------+
- 12| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 16| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 20| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') |
- +---------------+---------------+---------------+---------------+
- 28| 0x6f ('o') | 0x21 ('!') |
- +---------------+---------------+
- Total 30 bytes (24 byte header, 5 byte key, 1 byte value)
-
-Field (offset) (value)
-Magic (0) : 0x80
-Opcode (1) : 0x0e
-Key length (2,3) : 0x0005
-Extra length (4) : 0x00
-Data type (5) : 0x00
-Reserved (6,7) : 0x0000
-Total body (8-11) : 0x00000006
-Opaque (12-15): 0x00000000
-CAS (16-23): 0x0000000000000000
-Extras : None
-Key (24-28): The textual string "Hello"
-Value (29) : "!"
- </artwork>
- </figure>
- <t>
- The response-packet contains no extra data, and the result of the
- operation is signaled through the status code.
- </t>
- </section>
- </section>
-
- <section anchor="command-stat" title="Stat">
- <t>
- <list style="empty">
- <t>MUST NOT have extras.</t>
- <t>MAY have key.</t>
- <t>MUST NOT have value.</t>
- </list>
- </t>
-
- <t>
- Request server statistics. Without a key specified the server will
- respond with a "default" set of statistics information. Each piece
- of statistical information is returned in its own packet (key
- contains the name of the statistical item and the body contains the
- value in ASCII format). The sequence of return packets is terminated
- with a packet that contains no key and no value.
- </t>
- <section anchor="command-stat-example" title="Example">
- <t>The following example requests all statistics from the server</t>
- <figure>
- <preamble>Stat request:</preamble>
- <artwork>
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0| 0x80 | 0x10 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 4| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 8| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 12| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 16| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 20| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- Total 24 bytes
-
-Field (offset) (value)
-Magic (0) : 0x80
-Opcode (1) : 0x10
-Key length (2,3) : 0x0000
-Extra length (4) : 0x00
-Data type (5) : 0x00
-Reserved (6,7) : 0x0000
-Total body (8-11) : 0x00000000
-Opaque (12-15): 0x00000000
-CAS (16-23): 0x0000000000000000
-Extras : None
-Key : None
-Value : None
- </artwork>
- </figure>
- <t>
- The server will send each value in a separate packet with
- an "empty" packet (no key / no value) to terminate the sequence.
- Each of the response packets look like the following example:
- </t>
- <figure>
- <preamble>Stat response:</preamble>
- <artwork>
- Byte/ 0 | 1 | 2 | 3 |
- / | | | |
- |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
- +---------------+---------------+---------------+---------------+
- 0| 0x81 | 0x10 | 0x00 | 0x03 |
- +---------------+---------------+---------------+---------------+
- 4| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 8| 0x00 | 0x00 | 0x00 | 0x07 |
- +---------------+---------------+---------------+---------------+
- 12| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 16| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 20| 0x00 | 0x00 | 0x00 | 0x00 |
- +---------------+---------------+---------------+---------------+
- 24| 0x70 ('p') | 0x69 ('i') | 0x64 ('d') | 0x33 ('3') |
- +---------------+---------------+---------------+---------------+
- 28| 0x30 ('0') | 0x37 ('7') | 0x38 ('8') |
- +---------------+---------------+---------------+
- Total 31 bytes (24 byte header, 3 byte key, 4 byte body)
-
-Field (offset) (value)
-Magic (0) : 0x81
-Opcode (1) : 0x10
-Key length (2,3) : 0x0003
-Extra length (4) : 0x00
-Data type (5) : 0x00
-Status (6,7) : 0x0000
-Total body (8-11) : 0x00000007
-Opaque (12-15): 0x00000000
-CAS (16-23): 0x0000000000000000
-Exstras : None
-Key : The textual string "pid"
-Value : The textual string "3078"
- </artwork>
- </figure>
- </section>
- </section>
- </section>
- <section anchor="security" title="Security Considerations">
- <t>
- Memcache has no authentication or security layers whatsoever. It is
- RECOMMENDED that memcache be deployed strictly on closed, protected,
- back-end networks within a single data center, within a single cluster of
- servers, or even on a single host, providing shared caching for multiple
- applications. Memcache MUST NOT be made available on a public network.
- </t>
- </section>
-
- </middle>
-
- <back>
- <references title="Normative References">
- <reference anchor="LJ">
- <front>
- <title>LJ NEEDS MOAR SPEED</title>
- <author fullname="Brad Fitzpatrick">
- <organization>Danga Interactive</organization>
- </author>
- <date day="5" month="10" year="1999" />
- <abstract>
- <t>http://www.livejournal.com/</t>
- </abstract>
- </front>
- </reference>
- <dwdrfc-ref anchor="KEYWORDS" src='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'/>
- </references>
-
- <section anchor="acknowledgments" title="Acknowledgments">
- <t>
- Thanks to Brad Fitzpatrick, Anatoly Vorobey, Steven Grimm, and Dustin
- Sallings, for their work on the memcached server.
- </t>
-
- <t>
- Thanks to Sean Chittenden, Jonathan Steinert, Brian Aker, Evan Martin,
- Nathan Neulinger, Eric Hodel, Michael Johnson, Paul Querna, Jamie
- McCarthy, Philip Neustrom, Andrew O'Brien, Josh Rotenberg, Robin H.
- Johnson, Tim Yardley, Paolo Borelli, Eli Bingham, Jean-Francois
- Bustarret, Paul G, Paul Lindner, Alan Kasindorf, Chris Goffinet, Tomash
- Brechko, and others for their work reporting bugs and maintaining
- memcached client libraries and bindings in many languages.
- </t>
- </section>
- </back>
-
-</rfc>
-
projects / awesomized / libmemcached / blobdiff