redis-7.2.4.tar.gz

[](https://github.com/redis/hiredis/actions/workflows/build.yml) **This Readme reflects the latest changed in the master branch. See [v1.0.0](https://github.com/redis/hiredis/tree/v1.0.0) for the Readme and documentation for the latest release ([API/ABI history](https://abi-laboratory.pro/?view=timeline&l=hiredis)).** # HIREDIS Hiredis is a minimalistic C client library for the [Redis](https://redis.io/) database. It is minimalistic because it just adds minimal support for the protocol, but at the same time it uses a 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. Apart from supporting sending commands and receiving replies, it comes with a reply parser that is decoupled from the I/O layer. It is a stream parser designed for easy reusability, which can for instance be used in higher level language bindings for efficient reply parsing. Hiredis only supports the binary-safe Redis protocol, so you can use it with any Redis version >= 1.2.0. The library comes with multiple APIs. There is the *synchronous API*, the *asynchronous API* and the *reply parsing API*. ## Upgrading to `1.1.0` Almost all users will simply need to recompile their applications against the newer version of hiredis. **NOTE**: Hiredis can now return `nan` in addition to `-inf` and `inf` in a `REDIS_REPLY_DOUBLE`. Applications that deal with `RESP3` doubles should make sure to account for this. ## Upgrading to `1.0.2` <span style="color:red">NOTE: v1.0.1 erroneously bumped SONAME, which is why it is skipped here.</span> Version 1.0.2 is simply 1.0.0 with a fix for [CVE-2021-32765](https://github.com/redis/hiredis/security/advisories/GHSA-hfm9-39pp-55p2). They are otherwise identical. ## Upgrading to `1.0.0` Version 1.0.0 marks the first stable release of Hiredis. It includes some minor breaking changes, mostly to make the exposed API more uniform and self-explanatory. It also bundles the updated `sds` library, to sync up with upstream and Redis. For code changes see the [Changelog](CHANGELOG.md). _Note: As described below, a few member names have been changed but most applications should be able to upgrade with minor code changes and recompiling._ ## IMPORTANT: Breaking changes from `0.14.1` -> `1.0.0` * `redisContext` has two additional members (`free_privdata`, and `privctx`). * `redisOptions.timeout` has been renamed to `redisOptions.connect_timeout`, and we've added `redisOptions.command_timeout`. * `redisReplyObjectFunctions.createArray` now takes `size_t` instead of `int` for its length parameter. ## IMPORTANT: Breaking changes when upgrading from 0.13.x -> 0.14.x Bulk and multi-bulk lengths less than -1 or greater than `LLONG_MAX` are now protocol errors. This is consistent with the RESP specification. On 32-bit platforms, the upper bound is lowered to `SIZE_MAX`. Change `redisReply.len` to `size_t`, as it denotes the the size of a string User code should compare this to `size_t` values as well. If it was used to compare to other values, casting might be necessary or can be removed, if casting was applied before. ## Upgrading from `<0.9.0` Version 0.9.0 is a major overhaul of hiredis in every aspect. However, upgrading existing code using hiredis should not be a big pain. The key thing to keep in mind when upgrading is that hiredis >= 0.9.0 uses a `redisContext*` to keep state, in contrast to the stateless 0.0.1 that only has a file descriptor to work with. ## Synchronous API To consume the synchronous API, there are only a few function calls that need to be introduced: ```c redisContext *redisConnect(const char *ip, int port); void *redisCommand(redisContext *c, const char *format, ...); void freeReplyObject(void *reply); ``` ### Connecting The function `redisConnect` is used to create a so-called `redisContext`. The context is where Hiredis holds state for a connection. The `redisContext` struct has an integer `err` field that is non-zero when the connection is in an error state. The field `errstr` will contain a string with a description of the error. More information on errors can be found in the **Errors** section. After trying to connect to Redis using `redisConnect` you should check the `err` field to see if establishing the connection was successful: ```c redisContext *c = redisConnect("127.0.0.1", 6379); if (c == NULL || c->err) { if (c) { printf("Error: %s\n", c->errstr); // handle error } else { printf("Can't allocate redis context\n"); } } ``` One can also use `redisConnectWithOptions` which takes a `redisOptions` argument that can be configured with endpoint information as well as many different flags to change how the `redisContext` will be configured. ```c redisOptions opt = {0}; /* One can set the endpoint with one of our helper macros */ if (tcp) { REDIS_OPTIONS_SET_TCP(&opt, "localhost", 6379); } else { REDIS_OPTIONS_SET_UNIX(&opt, "/tmp/redis.sock"); } /* And privdata can be specified with another helper */ REDIS_OPTIONS_SET_PRIVDATA(&opt, myPrivData, myPrivDataDtor); /* Finally various options may be set via the `options` member, as described below */ opt->options |= REDIS_OPT_PREFER_IPV4; ``` If a connection is lost, `int redisReconnect(redisContext *c)` can be used to restore the connection using the same endpoint and options as the given context. ### Configurable redisOptions flags There are several flags you may set in the `redisOptions` struct to change default behavior. You can specify the flags via the `redisOptions->options` member. | Flag | Description | | --- | --- | | REDIS\_OPT\_NONBLOCK | Tells hiredis to make a non-blocking connection. | | REDIS\_OPT\_REUSEADDR | Tells hiredis to set the [SO_REUSEADDR](https://man7.org/linux/man-pages/man7/socket.7.html) socket option | | REDIS\_OPT\_PREFER\_IPV4<br>REDIS\_OPT\_PREFER_IPV6<br>REDIS\_OPT\_PREFER\_IP\_UNSPEC | Informs hiredis to either prefer IPv4 or IPv6 when invoking [getaddrinfo](https://man7.org/linux/man-pages/man3/gai_strerror.3.html). `REDIS_OPT_PREFER_IP_UNSPEC` will cause hiredis to specify `AF_UNSPEC` in the getaddrinfo call, which means both IPv4 and IPv6 addresses will be searched simultaneously.<br>Hiredis prefers IPv4 by default. | | REDIS\_OPT\_NO\_PUSH\_AUTOFREE | Tells hiredis to not install the default RESP3 PUSH handler (which just intercepts and frees the replies). This is useful in situations where you want to process these messages in-band. | | REDIS\_OPT\_NOAUTOFREEREPLIES | **ASYNC**: tells hiredis not to automatically invoke `freeReplyObject` after executing the reply callback. | | REDIS\_OPT\_NOAUTOFREE | **ASYNC**: Tells hiredis not to automatically free the `redisAsyncContext` on connection/communication failure, but only if the user makes an explicit call to `redisAsyncDisconnect` or `redisAsyncFree` | *Note: A `redisContext` is not thread-safe.* ### Other configuration using socket options The following socket options are applied directly to the underlying socket. The values are not stored in the `redisContext`, so they are not automatically applied when reconnecting using `redisReconnect()`. These functions return `REDIS_OK` on success. On failure, `REDIS_ERR` is returned and the underlying connection is closed. To configure these for an asyncronous context (see *Asynchronous API* below), use `ac->c` to get the redisContext out of an asyncRedisContext. ```C int redisEnableKeepAlive(redisContext *c); int redisEnableKeepAliveWithInterval(redisContext *c, int interval); ``` Enables TCP keepalive by setting the following socket options (with some variations depending on OS): * `SO_KEEPALIVE`; * `TCP_KEEPALIVE` or `TCP_KEEPIDLE`, value configurable using the `interval` parameter, default 15 seconds; * `TCP_KEEPINTVL` set to 1/3 of `interval`; * `TCP_