|
| 1 | +--- |
| 2 | +categories: |
| 3 | +- docs |
| 4 | +- develop |
| 5 | +- stack |
| 6 | +- oss |
| 7 | +- rs |
| 8 | +- rc |
| 9 | +- oss |
| 10 | +- kubernetes |
| 11 | +- clients |
| 12 | +description: Connect your C application to a Redis database. |
| 13 | +linkTitle: hiredis (C) |
| 14 | +title: hiredis guide (C) |
| 15 | +weight: 9 |
| 16 | +--- |
| 17 | + |
| 18 | +[`hiredis`](https://github.com/redis/hiredis) is the client for the |
| 19 | +[C language](https://en.wikipedia.org/wiki/C_(programming_language)). |
| 20 | +The sections below explain how to install `hiredis` and connect your application |
| 21 | +to a Redis database. |
| 22 | + |
| 23 | +`hiredis` requires a running Redis or [Redis Stack]({{< relref "/operate/oss_and_stack/install/install-stack/" >}}) server. See [Getting started]({{< relref "/operate/oss_and_stack/install/" >}}) for Redis installation instructions. |
| 24 | + |
| 25 | +## Build and install |
| 26 | + |
| 27 | +Clone or download the `hiredis` source from the [Github repository](https://github.com/redis/hiredis). |
| 28 | +Then, in a terminal, go into the `hiredis` folder and run the `make` command to build |
| 29 | +the dynamically-loaded library for `hiredis` (this has the name `libhiredis.dylib` on |
| 30 | +MacOS and `libhiredis.so` on Linux). You can copy this library to your |
| 31 | +project folder or run `sudo make install` to install it to `/usr/local/lib`. |
| 32 | +You should also copy the header files `hiredis.h`, `alloc.h`, `read.h`, and |
| 33 | +`sds.h` to your project. |
| 34 | + |
| 35 | +## Connect and test |
| 36 | + |
| 37 | +The code in the example below connects to the server, stores and retrieves |
| 38 | +a string key using [`SET`]({{< relref "/commands/set" >}}) and |
| 39 | +[`GET`]({{< relref "/commands/get" >}}), and then finally closes the |
| 40 | +connection. An explanation of the code follows the example. |
| 41 | + |
| 42 | +```c |
| 43 | +#include <stdio.h> |
| 44 | + |
| 45 | +#include "hiredis.h" |
| 46 | + |
| 47 | +int main() { |
| 48 | + // The `redisContext` type represents the connection |
| 49 | + // to the Redis server. Here, we connect to the |
| 50 | + // default host and port. |
| 51 | + redisContext *c = redisConnect("127.0.0.1", 6379); |
| 52 | + |
| 53 | + // Check if the context is null or if a specific |
| 54 | + // error occurred. |
| 55 | + if (c == NULL || c->err) { |
| 56 | + if (c != NULL) { |
| 57 | + printf("Error: %s\n", c->errstr); |
| 58 | + // handle error |
| 59 | + } else { |
| 60 | + printf("Can't allocate redis context\n"); |
| 61 | + } |
| 62 | + } |
| 63 | + |
| 64 | + // Set a string key. |
| 65 | + redisReply *reply = redisCommand(c, "SET foo bar"); |
| 66 | + |
| 67 | + // Check and free the reply. |
| 68 | + if (reply != NULL) { |
| 69 | + printf("Reply: %s\n", reply->str); |
| 70 | + freeReplyObject(reply); |
| 71 | + } |
| 72 | + |
| 73 | + // Get the key we have just stored. |
| 74 | + reply = redisCommand(c, "GET foo"); |
| 75 | + |
| 76 | + // Check and free the reply. |
| 77 | + if (reply != NULL) { |
| 78 | + printf("Reply: %s\n", reply->str); |
| 79 | + freeReplyObject(reply); |
| 80 | + } |
| 81 | + |
| 82 | + // Close the connection. |
| 83 | + redisFree(c); |
| 84 | +} |
| 85 | +``` |
| 86 | + |
| 87 | +For a real project, you would build your code with a makefile, but for |
| 88 | +this simple test, you can just place it in a file called `main.c` and |
| 89 | +build it with the following command (assuming you used `make install` to |
| 90 | +install the `libhiredis` library): |
| 91 | + |
| 92 | +```bash |
| 93 | +cc main.c -L/usr/local/lib -lhiredis |
| 94 | +``` |
| 95 | + |
| 96 | +The default executable filename is `a.out`. If you run this file from |
| 97 | +the terminal, you should see the following output: |
| 98 | + |
| 99 | +``` |
| 100 | +% ./a.out |
| 101 | +Reply: OK |
| 102 | +Reply: bar |
| 103 | +``` |
| 104 | + |
| 105 | +The code first uses `redisConnect()` to create the connection to |
| 106 | +use for all subsequent commands. |
| 107 | + |
| 108 | +The `redisCommand()` function |
| 109 | +issues commands to the server, each of which returns a |
| 110 | +`redisReply` pointer. Here, the reply is a string, which you can |
| 111 | +access using the `str` field of the reply. The `redisCommand()` |
| 112 | +call allocates memory for the reply, so you should free this |
| 113 | +with `freeReplyObject()` when you have finished using it. |
| 114 | +See [Issue commands]({{< relref "/develop/clients/hiredis/issue-commands" >}}) for more information about |
| 115 | +handling commands and their replies. |
| 116 | + |
| 117 | +Finally, you should close the connection to Redis with a |
| 118 | +call to `redisFree()`. This is not strictly necessary |
| 119 | +for this short test program, but real-world code will typically |
| 120 | +open and use many connections. You must free them after using them |
| 121 | +to prevent errors. |
| 122 | + |
| 123 | +## More information |
| 124 | + |
| 125 | +See the other pages in this section for more information and examples. |
0 commit comments