Merge in all new docs
[m6w6/libmemcached] / docs / man / libmemcached_examples.3
1 .TH "LIBMEMCACHED_EXAMPLES" "3" "April 12, 2011" "0.47" "libmemcached"
2 .SH NAME
3 libmemcached_examples \- libmemcached Documentation
4 .
5 .nr rst2man-indent-level 0
6 .
7 .de1 rstReportMargin
8 \\$1 \\n[an-margin]
9 level \\n[rst2man-indent-level]
10 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
11 -
12 \\n[rst2man-indent0]
13 \\n[rst2man-indent1]
14 \\n[rst2man-indent2]
15 ..
16 .de1 INDENT
17 .\" .rstReportMargin pre:
18 . RS \\$1
19 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
20 . nr rst2man-indent-level +1
21 .\" .rstReportMargin post:
22 ..
23 .de UNINDENT
24 . RE
25 .\" indent \\n[an-margin]
26 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
27 .nr rst2man-indent-level -1
28 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
29 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
30 ..
31 .\" Man page generated from reStructeredText.
32 .
33 .sp
34 Examples for libmemcached
35 .SH DESCRIPTION
36 .sp
37 For full examples, test cases are found in tests/*.c in the main
38 distribution. These are always up to date, and are used for each test run of
39 the library.
40 .SH CREATING AND FREEING THE MEMCACHED_ST STRUCTURE
41 .sp
42 .nf
43 .ft C
44 memcached_st *memc;
45 memcached_return_t rc;
46
47 memc= memcached_create(NULL);
48 \&...do stuff...
49 memcached_free(memc);
50 .ft P
51 .fi
52 .sp
53 The above code would create a connection and then free the connection when
54 finished.
55 .SH CONNECTING TO SERVERS
56 .sp
57 .nf
58 .ft C
59 const char *config_string= "\-\-SERVER=host10.example.com \-\-SERVER=host11.example.com \-\-SERVER=host10.example.com"
60 memcached_st *memc= memcached_create_with_options(config_string, strlen(config_string);
61 {
62 ...
63 }
64 memcached_free(memc);
65 .ft P
66 .fi
67 .sp
68 In the above code you create a \fBmemcached_st\fP object with three server by making use of \fImemcached_create_with_options(3)\fP.
69 .SH CREATING A POOL OF SERVERS
70 .sp
71 .nf
72 .ft C
73 const char *config_string= "\-\-SERVER=host10.example.com \-\-SERVER=host11.example.com \-\-SERVER=host10.example.com";
74
75 memcached_pool_st* pool= memcached_pool(config_string, strlen(config_string));
76
77 memcached_return_t rc;
78
79 memcached_st *memc= memcached_pool_pop(pool, false, &rc);
80
81 \&.... do work
82
83 /*
84 Release the memc_ptr that was pulled from the pool
85 */
86 memcached_pool_push(pool, memc);
87
88 /*
89 Destroy the pool.
90 */
91 memcached_pool_destroy(pool);
92 .ft P
93 .fi
94 .sp
95 In the above code you create a \fBmemcached_pool_st\fP object with three
96 server by making use of \fImemcached_pool(3)\fP.
97 .sp
98 When memcached_pool_destroy() all memory will be released that is associated
99 with the pool.
100 .SH ADDING A VALUE TO THE SERVER
101 .sp
102 .nf
103 .ft C
104 char *key= "foo";
105 char *value;
106 size_t value_length= 8191;
107 unsigned int x;
108
109 value = (char*)malloc(value_length);
110 assert(value);
111
112 for (x= 0; x < value_length; x++)
113 value[x] = (char) (x % 127);
114
115 for (x= 0; x < 1; x++)
116 {
117 rc= memcached_set(memc, key, strlen(key),
118 value, value_length,
119 (time_t)0, (uint32_t)0);
120 assert(rc == MEMCACHED_SUCCESS);
121 }
122
123 free(value);
124 .ft P
125 .fi
126 .sp
127 It is best practice to always look at the return value of any operation.
128 .SH FETCHING MULTIPLE VALUES
129 .sp
130 .nf
131 .ft C
132 memcached_return_t rc;
133 char *keys[]= {"fudge", "son", "food"};
134 size_t key_length[]= {5, 3, 4};
135 unsigned int x;
136 uint32_t flags;
137
138 char return_key[MEMCACHED_MAX_KEY];
139 size_t return_key_length;
140 char *return_value;
141 size_t return_value_length;
142
143 rc= memcached_mget(memc, keys, key_length, 3);
144
145 x= 0;
146 while ((return_value= memcached_fetch(memc, return_key, &return_key_length,
147 &return_value_length, &flags, &rc)))
148 {
149 free(return_value);
150 x++;
151 }
152 .ft P
153 .fi
154 .sp
155 Notice that you freed values returned from memcached_fetch(). The define
156 \fBMEMCACHED_MAX_KEY\fP is provided for usage.
157 .SH HOME
158 .sp
159 To find out more information please check:
160 \fI\%https://launchpad.net/libmemcached\fP
161 .SH SEE ALSO
162 .sp
163 \fImemcached(1)\fP
164 .SH AUTHOR
165 Brian Aker
166 .SH COPYRIGHT
167 2011, Brian Aker DataDifferential, http://datadifferential.com/
168 .\" Generated by docutils manpage writer.
169 .\"
170 .