Merge pull request #140 from hussainnaqvee/patch-1
[awesomized/libmemcached] / libmemcached / memcached_fetch.rst
1 memcached_fetch
2 =================
3
4 SYNOPSIS
5 --------
6
7 #include <libmemcached/memcached.h>
8 Compile and link with -lmemcached
9
10 .. function:: char *memcached_fetch(memcached_st *ptr, char *key, size_t *key_length, size_t *value_length, uint32_t *flags, memcached_return_t *error)
11
12 .. deprecated:: 0.50
13 Use :func:`memcached_fetch_result` instead.
14
15
16 DESCRIPTION
17 -----------
18
19 :func:`memcached_fetch` is used to fetch an individual value from the server.
20 :func:`memcached_mget` must always be called before using this method.
21 You must pass in a key and its length to fetch the object.
22
23 You must supply three pointer variables which will give you the state of the returned
24 object:
25
26 * A :type:`uint32_t` pointer to contain whatever flags you stored with the value,
27 * a :type:`size_t` pointer which will be filled with size of of the object, and
28 * a :type:`memcached_return_t` pointer to hold any error.
29
30 The object will be returned upon success and NULL will be returned on failure.
31
32 `MEMCACHED_END` is returned by the error value when all objects that have been found are returned.
33 The final value upon `MEMCACHED_END` is a NULL pointer.
34
35 Values returned by :func:`memcached_fetch` must be freed by the caller.
36
37 All of the above functions are not tested when the
38 `MEMCACHED_BEHAVIOR_USE_UDP` has been set. Executing any of these
39 functions with this behavior on will result in `MEMCACHED_NOT_SUPPORTED`
40 being returned, or for those functions which do not return a
41 :type:`memcached_return_t`, the error function parameter will
42 be set to `MEMCACHED_NOT_SUPPORTED`.
43
44 RETURN VALUE
45 ------------
46
47 :func:`memcached_fetch` sets error to
48 to `MEMCACHED_END` upon successful conclusion.
49
50 `MEMCACHED_NOTFOUND` will be return if no keys at all were found.
51
52 `MEMCACHED_KEY_TOO_BIG` is set to error whenever :func:`memcached_fetch` was used
53 and the key was set larger then `MEMCACHED_MAX_KEY`, which was the largest
54 key allowed for the original memcached ascii server.
55
56 SEE ALSO
57 --------
58
59 .. only:: man
60
61 :manpage:`memcached(1)`
62 :manpage:`libmemcached(3)`
63 :manpage:`memcached_strerror(3)`
64 :manpage:`memcached_fetch_result(3)`
65
66 .. only:: html
67
68 * :manpage:`memcached(1)`
69 * :doc:`../libmemcached`
70 * :doc:`memcached_strerror`
71 * :doc:`memcached_get`