Update docs.
[awesomized/libmemcached] / docs / man / libmemcached_examples.3
1 .TH "LIBMEMCACHED_EXAMPLES" "3" "April 09, 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 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 memcached_server_st *servers;
60 memcached_st *memc= memcached_create(NULL);
61 char servername[]= "0.example.com";
62
63 servers= memcached_server_list_append(NULL, servername, 400, &rc);
64
65 for (x= 0; x < 20; x++)
66 {
67 char buffer[SMALL_STRING_LEN];
68
69 snprintf(buffer, SMALL_STRING_LEN, "%u.example.com", 400+x);
70 servers= memcached_server_list_append(servers, buffer, 401, &rc);
71 }
72 rc= memcached_server_push(memc, servers);
73 memcached_server_free(servers);
74 memcached_free(memc);
75 .ft P
76 .fi
77 .sp
78 In the above code you create a \fBmemcached_st\fP object that you then feed in a
79 single host into. In the for loop you build a \fBmemcached_server_st\fPpointer that you then later feed via memcached_server_push() into the
80 \fBmemcached_st\fP structure.
81 .sp
82 You can reuse the \fBmemcached_server_st\fP object with multile \fBmemcached_st\fPstructures.
83 .SH ADDING A VALUE TO THE SERVER
84 .sp
85 .nf
86 .ft C
87 char *key= "foo";
88 char *value;
89 size_t value_length= 8191;
90 unsigned int x;
91
92 value = (char*)malloc(value_length);
93 assert(value);
94
95 for (x= 0; x < value_length; x++)
96 value[x] = (char) (x % 127);
97
98 for (x= 0; x < 1; x++)
99 {
100 rc= memcached_set(memc, key, strlen(key),
101 value, value_length,
102 (time_t)0, (uint32_t)0);
103 assert(rc == MEMCACHED_SUCCESS);
104 }
105
106 free(value);
107 .ft P
108 .fi
109 .sp
110 It is best practice to always look at the return value of any operation.
111 .SH FETCHING MULTIPLE VALUES
112 .sp
113 .nf
114 .ft C
115 memcached_return_t rc;
116 char *keys[]= {"fudge", "son", "food"};
117 size_t key_length[]= {5, 3, 4};
118 unsigned int x;
119 uint32_t flags;
120
121 char return_key[MEMCACHED_MAX_KEY];
122 size_t return_key_length;
123 char *return_value;
124 size_t return_value_length;
125
126 rc= memcached_mget(memc, keys, key_length, 3);
127
128 x= 0;
129 while ((return_value= memcached_fetch(memc, return_key, &return_key_length,
130 &return_value_length, &flags, &rc)))
131 {
132 free(return_value);
133 x++;
134 }
135 .ft P
136 .fi
137 .sp
138 Notice that you freed values returned from memcached_fetch(). The define
139 \fBMEMCACHED_MAX_KEY\fP is provided for usage.
140 .SH HOME
141 .sp
142 To find out more information please check:
143 \fI\%https://launchpad.net/libmemcached\fP
144 .SH SEE ALSO
145 .sp
146 \fImemcached(1)\fP
147 .SH AUTHOR
148 Brian Aker
149 .SH COPYRIGHT
150 2011, Brian Aker DataDifferential, http://datadifferential.com/
151 .\" Generated by docutils manpage writer.
152 .\"
153 .