git.m6w6.name Git - awesomized/libmemcached/blob - docs/memcached_set.rst

   1 .. highlight:: perl
   2
   3
   4 ****
   5 NAME
   6 ****
   7
   8
   9 memcached_set, memcached_add, memcached_replace - Store value on server
  10
  11
  12 *******
  13 LIBRARY
  14 *******
  15
  16
  17 C Client Library for memcached (libmemcached, -lmemcached)
  18
  19
  20 ********
  21 SYNOPSIS
  22 ********
  23
  24
  25
  26 .. code-block:: perl
  27
  28    #include <memcached.h>
  29
  30    memcached_return_t
  31      memcached_set (memcached_st *ptr,
  32                     const char *key, size_t key_length,
  33                     const char *value, size_t value_length,
  34                     time_t expiration,
  35                     uint32_t flags);
  36
  37    memcached_return_t
  38      memcached_add (memcached_st *ptr,
  39                     const char *key, size_t key_length,
  40                     const char *value, size_t value_length,
  41                     time_t expiration,
  42                     uint32_t flags);
  43
  44    memcached_return_t
  45      memcached_replace (memcached_st *ptr,
  46                         const char *key, size_t key_length,
  47                         const char *value, size_t value_length,
  48                         time_t expiration,
  49                         uint32_t flags);
  50
  51    memcached_return_t
  52      memcached_prepend(memcached_st *ptr,
  53                        const char *key, size_t key_length,
  54                        const char *value, size_t value_length,
  55                        time_t expiration,
  56                        uint32_t flags)
  57
  58    memcached_return_t
  59      memcached_append(memcached_st *ptr,
  60                       const char *key, size_t key_length,
  61                        const char *value, size_t value_length,
  62                        time_t expiration,
  63                        uint32_t flags)
  64    memcached_return_t
  65      memcached_cas(memcached_st *ptr,
  66                    const char *key, size_t key_length,
  67                    const char *value, size_t value_length,
  68                    time_t expiration,
  69                    uint32_t flags,
  70                    uint64_t cas);
  71
  72    memcached_return_t
  73      memcached_set_by_key(memcached_st *ptr,
  74                           const char *master_key, size_t master_key_length,
  75                           const char *key, size_t key_length,
  76                           const char *value, size_t value_length,
  77                           time_t expiration,
  78                           uint32_t flags);
  79
  80    memcached_return_t
  81      memcached_add_by_key(memcached_st *ptr,
  82                           const char *master_key, size_t master_key_length,
  83                           const char *key, size_t key_length,
  84                           const char *value, size_t value_length,
  85                           time_t expiration,
  86                           uint32_t flags);
  87
  88    memcached_return_t
  89      memcached_replace_by_key(memcached_st *ptr,
  90                               const char *master_key, size_t master_key_length,
  91                               const char *key, size_t key_length,
  92                               const char *value, size_t value_length,
  93                               time_t expiration,
  94                               uint32_t flags);
  95
  96    memcached_return_t
  97      memcached_prepend_by_key(memcached_st *ptr,
  98                               const char *master_key, size_t master_key_length,
  99                               const char *key, size_t key_length,
 100                               const char *value, size_t value_length,
 101                               time_t expiration,
 102                               uint32_t flags);
 103
 104    memcached_return_t
 105      memcached_append_by_key(memcached_st *ptr,
 106                              const char *master_key, size_t master_key_length,
 107                              const char *key, size_t key_length,
 108                              const char *value, size_t value_length,
 109                              time_t expiration,
 110                              uint32_t flags);
 111
 112    memcached_return_t
 113      memcached_cas_by_key(memcached_st *ptr,
 114                           const char *master_key, size_t master_key_length,
 115                           const char *key, size_t key_length,
 116                           const char *value, size_t value_length,
 117                           time_t expiration,
 118                           uint32_t flags,
 119                           uint64_t cas);
 120
 121
 122
 123 ***********
 124 DESCRIPTION
 125 ***********
 126
 127
 128 memcached_set(), memcached_add(), and memcached_replace() are all used to
 129 store information on the server. All methods take a key, and its length to
 130 store the object. Keys are currently limited to 250 characters by the
 131 memcached(1) server. You must also supply a value and a length. Optionally you
 132 may support an expiration time for the object and a 16 byte value (it is
 133 meant to be used as a bitmap).
 134
 135 memcached_set() will write an object to the server. If an object already
 136 exists it will overwrite what is in the server. If the object does not exist
 137 it will be written. If you are using the non-blocking mode this function
 138 will always return true unless a network error occurs.
 139
 140 memcached_replace() replaces an object on the server. If the object is not
 141 found on the server an error occurs.
 142
 143 memcached_add() adds an object to the server. If the object is found on the
 144 server an error occurs, otherwise the value is stored.
 145
 146 memcached_prepend() places a segment of data before the last piece of data
 147 stored. Currently expiration and key are not used in the server.
 148
 149 memcached_append() places a segment of data at the end of the last piece of
 150 data stored. Currently expiration and key are not used in the server.
 151
 152 memcached_cas() overwrites data in the server as long as the "cas" value is
 153 still the same in the server. You can get the cas value of a result by
 154 calling memcached_result_cas() on a memcached_result_st(3) structure. At the point
 155 that this note was written cas is still buggy in memached. Turning on support
 156 for it in libmemcached(3) is optional. Please see memcached_set() for
 157 information on how to do this.
 158
 159 memcached_set_by_key(), memcached_add_by_key(), memcached_replace_by_key(),
 160 memcached_prepend_by_key(), memcached_append_by_key_by_key(),
 161 memcached_cas_by_key() methods all behave in a similar method as the non key
 162 methods. The difference is that they use their master_key parameter to map
 163 objects to particular servers.
 164
 165 If you are looking for performance, memcached_set() with non-blocking IO is
 166 the fastest way to store data on the server.
 167
 168 All of the above functions are supported with the \ ``MEMCACHED_BEHAVIOR_USE_UDP``\
 169 behavior enabled. But when using these operations with this behavior on, there
 170 are limits to the size of the payload being sent to the server.  The reason for
 171 these limits is that the Memcahed Server does not allow multi-datagram requests
 172 and the current server implementation sets a datagram size to 1400 bytes. Due
 173 to protocol overhead, the actual limit of the user supplied data is less than
 174 1400 bytes and depends on the protocol in use as well as the operation being
 175 executed. When running with the binary protocol, \ `` MEMCACHED_BEHAVIOR_BINARY_PROTOCOL``\ ,
 176 the size of the key,value, flags and expiry combined may not exceed 1368 bytes.
 177 When running with the ASCII protocol, the exact limit fluctuates depending on
 178 which function is being executed and whether the function is a cas operation
 179 or not. For non-cas ASCII set operations, there are at least 1335 bytes available
 180 to split among the key, key_prefix, and value; for cas ASCII operations there are
 181 at least 1318 bytes available to split among the key, key_prefix and value. If the
 182 total size of the command, including overhead, exceeds 1400 bytes, a \ ``MEMCACHED_WRITE_FAILURE``\
 183 will be returned.
 184
 185
 186 ******
 187 RETURN
 188 ******
 189
 190
 191 All methods return a value of type \ ``memcached_return_t``\ .
 192 On success the value will be \ ``MEMCACHED_SUCCESS``\ .
 193 Use memcached_strerror() to translate this value to a printable string.
 194
 195 For memcached_replace() and memcached_add(), \ ``MEMCACHED_NOTSTORED``\  is a
 196 legitmate error in the case of a collision.
 197
 198
 199 ****
 200 HOME
 201 ****
 202
 203
 204 To find out more information please check:
 205 `https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
 206
 207
 208 ******
 209 AUTHOR
 210 ******
 211
 212
 213 Brian Aker, <brian@tangent.org>
 214
 215
 216 ********
 217 SEE ALSO
 218 ********
 219
 220
 221 memcached(1) libmemached(3) memcached_strerror(3)
 222