From 8b8b7afef28055ca40230abf3e91006884e6c8f8 Mon Sep 17 00:00:00 2001 From: Pieter Noordhuis Date: Tue, 12 Oct 2010 00:31:09 +0200 Subject: Change README to Markdown --- README | 116 -------------------------------------------------------------- README.md | 116 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 116 insertions(+), 116 deletions(-) delete mode 100644 README create mode 100644 README.md diff --git a/README b/README deleted file mode 100644 index 11926ce..0000000 --- a/README +++ /dev/null @@ -1,116 +0,0 @@ -HIREDIS OVERVIEW ----------------- - -Hiredis is a minimalistic C client library for the Redis Database. - -It is minimalistic because it just adds minimal support for the protocol, but -at the same time it uses an high level printf-alike API in order to make it -much higher level than otherwise suggested by its minimal code base and the -lack of explicit bindings for every Redis command. - -Hiredis only supports the Redis new protocol, so you can use it with any -Redis version >= 1.2.0. - -HIREDIS API ------------ - -Hiredis exports only three function calls: - -redisReply *redisConnect(int *fd, char *ip, int port); -redisReply *redisCommand(int fd, char *format, ...); -void freeReplyObject(redisReply *r); - -The first function is used in order to create a connection to the Redis server: - - redisReply *reply; - int fd; - - reply = redisConnect(&fd,"127.0.0.1",6379); - -to test for connection errors all it is needed to do is checking if reply -is not NULL: - - if (reply != NULL) { - printf("Connection error: %s\n", reply->reply); - freeReplyObject(reply); - exit(1); - } - -When a reply object returns an error, the reply->type is set to the value -REDIS_REPLY_ERROR, and reply->reply points to a C string with the description -of the error. - -In the above example we don't check for reply->type as redisConnect() can -only return NULL or a reply object that is actually an error. - -As you can see redisConnect() will just set (by reference) the fd variable -to the file descriptor of the open socket connected to our Redis server. - -Calls to redisCommand() will require this file descriptor as first argument. - -SENDING COMMNADS ----------------- - -Commands are sent using a printf-alike format. In the simplest form it is -like that: - - reply = redisCommand("SET foo bar"); - -But you can use "%s" and "%b" format specifiers to create commands in a -printf-alike fashion: - - reply = redisComand("SET foo %s", somevalue); - -If your arguments are binary safe, you can use %b that receives the pointer -to the buffer and a size_t integer with the length of the buffer. - - reply = redisCommand("SET %s %b", "foo", somevalue, somevalue_length); - -Internally Hiredis will split the command in different arguments and will -convert it to the actual protocol used to communicate with Redis. -Every space will separate arguments, so you can use interpolation. -The following example is valid: - - reply = redisCommand("SET key:%s %s", myid, value); - -USING REPLIES -------------- - -redisCommand() returns a reply object. In order to use this object you -need to test the reply->type field, that can be one of the following types: - -REDIS_REPLY_ERROR - The command returned an error string, that can be read accessing to - the reply->reply field. - -REDIS_REPLY_STRING - The command returned a string, that can be read accessing to the - reply->reply field. The string is always nul-termined, but when you - need to work with binary-safe strings you can obtain the exact length - of the reply with: sdslen(reply->reply). - -REDIS_REPLY_ARRAY - The command returned an array of reply->elements elements. - Every element is a redisReply object, stored at redis->element[..index..] - Redis may reply with nexted arrays but this is fully supported. - -REDIS_REPLY_INTEGER - The command replies with an integer. It's possible to access this integer - using the reply->integer field that is of type "long long". - -REDIS_REPLY_NIL - The command replies with a NIL special object. There is no data to access. - -FREEING REPLIES ---------------- - -Replies should be freed using the freeReplyObject() function. -Note that this function will take care of freeing sub-replies objects -contained in arrays and nested arrays, so there is no need for the user to -free the sub replies (it is actually harmful and will corrupt the memory). - -AUHTOR ------- - -Hiredis was written by Salvatore Sanfilippo (antirez at gmail) and is -released under the BSD license. diff --git a/README.md b/README.md new file mode 100644 index 0000000..f2d871f --- /dev/null +++ b/README.md @@ -0,0 +1,116 @@ +HIREDIS OVERVIEW +---------------- + +Hiredis is a minimalistic C client library for the Redis Database. + +It is minimalistic because it just adds minimal support for the protocol, but +at the same time it uses an high level printf-alike API in order to make it +much higher level than otherwise suggested by its minimal code base and the +lack of explicit bindings for every Redis command. + +Hiredis only supports the new Redis protocol, so you can use it with any +Redis version >= 1.2.0. + +HIREDIS API +----------- + +Hiredis exports only three function calls: + + redisReply *redisConnect(int *fd, char *ip, int port); + redisReply *redisCommand(int fd, char *format, ...); + void freeReplyObject(redisReply *r); + +The first function is used in order to create a connection to the Redis server: + + redisReply *reply; + int fd; + + reply = redisConnect(&fd,"127.0.0.1",6379); + +to test for connection errors all it is needed to do is checking if reply +is not NULL: + + if (reply != NULL) { + printf("Connection error: %s\n", reply->reply); + freeReplyObject(reply); + exit(1); + } + +When a reply object returns an error, the reply->type is set to the value +`REDIS_REPLY_ERROR`, and reply->reply points to a C string with the description +of the error. + +In the above example we don't check for reply->type as `redisConnect()` can +only return `NULL` or a reply object that is actually an error. + +As you can see `redisConnect()` will just set (by reference) the `fd` variable +to the file descriptor of the open socket connected to our Redis server. + +Calls to `redisCommand()` will require this file descriptor as first argument. + +SENDING COMMANDS +---------------- + +Commands are sent using a printf-alike format. In the simplest form it is +like that: + + reply = redisCommand("SET foo bar"); + +But you can use "%s" and "%b" format specifiers to create commands in a +printf-alike fashion: + + reply = redisComand("SET foo %s", somevalue); + +If your arguments are binary safe, you can use "%b" that receives the pointer +to the buffer and a size_t integer with the length of the buffer. + + reply = redisCommand("SET %s %b", "foo", somevalue, somevalue_length); + +Internally Hiredis will split the command in different arguments and will +convert it to the actual protocol used to communicate with Redis. +Every space will separate arguments, so you can use interpolation. +The following example is valid: + + reply = redisCommand("SET key:%s %s", myid, value); + +USING REPLIES +------------- + +`redisCommand()` returns a reply object. In order to use this object you +need to test the reply->type field, that can be one of the following types: + +* `REDIS_REPLY_ERROR`: + The command returned an error string, that can be read accessing to + the reply->reply field. + +* `REDIS_REPLY_STRING`: + The command returned a string, that can be read accessing to the + reply->reply field. The string is always null-terminated, but when you + need to work with binary-safe strings you can obtain the exact length + of the reply with: `sdslen(reply->reply)`. + +* `REDIS_REPLY_ARRAY`: + The command returned an array of reply->elements elements. + Every element is a redisReply object, stored at redis->element[..index..] + Redis may reply with nested arrays but this is fully supported. + +* `REDIS_REPLY_INTEGER`: + The command replies with an integer. It's possible to access this integer + using the reply->integer field that is of type "long long". + +* `REDIS_REPLY_NIL`: + The command replies with a NIL special object. There is no data to access. + +FREEING REPLIES +--------------- + +Replies should be freed using the `freeReplyObject()` function. +Note that this function will take care of freeing sub-replies objects +contained in arrays and nested arrays, so there is no need for the user to +free the sub replies (it is actually harmful and will corrupt the memory). + +AUHTOR +------ + +Hiredis was written by Salvatore Sanfilippo (antirez at gmail) and is +released under the BSD license. -- cgit v1.2.3