Updating for 1.0.2 release
[awesomized/libmemcached] / docs / man / libmemcached_examples.3
1 .TH "LIBMEMCACHED_EXAMPLES" "3" "October 26, 2011" "1.0.2" "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 CONNECTING TO SERVERS
41 .sp
42 .nf
43 .ft C
44 const char *config_string= "\-\-SERVER=host10.example.com \-\-SERVER=host11.example.com \-\-SERVER=host10.example.com"
45 memcached_st *memc= memcached(config_string, strlen(config_string);
46 {
47 \&...
48 }
49 memcached_free(memc);
50 .ft P
51 .fi
52 .sp
53 In the above code you create a \fBmemcached_st\fP object with three server
54 by making use of \fBmemcached_create_with_options()\fP.
55 .SH CREATING A POOL OF SERVERS
56 .sp
57 .nf
58 .ft C
59
60 .ft P
61 .fi
62 .sp
63 Creating a pool of Servers:
64 .sp
65 .nf
66 .ft C
67 const char *config_string= "\-\-SERVER=host10.example.com \-\-SERVER=host11.example.com \-\-SERVER=host10.example.com";
68
69 memcached_pool_st* pool= memcached_pool(config_string, strlen(config_string));
70
71 memcached_return_t rc;
72
73 memcached_st *memc= memcached_pool_pop(pool, false, &rc);
74
75 \&.... do work
76
77 /*
78 Release the memc_ptr that was pulled from the pool
79 */
80 memcached_pool_push(pool, memc);
81
82 /*
83 Destroy the pool.
84 */
85 memcached_pool_destroy(pool);
86 .ft P
87 .fi
88 .sp
89 In the above code you create a \fBmemcached_pool_st\fP object with three
90 server by making use of \fBmemcached_pool()\fP.
91 .sp
92 When \fBmemcached_pool_destroy()\fP all memory will be released that is associated
93 with the pool.
94 .SH ADDING A VALUE TO THE SERVER
95 .sp
96 .nf
97 .ft C
98
99 .ft P
100 .fi
101 .sp
102 Adding a value to the Server:
103 .sp
104 .nf
105 .ft C
106 char *key= "foo";
107 char *value= "value";
108
109 memcached_return_t rc= memcached_set(memc, key, strlen(key), value, value_length, (time_t)0, (uint32_t)0);
110
111 if (rc != MEMCACHED_SUCCESS)
112 {
113 \&... // handle failure
114 }
115 .ft P
116 .fi
117 .sp
118 It is best practice to always look at the return value of any operation.
119 .SH FETCHING MULTIPLE VALUES
120 .sp
121 .nf
122 .ft C
123 memcached_return_t rc;
124 char *keys[]= {"fudge", "son", "food"};
125 size_t key_length[]= {5, 3, 4};
126 unsigned int x;
127 uint32_t flags;
128
129 char return_key[MEMCACHED_MAX_KEY];
130 size_t return_key_length;
131 char *return_value;
132 size_t return_value_length;
133
134 rc= memcached_mget(memc, keys, key_length, 3);
135
136 x= 0;
137 while ((return_value= memcached_fetch(memc, return_key, &return_key_length,
138 &return_value_length, &flags, &rc)))
139 {
140 free(return_value);
141 x++;
142 }
143 .ft P
144 .fi
145 .sp
146 Notice that you freed values returned from memcached_fetch(). The define
147 \fBMEMCACHED_MAX_KEY\fP is provided for usage.
148 .SH HOME
149 .sp
150 To find out more information please check:
151 \fI\%http://libmemcached.org/\fP
152 .SH SEE ALSO
153 .sp
154 \fImemcached(1)\fP
155 .SH AUTHOR
156 Brian Aker
157 .SH COPYRIGHT
158 2011, Brian Aker DataDifferential, http://datadifferential.com/
159 .\" Generated by docutils manpage writer.
160 .\"
161 .