Protocol

--------

Clients of memcached communicate with server through TCP connections.

(A UDP interface is also available; details are below under "UDP

protocol.") A given running memcached server listens on some

(configurable) port; clients connect to that port, send commands to

the server, read responses, and eventually close the connection.

There is no need to send any command to end the session. A client may

just close the connection at any moment it no longer needs it. Note,

however, that clients are encouraged to cache their connections rather

than reopen them every time they need to store or retrieve data. This

is because memcached is especially designed to work very efficiently

with a very large number (many hundreds, more than a thousand if

necessary) of open connections. Caching connections will eliminate the

overhead associated with establishing a TCP connection (the overhead

of preparing for a new connection on the server side is insignificant

compared to this).

There are two kinds of data sent in the memcache protocol: text lines

and unstructured data. Text lines are used for commands from clients

and responses from servers. Unstructured data is sent when a client

wants to store or retrieve data. The server will transmit back

unstructured data in exactly the same way it received it, as a byte

stream. The server doesn't care about byte order issues in

unstructured data and isn't aware of them. There are no limitations on

characters that may appear in unstructured data; however, the reader

of such data (either a client or a server) will always know, from a

preceding text line, the exact length of the data block being

transmitted.

Text lines are always terminated by \r\n. Unstructured data is _also_

terminated by \r\n, even though \r, \n or any other 8-bit characters

may also appear inside the data. Therefore, when a client retrieves

data from a server, it must use the length of the data block (which it

will be provided with) to determine where the data block ends, and not

the fact that \r\n follows the end of the data block, even though it

does.

Keys

----

Data stored by memcached is identified with the help of a key. A key

is a text string which should uniquely identify the data for clients

that are interested in storing and retrieving it. Currently the

length limit of a key is set at 250 characters (of course, normally

clients wouldn't need to use such long keys); the key must not include

control characters or whitespace.

Commands

--------

There are three types of commands.

Storage commands (there are six: "set", "add", "replace", "append"

"prepend" and "cas") ask the server to store some data identified by a

key. The client sends a command line, and then a data block; after

that the client expects one line of response, which will indicate

success or failure.

Retrieval commands ("get", "gets", "gat", and "gats") ask the server to

retrieve data corresponding to a set of keys (one or more keys in one

request). The client sends a command line, which includes all the

requested keys; after that for each item the server finds it sends to

the client one response line with information about the item, and one

data block with the item's data; this continues until the server

finished with the "END" response line.

All other commands don't involve unstructured data. In all of them,

the client sends one command line, and expects (depending on the

command) either one line of response, or several lines of response

ending with "END" on the last line.

A command line always starts with the name of the command, followed by

parameters (if any) delimited by whitespace. Command names are

lower-case and are case-sensitive.

Meta Commands

-------------

Meta commands are a set of new ASCII-based commands. They follow the same

structure of the original commands but have a new flexible feature set.

Meta commands incorporate most features available in the binary protocol, as

well as a flag system to make the commands flexible rather than having a

large number of high level commands. These commands completely replace the

usage of basic Storage and Retrieval commands.

Meta flags are not to be confused with client bitflags, which is an opaque

number passed by the client. Meta flags change how the command operates, but

they are not stored in cache.

These work mixed with normal protocol commands on the same connection. All

existing commands continue to work. The meta commands will not replace

specialized commands that do not sit in the Storage or Retrieval categories

noted in the 'Commands' section above.

All meta commands follow a basic syntax:

<cm> <key> <datalen*> <flag1> <flag2> <...>\r\n

Where <cm> is a 2 character command code.

<datalen> is only for commands with payloads, like set.

Responses look like:

<RC> <datalen*> <flag1> <flag2> <...>\r\n

Where <RC> is a 2 character return code. The number of flags returned are

based off of the flags supplied.

<datalen> is only for responses with payloads, with the return code 'VA'.

Flags are single character codes, ie 'q' or 'k' or 'I', which adjust the

behavior of the command. If a flag requests a response flag (ie 't' for TTL

remaining), it is returned in the same order as they were in the original

command, though this is not strict.

Flags are single character codes, ie 'q' or 'k' or 'O', which adjust the

behavior of a command. Flags may contain token arguments, which come after the

flag and before the next space or newline, ie 'Oopaque' or 'Kuserkey'. Flags

can return new data or reflect information, in the same order they were

supplied in the request. Sending an 't' flag with a get for an item with 20

seconds of TTL remaining, would return 't20' in the response.

All commands accept a tokens 'P' and 'L' which are completely ignored. The

arguments to 'P' and 'L' can be used as hints or path specifications to a

proxy or router inbetween a client and a memcached daemon. For example, a

client may prepend a "path" in the key itself: "mg /path/foo v" or in a proxy

token: "mg foo Lpath/ v" - the proxy may then optionally remove or forward the

token to a memcached daemon, which will ignore them.

Syntax errors are handled the same as noted under 'Error strings' section

below.

For usage examples beyond basic syntax, please see the wiki:

https://github.com/memcached/memcached/wiki/MetaCommands

Expiration times

----------------

Some commands involve a client sending some kind of expiration time

(relative to an item or to an operation requested by the client) to

the server. In all such cases, the actual value sent may either be

Unix time (number of seconds since January 1, 1970, as a 32-bit

value), or a number of seconds starting from current time. In the

latter case, this number of seconds may not exceed 60*60*24*30 (number

of seconds in 30 days); if the number sent by a client is larger than

that, the server will consider it to be real Unix time value rather

than an offset from current time.

Note that a TTL of 1 will sometimes immediately expire. Time is internally

updated on second boundaries, which makes expiration time roughly +/- 1s.

This more proportionally affects very low TTL's.

Error strings

-------------

Each command sent by a client may be answered with an error string

from the server. These error strings come in three types:

- "ERROR\r\n"

means the client sent a nonexistent command name.

- "CLIENT_ERROR <error>\r\n"

means some sort of client error in the input line, i.e. the input

doesn't conform to the protocol in some way. <error> is a

human-readable error string.

- "SERVER_ERROR <error>\r\n"

means some sort of server error prevents the server from carrying

out the command. <error> is a human-readable error string. In cases

of severe server errors, which make it impossible to continue

serving the client (this shouldn't normally happen), the server will

close the connection after sending the error line. This is the only

case in which the server closes a connection to a client.

In the descriptions of individual commands below, these error lines

are not again specifically mentioned, but clients must allow for their

possibility.

Authentication

--------------

Optional username/password token authentication (see -Y option). Used by

sending a fake "set" command with any key:

set <key> <flags> <exptime> <bytes>\r\n

username password\r\n

key, flags, and exptime are ignored for authentication. Bytes is the length

of the username/password payload.

- "STORED\r\n" indicates success. After this point any command should work

normally.

- "CLIENT_ERROR [message]\r\n" will be returned if authentication fails for

any reason.

Storage commands

----------------

First, the client sends a command line which looks like this:

<command name> <key> <flags> <exptime> <bytes> [noreply]\r\n

cas <key> <flags> <exptime> <bytes> <cas unique> [noreply]\r\n

- <command name> is "set", "add", "replace", "append" or "prepend"

"set" means "store this data".

"add" means "store this data, but only if the server *doesn't* already

hold data for this key".

"replace" means "store this data, but only if the server *does*

already hold data for this key".

"append" means "add this data to an existing key after existing data".

"prepend" means "add this data to an existing key before existing data".

The append and prepend commands do not accept flags or exptime.

They update existing data portions, and ignore new flag and exptime

settings.

"cas" is a check and set operation which means "store this data but

only if no one else has updated since I last fetched it."

- <key> is the key under which the client asks to store the data

- <flags> is an arbitrary 16-bit unsigned integer (written out in

decimal) that the server stores along with the data and sends back

when the item is retrieved. Clients may use this as a bit field to

store data-specific information; this field is opaque to the server.

Note that in memcached 1.2.1 and higher, flags may be 32-bits, instead

of 16, but you might want to restrict yourself to 16 bits for

compatibility with older versions.

- <exptime> is expiration time. If it's 0, the item never expires

(although it may be deleted from the cache to make place for other

items). If it's non-zero (either Unix time or offset in seconds from

current time), it is guaranteed that clients will not be able to

retrieve this item after the expiration time arrives (measured by

server time). If a negative value is given the item is immediately

expired.

- <bytes> is the number of bytes in the data block to follow, *not*

including the delimiting \r\n. <bytes> may be zero (in which case

it's followed by an empty data block).

- <cas unique> is a unique 64-bit value of an existing entry.

Clients should use the value returned from the "gets" command

when issuing "cas" updates.

- "noreply" optional parameter instructs the server to not send the

reply. NOTE: if the request line is malformed, the server can't

parse "noreply" option reliably. In this case it may send the error

to the client, and not reading it on the client side will break

things. Client should construct only valid requests.

After this line, the client sends the data block:

<data block>\r\n

- <data block> is a chunk of arbitrary 8-bit data of length <bytes>

from the previous line.

After sending the command line and the data block the client awaits

the reply, which may be:

- "STORED\r\n", to indicate success.

- "NOT_STORED\r\n" to indicate the data was not stored, but not

because of an error. This normally means that the

condition for an "add" or a "replace" command wasn't met.

- "EXISTS\r\n" to indicate that the item you are trying to store with

a "cas" command has been modified since you last fetched it.

- "NOT_FOUND\r\n" to indicate that the item you are trying to store

with a "cas" command did not exist.

Retrieval command:

------------------

The retrieval commands "get" and "gets" operate like this:

get <key>*\r\n

gets <key>*\r\n

- <key>* means one or more key strings separated by whitespace.

After this command, the client expects zero or more items, each of

which is received as a text line followed by a data block. After all

the items have been transmitted, the server sends the string

"END\r\n"

to indicate the end of response.

Each item sent by the server looks like this:

VALUE <key> <flags> <bytes> [<cas unique>]\r\n

<data block>\r\n

- <key> is the key for the item being sent

- <flags> is the flags value set by the storage command

- <bytes> is the length of the data block to follow, *not* including

its delimiting \r\n

- <cas unique> is a unique 64-bit integer that uniquely identifies

this specific item.

- <data block> is the data for this item.

If some of the keys appearing in a retrieval request are not sent back

by the server in the item list this means that the server does not

hold items with such keys (because they were never stored, or stored

but deleted to make space for more items, or expired, or explicitly

deleted by a client).

Deletion

--------

The command "delete" allows for explicit deletion of items:

delete <key> [noreply]\r\n

- <key> is the key of the item the client wishes the server to delete

- "noreply" optional parameter instructs the server to not send the

reply. See the note in Storage commands regarding malformed

requests.

The response line to this command can be one of:

- "DELETED\r\n" to indicate success

- "NOT_FOUND\r\n" to indicate that the item with this key was not

found.

See the "flush_all" command below for immediate invalidation

of all existing items.

Increment/Decrement

-------------------

Commands "incr" and "decr" are used to change data for some item

in-place, incrementing or decrementing it. The data for the item is

treated as decimal representation of a 64-bit unsigned integer. If

the current data value does not conform to such a representation, the

incr/decr commands return an error (memcached <= 1.2.6 treated the

bogus value as if it were 0, leading to confusion). Also, the item

must already exist for incr/decr to work; these commands won't pretend

that a non-existent key exists with value 0; instead, they will fail.

The client sends the command line:

incr <key> <value> [noreply]\r\n

or

decr <key> <value> [noreply]\r\n

- <key> is the key of the item the client wishes to change

- <value> is the amount by which the client wants to increase/decrease

the item. It is a decimal representation of a 64-bit unsigned integer.

- "noreply" optional parameter instructs the server to not send the

reply. See the note in Storage commands regarding malformed

requests.

The response will be one of:

- "NOT_FOUND\r\n" to indicate the item with this value was not found

- <value>\r\n , where <value> is the new value of the item's data,

after the increment/decrement operation was carried out.

Note that underflow in the "decr" command is caught: if a client tries

to decrease the value below 0, the new value will be 0. Overflow in

the "incr" command will wrap around the 64 bit mark.

Note also that decrementing a number such that it loses length isn't

guaranteed to decrement its returned length. The number MAY be

space-padded at the end, but this is purely an implementation

optimization, so you also shouldn't rely on that.

Touch

-----

The "touch" command is used to update the expiration time of an existing item

without fetching it.

touch <key> <exptime> [noreply]\r\n

- <key> is the key of the item the client wishes the server to touch

- <exptime> is expiration time. Works the same as with the update commands

(set/add/etc). This replaces the existing expiration time. If an existing

item were to expire in 10 seconds, but then was touched with an

expiration time of "20", the item would then expire in 20 seconds.

- "noreply" optional parameter instructs the server to not send the

reply. See the note in Storage commands regarding malformed

requests.

The response line to this command can be one of:

- "TOUCHED\r\n" to indicate success

- "NOT_FOUND\r\n" to indicate that the item with this key was not

found.

Get And Touch

-------------

The "gat" and "gats" commands are used to fetch items and update the

expiration time of an existing items.

gat <exptime> <key>*\r\n

gats <exptime> <key>*\r\n

- <exptime> is expiration time.

- <key>* means one or more key strings separated by whitespace.

After this command, the client expects zero or more items, each of

which is received as a text line followed by a data block. After all

the items have been transmitted, the server sends the string

"END\r\n"

to indicate the end of response.

Each item sent by the server looks like this:

VALUE <key> <flags> <bytes> [<cas unique>]\r\n

<data block>\r\n

- <key> is the key for the item being sent

- <flags> is the flags value set by the storage command

- <bytes> is the length of the data block to follow, *not* including

its delimiting \r\n

- <cas unique> is a unique 64-bit integer that uniquely identifies

this specific item.

- <data block> is the data for this item.

Meta Debug

----------

The meta debug command is a human readable dump of all available internal

metadata of an item, minus the value.

me <key> <flag>\r\n

- <key> means one key string.

- if <flag> is 'b', then <key> is a base64 encoded binary value. the response

key will also be base64 encoded.

The response looks like:

ME <key> <k>=<v>*\r\n

A miss looks like:

EN\r\n

Each of the keys and values are the internal data for the item.

exp = expiration time

la = time in seconds since last access

cas = CAS ID

fetch = whether an item has been fetched before

cls = slab class id

size = total size in bytes

Others may be added.

Meta Get

--------

The meta get command is the generic command for retrieving key data from

memcached. Based on the flags supplied, it can replace all of the commands:

"get", "gets", "gat", "gats", "touch", as well as adding new options.

mg <key> <flags>*\r\n

- <key> means one key string. Unlike "get" metaget can only take a single key.

- <flags> are a set of single character codes ended with a space or newline.

flags may have token strings after the initial character.

After this command, the client expects an item to be returned, received as a

text line followed by an optional data block.

If a response line appearing in a retrieval request is not sent back

by the server this means that the server does not

have the item (because it was never stored, or stored

but deleted to make space for more items, or expired, or explicitly

deleted by a client).

An item sent by the server looks like:

VA <size> <flags>*\r\n

<data block>\r\n

- <size> is the size of <data block> in bytes, minus the \r\n

- <flags>* are flags returned by the server, based on the command flags.

They are added in order specified by the flags sent.

- <data block> is the data for this item. Note that the data block is

optional, requiring the 'v' flag to be supplied.

If the request did not ask for a value in the response (v) flag, the server

response looks like:

HD <flags>*\r\n

If the request resulted in a miss, the response looks like:

EN\r\n

Unless the (q) flag was supplied, which suppresses the status code for a miss.

The flags used by the 'mg' command are:

- b: interpret key as base64 encoded binary value

- c: return item cas token

- C(token): check CAS, do not send value if matches

- f: return client flags token

- h: return whether item has been hit before as a 0 or 1

- k: return key as a token

- l: return time since item was last accessed in seconds

- O(token): opaque value, consumes a token and copies back with response

- q: use noreply semantics for return codes.

- s: return item size token

- t: return item TTL remaining in seconds (-1 for unlimited)

- u: don't bump the item in the LRU

- v: return item value in <data block>

These flags can modify the item:

- E(token): use token as new CAS value if item is modified

- N(token): vivify on miss, takes TTL as a argument

- R(token): if remaining TTL is less than token, win for recache

- T(token): update remaining TTL

These extra flags can be added to the response:

- W: client has "won" the recache flag

- X: item is stale

- Z: item has already sent a winning flag

The flags are now repeated with detailed information where useful:

- b: interpret key as base64 encoded binary value

This flag instructs memcached to run a base64 decoder on <key> before looking

it up. This allows storing and fetching of binary packed keys, so long as they

are sent to memcached in base64 encoding.

If 'b' flag is sent in the response, and a key is returned via 'k', this

signals to the client that the key is base64 encoded binary.

- C(token): check CAS value against item, remove 'v' flag if matches

If a CAS token is supplied with C, and a 'v' flag is supplied, only return the

value if the CAS flag does NOT match. The response code will be "HD" if the

CAS does match, else "VA <size>" if the CAS does not match. This allows

conditionally fetching the value of an item only if it has changed.

All other flags behave as normal, example: T(token) will update the TTL

regardless of if the CAS matches.

- h: return whether item has been hit before as a 0 or 1

- l: return time since item was last accessed in seconds

The above two flags return the value of "hit before?" and "last access time"

before the command was processed. Otherwise this would always show a 1 for

hit or always show an access time of "0" unless combined with the "u" flag.

- O(token): opaque value, consumes a token and copies back with response

The O(opaque) token is used by this and other commands to allow easier

pipelining of requests while saving bytes on the wire for responses. For

example: if pipelining three get commands together, you may not know which

response belongs to which without also retrieving the key. If the key is very

long this can generate a lot of traffic, especially if the data block is very

small. Instead, you can supply an "O" flag for each mg with tokens of "1" "2"

and "3", to match up responses to the request.

Opaque tokens may be up to 32 bytes in length, and are a string similar to

keys.

- q: use noreply semantics for return codes.

Noreply is a method of reducing the amount of data sent back by memcached to

the client for normal responses. In the case of metaget, if an item is not

available the "VA" line is normally not sent, and the response is terminated by

"EN\r\n".

With noreply enabled, the "EN\r\n" marker is suppressed. This allows you to

pipeline several mg's together and read all of the responses without the

"EN\r\n" lines in the middle.

Errors are always returned.

- u: don't bump the item in the LRU

It is possible to access an item without causing it to be "bumped" to the head

of the LRU. This also avoids marking an item as being hit or updating its last

access time.

- v: return item value in <data block>

The data block for a metaget response is optional, requiring this flag to be

passed in. The response code also changes from "HD" to "VA <size>"

These flags can modify the item:

- E(token): use token as new CAS value if item is modified

Normally when an item is created it is given a CAS value from an internal

atomically incrementing counter. This allows overriding the CAS (8 byte

unsigned integer) with the specified value. This is useful for using an

external system to version cache data (row versions, clocks, etc).

- N(token): vivify on miss, takes TTL as a argument

Used to help with so called "dog piling" problems with recaching of popular

items. If supplied, and metaget does not find the item in cache, it will

create a stub item with the key and TTL as supplied. If such an item is

created a 'W' flag is added to the response to indicate to a client that they

have "won" the right to recache an item.

The automatically created item has 0 bytes of data.

Further requests will see a 'Z' flag to indicate that another client has

already received the win flag.

Can be combined with CAS flags to gate the update further.

- R(token): if token is less than remaining TTL win for recache

Similar to and can be combined with 'N'. If the remaining TTL of an item is

below the supplied token, return a 'W' flag to indicate the client has "won"

the right to recache an item. This allows refreshing an item before it leads to

a miss.

- T(token): update remaining TTL

Similar to "touch" and "gat" commands, updates the remaining TTL of an item if

hit.

These extra flags can be added to the response:

- W: client has "won" the recache flag

When combined with N or R flags, a client may be informed they have "won"

ownership of a cache item. This allows a single client to be atomically

notified that it should cache or update an item. Further clients requesting

the item can use the existing data block (if valid or stale), retry, wait, or

take some other action while the item is missing.

This is used when the act of recaching an item can cause undue load on another

system (CPU, database accesses, time, and so on).

- X: item is stale

Items can be marked as stale by the metadelete command. This indicates to the

client that an object needs to be updated, and that it should make a decision

o if potentially stale data is safe to use.

This is used when you want to convince clients to recache an item, but it's

safe to use pre-existing data while the recache happens.

- Z: item has already sent a winning flag

When combined with the X flag, or the client N or R flags, this extra response

flag indicates to a client that a different client is responsible for

recaching this item. If there is data supplied it may use it, or the client

may decide to retry later or take some other action.

Meta Set

--------

The meta set command a generic command for storing data to memcached. Based

on the flags supplied, it can replace all storage commands (see token M) as

well as adds new options.

ms <key> <datalen> <flags>*\r\n

- <key> means one key string.

- <datalen> is the length of the payload data.

- <flags> are a set of single character codes ended with a space or newline.

flags may have strings after the initial character.

After this line, the client sends the data block:

<data block>\r\n

- <data block> is a chunk of arbitrary 8-bit data of length <datalen>

from the previous line.

After sending the command line and the data block the client awaits

the reply, which is of the format:

<CD> <flags>*\r\n

Where CD is one of:

- "HD" (STORED), to indicate success.

- "NS" (NOT_STORED), to indicate the data was not stored, but not

because of an error.

- "EX" (EXISTS), to indicate that the item you are trying to store with

CAS semantics has been modified since you last fetched it.

- "NF" (NOT_FOUND), to indicate that the item you are trying to store

with CAS semantics did not exist.

The flags used by the 'ms' command are:

- b: interpret key as base64 encoded binary value (see metaget)

- c: return CAS value if successfully stored.

- C(token): compare CAS value when storing item

- E(token): use token as new CAS value (see metaget for detail)

- F(token): set client flags to token (32 bit unsigned numeric)

- I: invalidate. set-to-invalid if supplied CAS is older than item's CAS

- k: return key as a token

- O(token): opaque value, consumes a token and copies back with response

- q: use noreply semantics for return codes

- s: return the size of the stored item on success (ie; new size on append)

- T(token): Time-To-Live for item, see "Expiration" above.

- M(token): mode switch to change behavior to add, replace, append, prepend

- N(token): if in append mode, autovivify on miss with supplied TTL

The flags are now repeated with detailed information where useful:

- c: returns the CAS value on successful storage. Will return 0 on error, but

clients must not depend on the return value being zero. In future versions

this may return the current CAS value for "EX" return code conditions.

- C(token): compare CAS value when storing item

Similar to the basic "cas" command, only store item if the supplied token

matches the current CAS value of the item. When combined with the 'I' flag, a

CAS value that is _lower_ than the current value may be accepted, but the item

will be marked as "stale", returning the X flag with mget requests.

- F(token): set client flags to token (32 bit unsigned numeric)

Sets flags to 0 if not supplied.

- I: invalid. set-to-invalid if CAS is older than it should be.

Functional when combined with 'C' flag above.

- O(token): opaque value, consumes a token and copies back with response

See description under 'Meta Get'

- q: use noreply semantics for return codes

Noreply is a method of reducing the amount of data sent back by memcached to

the client for normal responses. In the case of metaset, a response that

would start with "HD" will not be sent. Any other code, such as "EX"

(EXISTS) will still be returned.

Errors are always returned.

- M(token): mode switch. Takes a single character for the mode.

E: "add" command. LRU bump and return NS if item exists. Else

add.

A: "append" command. If item exists, append the new value to its data.

P: "prepend" command. If item exists, prepend the new value to its data.

R: "replace" command. Set only if item already exists.

S: "set" command. The default mode, added for completeness.

The "cas" command is supplanted by specifying the cas value with the 'C' flag.

Append and Prepend modes will also respect a supplied cas value.

- N(token): if in append mode, autovivify on miss with supplied TTL

Append and Prepend modes normally ignore the T argument, as they cannot create

a new item on a miss. If N is supplied, and append reaches a miss, it will

create a new item seeded with the data from the append command. It uses the

TTL from N instead of T to be consistent with the usage of N in other

commands.

Meta Delete

-----------

The meta delete command allows for explicit deletion of items, as well as

marking items as "stale" to allow serving items as stale during revalidation.

md <key> <flags>*\r\n

- <key> means one key string.

- <flags> are a set of single character codes ended with a space or newline.

flags may have strings after the initial character.

The response is in the format:

<CD> <flags> <tokens>*\r\n

Where CD is one of:

- "HD" (DELETED), to indicate success

- "NF" (NOT_FOUND), to indicate that the item with this key was not found.

- "EX" (EXISTS), to indicate that the supplied CAS token does not match the

stored item.

The flags used by the 'md' command are:

- b: interpret key as base64 encoded binary value (see metaget)

- C(token): compare CAS value

- E(token): use token as new CAS value (see metaget for detail)

- I: invalidate. mark as stale, bumps CAS.

- k: return key

- O(token): opaque to copy back.

- q: noreply

- T(token): updates TTL, only when paired with the 'I' flag

- x: removes the item value, but leaves the item.

The flags are now repeated with detailed information where useful:

- C(token): compare CAS value

Can be used to only delete or mark-stale if a supplied CAS value matches.

- I: invalidate. mark as stale, bumps CAS.

Instead of removing an item, this will give the item a new CAS value and mark

it as stale. This means when it is later fetched by metaget, the client will

be supplied an 'X' flag to show the data is stale and needs to be recached.

- O(token): opaque to copy back.

See description under 'Meta Get'

- q: noreply

See description under 'Meta Set'. In the case of meta delete, this will hide

response lines with the code "DE". It will still return any other responses.

- T(token): updates TTL, only when paired with the 'I' flag

When marking an item as stale with 'I', the 'T' flag can be used to update the

TTL as well; limiting the amount of time an item will live while stale and

waiting to be recached.

- x: removes the item value, but leaves the item.

This deletes the value off of an item (by replacing it with an empty value

item atomically). Combined with I this can leave what is effectively a

tombstone of a previous value.

Meta Arithmetic

---------------

The meta arithmetic command allows for basic operations against numerical

values. This replaces the "incr" and "decr" commands. Values are unsigned

64bit integers. Decrementing will reach 0 rather than underflow. Incrementing

can overflow.

ma <key> <flags>*\r\n

- <key> means one key string.

- <flags> are a set of single character codes ended with a space or newline.

flags may have strings after the initial character.

The response is in the format:

<CD> <flags> <tokens>*\r\n

Where CD is one of:

- "HD" to indicate success

- "NF" (NOT_FOUND), to indicate that the item with this key was not found.

- "NS" (NOT_STORED), to indicate that the item was not created as requested

after a miss.

- "EX" (EXISTS), to indicate that the supplied CAS token does not match the

stored item.

If the 'v' flag is supplied, the response is formatted as:

VA <size> <flags>*\r\n

<number>\r\n

The flags used by the 'ma' command are:

- b: interpret key as base64 encoded binary value (see metaget)

- C(token): compare CAS value (see mset)

- E(token): use token as new CAS value (see metaget for detail)

- N(token): auto create item on miss with supplied TTL

- J(token): initial value to use if auto created after miss (default 0)

- D(token): delta to apply (decimal unsigned 64-bit number, default 1)

- T(token): update TTL on success

- M(token): mode switch to change between incr and decr modes.

- O(token): opaque value, consumes a token and copies back with response

- q: use noreply semantics for return codes (see details under mset)

- t: return current TTL

- c: return current CAS value if successful.

- v: return new value

- k: return key as a token

The flags are now repeated with detailed information where useful:

- C(token): compare CAS value

Can be used to only incr/decr if a supplied CAS value matches. A new CAS value

is generated after a delta is applied. Add the 'c' flag to get the new CAS

value after success.

- N(token): auto create item on miss with supplied TTL

Similar to mget, on a miss automatically create the item. A value can be

seeded using the J flag.

- J(token): initial value

An unsigned 64-bit integer which will be seeded as the value on a miss. Must be

combined with an N flag.

- D(token): delta to apply

An unsigned integer to either add or subtract from the currently stored

number.

- T(token): update TTL

On success, sets the remaining TTL to the supplied value.

-M(token): mode switch. Takes a single character for the mode.

I: Increment mode (default)

+: Alias for increment

D: Decrement mode

-: Alias for decrement

Meta No-Op

----------

The meta no-op command exists solely to return a static response code. It

takes no flags, no arguments.

"mn\r\n"

This returns the static response:

"MN\r\n"

This command is useful when used with the 'q' flag and pipelining commands.

For example, with 'mg' the response lines are blank on miss when the 'q' flag

is supplied. If pipelining several 'mg's together with noreply semantics, an

"mn\r\n" command can be tagged to the end of the chain, which will return an

"MN\r\n", signalling to a client that all previous commands have been

processed.

Slabs Reassign

--------------

NOTE: This command is subject to change as of this writing.

The slabs reassign command is used to redistribute memory once a running

instance has hit its limit. It might be desirable to have memory laid out

differently than was automatically assigned after the server started.

slabs reassign <source class> <dest class>\r\n

- <source class> is an id number for the slab class to steal a page from

A source class id of -1 means "pick from any valid class"

- <dest class> is an id number for the slab class to move a page to