---
name: "memcached_increment_with_initial"
section: "3"
platform: "linux"
package: "libmemcached-awesome"
version: "1.1.4-4"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/memcached_increment_with_initial"
---

# memcached\_increment\_with\_initial(3)

Incrementing and Decrementing Values

## NAME

memcached\_increment\_with\_initial - Incrementing and Decrementing Values

## SYNOPSIS

- **#include \<libmemcached/memcached.h\>**

  Compile and link with -lmemcached

- **memcached\_return\_t \<#\_CPPv418memcached\_return\_t\> memcached\_increment(memcached\_st \<#\_CPPv412memcached\_st\> \*ptr, const char \*key, size\_t key\_length, uint32\_t offset, uint64\_t \*value)**

  - **memcached\_return\_t \<#\_CPPv418memcached\_return\_t\> memcached\_decrement(memcached\_st \<#\_CPPv412memcached\_st\> \*ptr, const char \*key, size\_t key\_length, uint32\_t offset, uint64\_t \*value)**

  - **memcached\_return\_t \<#\_CPPv418memcached\_return\_t\> memcached\_increment\_with\_initial(memcached\_st \<#\_CPPv412memcached\_st\> \*ptr, const char \*key, size\_t key\_length, uint64\_t offset, uint64\_t initial, time\_t expiration, uint64\_t \*value)**

  - **memcached\_return\_t \<#\_CPPv418memcached\_return\_t\> memcached\_decrement\_with\_initial(memcached\_st \<#\_CPPv412memcached\_st\> \*ptr, const char \*key, size\_t key\_length, uint64\_t offset, uint64\_t initial, time\_t expiration, uint64\_t \*value)**

  - **memcached\_return\_t \<#\_CPPv418memcached\_return\_t\> memcached\_increment\_by\_key(memcached\_st \<#\_CPPv412memcached\_st\> \*ptr, const char \*group\_key, size\_t group\_key\_length, const char \*key, size\_t key\_length, uint32\_t offset, uint64\_t \*value)**

  - **memcached\_return\_t \<#\_CPPv418memcached\_return\_t\> memcached\_decrement\_by\_key(memcached\_st \<#\_CPPv412memcached\_st\> \*ptr, const char \*group\_key, size\_t group\_key\_length, const char \*key, size\_t key\_length, uint32\_t offset, uint64\_t \*value)**

  - **memcached\_return\_t \<#\_CPPv418memcached\_return\_t\> memcached\_increment\_with\_initial\_by\_key(memcached\_st \<#\_CPPv412memcached\_st\> \*ptr, const char \*group\_key, size\_t group\_key\_length, const char \*key, size\_t key\_length, uint64\_t offset, uint64\_t initial, time\_t expiration, uint64\_t \*value)**

  - **memcached\_return\_t \<#\_CPPv418memcached\_return\_t\> memcached\_decrement\_with\_initial\_by\_key(memcached\_st \<#\_CPPv412memcached\_st\> \*ptr, const char \*group\_key, size\_t group\_key\_length, const char \*key, size\_t key\_length, uint64\_t offset, uint64\_t initial, time\_t expiration, uint64\_t \*value)**

  - **Parameters**

    - •

      **ptr** -- pointer to an initialized **memcached\_st** \<#\_CPPv412memcached\_st\> struct

    - •

      **group\_key** -- key namespace

    - •

      **group\_key\_length** -- length of the key namespace without any terminating zero

    - •

      **key** -- the key

    - •

      **key\_length** -- length of the key without any terminating zero

    - •

      **offset** -- offset to increment/decrement

    - •

      **initial** -- initial value if **key** does not exist and **expiration** is not **MEMCACHED\_EXPIRATION\_NOT\_ADD**

    - •

      **expiration** -- expiration as a unix timestamp or as relative expiration time in seconds

    - •

      **value** -- the resulting value after initialization/increment/decrement

  - **Returns**

    **memcached\_return\_t** \<#\_CPPv418memcached\_return\_t\> indicating success

## DESCRIPTION

**[memcached(1)](/memcached/1.md) \<https://linux.die.net/man/1/memcached\>** servers have the ability to increment and decrement keys (overflow and underflow are not detected). This gives you the ability to use memcached to generate shared sequences of values.

**memcached\_increment()** takes a **key** and **key\_length** and increments the value by the **offset** passed to it. The value is then returned via the uint32\_t **value** pointer you pass to it.

**memcached\_decrement()** takes a **key** and **key\_length** and decrements the value by the **offset** passed to it. The value is then returned via the uint32\_t **value** pointer you pass to it.

**memcached\_increment\_with\_initial()** takes a **key** and **key\_length** and increments the value by the **offset** passed to it. If the object specified by **key** does not exist, one of two things may happen: If the **expiration** value is **MEMCACHED\_EXPIRATION\_NOT\_ADD** \<#c.MEMCACHED\_EXPIRATION\_NOT\_ADD\>, the operation will fail. For all other **expiration** values, the operation will succeed by seeding the value for that key with a initial value to expire with the provided expiration time. The **flags** will be set to zero. The value is then returned via the uint32\_t **value** pointer you pass to it. **memcached\_increment\_with\_initial** is only available when using the binary protocol.

**memcached\_decrement\_with\_initial()** takes a **key** and **key\_length** and decrements the value by the **offset** passed to it. If the object specified by **key** does not exist, one of two things may happen: If the **expiration** value is **MEMCACHED\_EXPIRATION\_NOT\_ADD** \<#c.MEMCACHED\_EXPIRATION\_NOT\_ADD\>, the operation will fail. For all other **expiration** values, the operation will succeed by seeding the value for that key with a initial value to expire with the provided expiration time. The **flags** will be set to zero. The value is then returned via the uint32\_t **value** pointer you pass to it. **memcached\_decrement\_with\_initial()** is only available when using the binary protocol.

**memcached\_increment\_by\_key()**, **memcached\_decrement\_by\_key()**, **memcached\_increment\_with\_initial\_by\_key()**, and **memcached\_decrement\_with\_initial\_by\_key()** are master key equivalents of the above.

## RETURN VALUE

A value of type **memcached\_return\_t** \<#\_CPPv418memcached\_return\_t\>  is returned. On success that value will be **MEMCACHED\_SUCCESS** \<#\_CPPv4N18memcached\_return\_t17MEMCACHED\_SUCCESSE\>. Use **memcached\_strerror()** \<#\_CPPv418memcached\_strerrorP12memcached\_st18memcached\_return\_t\> to translate this value to a printable string.

## SEE ALSO

**[memcached(1)](/memcached/1.md) \<https://linux.die.net/man/1/memcached\>** **[libmemcached(3)](/libmemcached/3.md) \<https://linux.die.net/man/3/libmemcached\>** **[memcached\_strerror(3)](/memcached_strerror/3.md) \<https://linux.die.net/man/3/memcached\_strerror\>**