diff options
Diffstat (limited to 'doc/ProtocolSpecification.html')
| -rw-r--r-- | doc/ProtocolSpecification.html | 142 |
1 files changed, 0 insertions, 142 deletions
diff --git a/doc/ProtocolSpecification.html b/doc/ProtocolSpecification.html deleted file mode 100644 index 686c574e8..000000000 --- a/doc/ProtocolSpecification.html +++ /dev/null @@ -1,142 +0,0 @@ - -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> -<html> - <head> - <link type="text/css" rel="stylesheet" href="style.css" /> - </head> - <body> - <div id="page"> - - <div id='header'> - <a href="index.html"> - <img style="border:none" alt="Redis Documentation" src="redis.png"> - </a> - </div> - - <div id="pagecontent"> - <div class="index"> -<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. --> -<b>ProtocolSpecification: Contents</b><br> <a href="#Networking layer">Networking layer</a><br> <a href="#Simple INLINE commands">Simple INLINE commands</a><br> <a href="#Bulk commands">Bulk commands</a><br> <a href="#Bulk replies">Bulk replies</a><br> <a href="#Multi-Bulk replies">Multi-Bulk replies</a><br> <a href="#Nil elements in Multi-Bulk replies">Nil elements in Multi-Bulk replies</a><br> <a href="#Single line reply">Single line reply</a><br> <a href="#Integer reply">Integer reply</a><br> <a href="#Multi bulk commands">Multi bulk commands</a><br> <a href="#Multiple commands and pipelining">Multiple commands and pipelining</a> - </div> - - <h1 class="wikiname">ProtocolSpecification</h1> - - <div class="summary"> - - </div> - - <div class="narrow"> - = Protocol Specification =<br/><br/>The Redis protocol is a compromise between being easy to parse by a computer -and being easy to parse by an human. Before reading this section you are -strongly encouraged to read the "REDIS TUTORIAL" section of this README in order -to get a first feeling of the protocol playing with it by TELNET.<h2><a name="Networking layer">Networking layer</a></h2>A client connects to a Redis server creating a TCP connection to the port 6379. -Every redis command or data transmitted by the client and the server is -terminated by "\r\n" (CRLF).<h2><a name="Simple INLINE commands">Simple INLINE commands</a></h2>The simplest commands are the inline commands. This is an example of a -server/client chat (the server chat starts with S:, the client chat with C:)<br/><br/><pre class="codeblock python" name="code"> -C: PING -S: +PONG -</pre>An inline command is a CRLF-terminated string sent to the client. The server can reply to commands in different ways: -<ul><li> With an error message (the first byte of the reply will be "-")</li><li> With a single line reply (the first byte of the reply will be "+)</li><li> With bulk data (the first byte of the reply will be "$")</li><li> With multi-bulk data, a list of values (the first byte of the reply will be "<code name="code" class="python">*</code>")</li><li> With an integer number (the first byte of the reply will be ":")</li></ul> -The following is another example of an INLINE command returning an integer:<br/><br/><pre class="codeblock python python" name="code"> -C: EXISTS somekey -S: :0 -</pre>Since 'somekey' does not exist the server returned ':0'.<br/><br/>Note that the EXISTS command takes one argument. Arguments are separated -simply by spaces.<h2><a name="Bulk commands">Bulk commands</a></h2>A bulk command is exactly like an inline command, but the last argument -of the command must be a stream of bytes in order to send data to the server. -the "SET" command is a bulk command, see the following example:<br/><br/><pre class="codeblock python python python" name="code"> -C: SET mykey 6 -C: foobar -S: +OK -</pre>The last argument of the commnad is '6'. This specify the number of DATA -bytes that will follow (note that even this bytes are terminated by two -additional bytes of CRLF).<br/><br/>All the bulk commands are in this exact form: instead of the last argument -the number of bytes that will follow is specified, followed by the bytes, -and CRLF. In order to be more clear for the programmer this is the string -sent by the client in the above sample:<br/><br/><blockquote>"SET mykey 6\r\nfoobar\r\n"</blockquote> -<h2><a name="Bulk replies">Bulk replies</a></h2>The server may reply to an inline or bulk command with a bulk reply. See -the following example:<br/><br/><pre class="codeblock python python python python" name="code"> -C: GET mykey -S: $6 -S: foobar -</pre>A bulk reply is very similar to the last argument of a bulk command. The -server sends as the first line a "$" byte followed by the number of bytes -of the actual reply followed by CRLF, then the bytes are sent followed by -additional two bytes for the final CRLF. The exact sequence sent by the -server is:<br/><br/><blockquote>"$6\r\nfoobar\r\n"</blockquote> -If the requested value does not exist the bulk reply will use the special -value -1 as data length, example:<br/><br/><pre class="codeblock python python python python python" name="code"> -C: GET nonexistingkey -S: $-1 -</pre>The client library API should not return an empty string, but a nil object, when the requested object does not exist. -For example a Ruby library should return 'nil' while a C library should return -NULL, and so forth.<h2><a name="Multi-Bulk replies">Multi-Bulk replies</a></h2>Commands similar to LRANGE needs to return multiple values (every element -of the list is a value, and LRANGE needs to return more than a single element). This is accomplished using multiple bulk writes, -prefixed by an initial line indicating how many bulk writes will follow. -The first byte of a multi bulk reply is always <code name="code" class="python">*</code>. Example:<br/><br/><pre class="codeblock python python python python python python" name="code"> -C: LRANGE mylist 0 3 -S: *4 -S: $3 -S: foo -S: $3 -S: bar -S: $5 -S: Hello -S: $5 -S: World -</pre>The first line the server sent is "<b>4\r\n" in order to specify that four bulk -write will follow. Then every bulk write is transmitted.<br/><br/>If the specified key does not exist instead of the number of elements in the -list, the special value -1 is sent as count. Example:<br/><br/><pre class="codeblock python python python python python python python" name="code"> -C: LRANGE nokey 0 1 -S: *-1 -</pre>A client library API SHOULD return a nil object and not an empty list when this -happens. This makes possible to distinguish between empty list and non existing ones.<h2><a name="Nil elements in Multi-Bulk replies">Nil elements in Multi-Bulk replies</a></h2>Single elements of a multi bulk reply may have -1 length, in order to signal that this elements are missing and not empty strings. This can happen with the SORT command when used with the GET <i>pattern</i> option when the specified key is missing. Example of a multi bulk reply containing an empty element:<br/><br/><pre class="codeblock python python python python python python python python" name="code"> -S: *3 -S: $3 -S: foo -S: $-1 -S: $3 -S: bar -</pre>The second element is nul. The client library should return something like this:<br/><br/><pre class="codeblock python python python python python python python python python" name="code"> -["foo",nil,"bar"] -</pre><h2><a name="Single line reply">Single line reply</a></h2>As already seen a single line reply is in the form of a single line string -starting with "+" terminated by "\r\n". For example:<br/><br/><pre class="codeblock python python python python python python python python python python" name="code"> -+OK -</pre>The client library should return everything after the "+", that is, the string "OK" in the example.<br/><br/>The following commands reply with a status code reply: -PING, SET, SELECT, SAVE, BGSAVE, SHUTDOWN, RENAME, LPUSH, RPUSH, LSET, LTRIM<h2><a name="Integer reply">Integer reply</a></h2>This type of reply is just a CRLF terminated string representing an integer, prefixed by a ":" byte. For example ":0\r\n", or ":1000\r\n" are integer replies.<br/><br/>With commands like INCR or LASTSAVE using the integer reply to actually return a value there is no special meaning for the returned integer. It is just an incremental number for INCR, a UNIX time for LASTSAVE and so on.<br/><br/>Some commands like EXISTS will return 1 for true and 0 for false.<br/><br/>Other commands like SADD, SREM and SETNX will return 1 if the operation was actually done, 0 otherwise.<br/><br/>The following commands will reply with an integer reply: SETNX, DEL, EXISTS, INCR, INCRBY, DECR, DECRBY, DBSIZE, LASTSAVE, RENAMENX, MOVE, LLEN, SADD, SREM, SISMEMBER, SCARD<h2><a name="Multi bulk commands">Multi bulk commands</a></h2>As you can see with the protocol described so far there is no way to -send multiple binary-safe arguments to a command. With bulk commands the -last argument is binary safe, but there are commands where multiple binary-safe -commands are needed, like the MSET command that is able to SET multiple keys -in a single operation.<br/><br/>In order to address this problem Redis 1.1 introduced a new way of seding -commands to a Redis server, that uses exactly the same protocol of the -multi bulk replies. For instance the following is a SET command using the -normal bulk protocol:<br/><br/><pre class="codeblock python python python python python python python python python python python" name="code"> -SET mykey 8 -myvalue -</pre>While the following uses the multi bulk command protocol:<br/><br/><pre class="codeblock python python python python python python python python python python python python" name="code"> -*3 -$3 -SET -$5 -mykey -$8 -myvalue -</pre>Commands sent in this format are longer, so currently they are used only in -order to transmit commands containing multiple binary-safe arguments, but -actually this protocol can be used to send every kind of command, without to -know if it's an inline, bulk or multi-bulk command.<br/><br/>It is possible that in the future Redis will support only this format.<br/><br/>A good client library may implement unknown commands using this -command format in order to support new commands out of the box without -modifications.<h2><a name="Multiple commands and pipelining">Multiple commands and pipelining</a></h2>A client can use the same connection in order to issue multiple commands. -Pipelining is supported so multiple commands can be sent with a single -write operation by the client, it is not needed to read the server reply -in order to issue the next command. All the replies can be read at the end.<br/><br/>Usually Redis server and client will have a very fast link so this is not -very important to support this feature in a client implementation, still -if an application needs to issue a very large number of commands in short -time to use pipelining can be much faster. -</b> - </div> - - </div> - </div> - </body> -</html> - |