Merge pull request #140 from hussainnaqvee/patch-1
[awesomized/libmemcached] / libmemcached / memcached_create.rst
1 Creating and destroying a memcached_st
2 ======================================
3
4 SYNOPSIS
5 --------
6
7 #include <libmemcached/memcached.h>
8 Compile and link with -lmemcached
9
10 .. type:: struct memcached_st memcached_st
11
12 .. function:: memcached_st* memcached_create(memcached_st *ptr)
13
14 :param ptr: pointer to user-allocated `memcached_st` struct or null pointer
15 :returns: pointer to initialized `memcached_st` struct
16
17 .. function:: void memcached_free(memcached_st *ptr)
18
19 :param ptr: pointer to initialized `memcached_st` struct to destroy and possibly free
20
21 .. function:: memcached_st* memcached_clone(memcached_st *destination, memcached_st *source)
22
23 :param destination: pointer to user-allocated `memcached_st` struct or null pointer
24 :param source: pointer to initialized `memcached_st` struct to copy from
25 :returns: pointer to newly initialized `destination`, copied from `source`
26
27 .. function:: void memcached_servers_reset(memcached_st *ptr)
28
29 :param ptr: pointer to initialized `memcached_st` struct
30
31 DESCRIPTION
32 -----------
33
34 `memcached_create` is used to create a `memcached_st` structure that will then
35 be used by other `libmemcached` functions to communicate with the server. You
36 should either pass a statically declared `memcached_st` to `memcached_create` or
37 a NULL. If a NULL passed in then a structure is allocated for you.
38
39 Please note, when you write new application use `memcached` over
40 `memcached_create`.
41
42 `memcached_clone` is similar to `memcached_create` but it copies the defaults
43 and list of servers from the source `memcached_st` pointer. If you pass a null
44 as the argument for the source to clone, it is the same as a call to
45 `memcached_create`. If the destination argument is NULL a `memcached_st` will be
46 allocated for you.
47
48 `memcached_servers_reset` allows you to zero out the list of servers that the
49 `memcached_st` has.
50
51 To clean up memory associated with a `memcached_st` structure you should pass it
52 to `memcached_free` when you are finished using it. `memcached_free` is the only
53 way to make sure all memory is deallocated when you finish using the structure.
54
55 You may wish to avoid using `memcached_create` or `memcached_clone` with a stack
56 based allocation. The most common issues related to ABI safety involve heap
57 allocated structures.
58
59 RETURN VALUE
60 ------------
61
62 `memcached_create` returns a pointer to the `memcached_st` that was created (or
63 initialized). On an allocation failure, it returns NULL.
64
65 `memcached_clone` returns a pointer to the `memcached_st` that was created (or
66 initialized). On an allocation failure, it returns NULL.
67
68 SEE ALSO
69 --------
70
71 .. only:: man
72
73 :manpage:`memcached(1)`
74 :manpage:`libmemcached(3)`
75
76 .. only:: html
77
78 * :manpage:`memcached(1)`
79 * :doc:`../libmemcached`