Update for release 1.01
[awesomized/libmemcached] / docs / man / memcached.3
1 .TH "MEMCACHED" "3" "October 24, 2011" "1.01" "libmemcached"
2 .SH NAME
3 memcached \- 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 .SH SYNOPSIS
34 .sp
35 #include <libmemcached/memcached.h>
36 .INDENT 0.0
37 .TP
38 .B memcached_st *memcached(const char\fI\ *string\fP, size_t\fI\ string_length\fP)
39 .UNINDENT
40 .INDENT 0.0
41 .TP
42 .B memcached_return_t libmemcached_check_configuration(const char\fI\ *option_string\fP, size_t\fI\ length\fP, char\fI\ *error_buffer\fP, size_t\fI\ error_buffer_size\fP)
43 .UNINDENT
44 .sp
45 Compile and link with \-lmemcached
46 .SH DESCRIPTION
47 .sp
48 Libmemcached implements a custom language for configuring and modifying
49 servers. By passing in an option string you can generate a \fBmemcached_st\fP object
50 that you can use in your application directly.
51 .INDENT 0.0
52 .TP
53 .B \-\-SERVER=<servername>:<optional_port>/?<optional_weight>
54 .UNINDENT
55 .sp
56 Provide a servername to be used by the client. Providing a weight will cause weighting to occur with all hosts with each server getting a default weight of 1.
57 .INDENT 0.0
58 .TP
59 .B \-\-SOCKET=<filepath>/?<optional_weight>
60 .UNINDENT
61 .sp
62 Provide a filepath to a UNIX socket file. Providing a weight will cause weighting to occur with all hosts with each server getting a default weight of 1.
63 .INDENT 0.0
64 .TP
65 .B \-\-VERIFY\-KEY
66 .UNINDENT
67 .sp
68 Verify that keys that are being used fit within the design of the protocol being used.
69 .INDENT 0.0
70 .TP
71 .B \-\-REMOVE_FAILED_SERVERS
72 .UNINDENT
73 .sp
74 Enable the behavior MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS.
75 .INDENT 0.0
76 .TP
77 .B \-\-BINARY\-PROTOCOL
78 .UNINDENT
79 .sp
80 Force all connections to use the binary protocol.
81 .INDENT 0.0
82 .TP
83 .B \-\-BUFFER\-REQUESTS
84 .UNINDENT
85 .sp
86 Enable MEMCACHED_BEHAVIOR_BUFFER_REQUESTS.
87 .INDENT 0.0
88 .TP
89 .B \-\-CONFIGURE\-FILE=
90 .UNINDENT
91 .sp
92 Provide a configuration file to be used to load requests. Beware that by using a configuration file libmemcached will reset memcached_st based on information only contained in the file.
93 .INDENT 0.0
94 .TP
95 .B \-\-CONNECT\-TIMEOUT=
96 .UNINDENT
97 .sp
98 Enable MEMCACHED_BEHAVIOR_CONNECT_TIMEOUT.
99 .INDENT 0.0
100 .TP
101 .B \-\-DISTRIBUTION=
102 .UNINDENT
103 .sp
104 Set the distribution model used by the client. See :manpage:\(ga\(ga for more details.
105 .INDENT 0.0
106 .TP
107 .B \-\-HASH=
108 .UNINDENT
109 .sp
110 Set the hashing alogrthm used for placing keys on servers.
111 .INDENT 0.0
112 .TP
113 .B \-\-HASH\-WITH\-NAMESPACE
114 .UNINDENT
115 .sp
116 When enabled the prefix key will be added to the key when determining which
117 server to store the data in.
118 .INDENT 0.0
119 .TP
120 .B \-\-NOREPLY
121 .UNINDENT
122 .sp
123 Enable "no reply" for all calls that support this. It is highly recommended
124 that you use this option with the binary protocol only.
125 .INDENT 0.0
126 .TP
127 .B \-\-NUMBER\-OF\-REPLICAS=
128 .UNINDENT
129 .sp
130 Set the nummber of servers that keys will be replicated to.
131 .INDENT 0.0
132 .TP
133 .B \-\-RANDOMIZE\-REPLICA\-READ
134 .UNINDENT
135 .sp
136 Select randomly the server within the replication pool to read from.
137 .INDENT 0.0
138 .TP
139 .B \-\-SORT\-HOSTS
140 .UNINDENT
141 .sp
142 When adding new servers always calculate their distribution based on sorted naming order.
143 .INDENT 0.0
144 .TP
145 .B \-\-SUPPORT\-CAS
146 .UNINDENT
147 .sp
148 See \fImemcached_behavior_set(3)\fP for MEMCACHED_BEHAVIOR_SUPPORT_CAS
149 .INDENT 0.0
150 .TP
151 .B \-\-USE\-UDP
152 .UNINDENT
153 .sp
154 See \fImemcached_behavior_set(3)\fP for MEMCACHED_BEHAVIOR_USE_UDP
155 .INDENT 0.0
156 .TP
157 .B \-\-NAMESPACE=
158 .UNINDENT
159 .sp
160 A namespace is a container that provides context for keys, only other
161 requests that know the namespace can access these values. This is
162 accomplished by prepending the namespace value to all keys.
163 .SS Mecached Pool Options:
164 .INDENT 0.0
165 .TP
166 .B \-\-POOL\-MIN
167 .UNINDENT
168 .sp
169 Initial size of pool.
170 .INDENT 0.0
171 .TP
172 .B \-\-POOL\-MAX
173 .UNINDENT
174 .sp
175 Maximize size of the pool.
176 .SS I/O Options:
177 .INDENT 0.0
178 .TP
179 .B \-\-TCP\-NODELAY
180 .UNINDENT
181 .sp
182 See \fImemcached_behavior_set(3)\fP for MEMCACHED_BEHAVIOR_TCP_NODELAY
183 .INDENT 0.0
184 .TP
185 .B \-\-TCP\-KEEPALIVE
186 .UNINDENT
187 .sp
188 See \fImemcached_behavior_set(3)\fP for MEMCACHED_BEHAVIOR_TCP_KEEPALIVE
189 .INDENT 0.0
190 .TP
191 .B \-\-RETRY\-TIMEOUT=
192 .UNINDENT
193 .sp
194 See \fImemcached_behavior_set(3)\fP for MEMCACHED_BEHAVIOR_RETRY_TIMEOUT
195 .INDENT 0.0
196 .TP
197 .B \-\-SERVER\-FAILURE\-LIMIT=
198 .UNINDENT
199 .sp
200 See \fImemcached_behavior_set(3)\fP for MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT
201 .INDENT 0.0
202 .TP
203 .B \-\-SND\-TIMEOUT=
204 .UNINDENT
205 .sp
206 See \fImemcached_behavior_set(3)\fP for MEMCACHED_BEHAVIOR_SND_TIMEOUT
207 .INDENT 0.0
208 .TP
209 .B \-\-SOCKET\-RECV\-SIZE=
210 .UNINDENT
211 .sp
212 See \fImemcached_behavior_set(3)\fP for MEMCACHED_BEHAVIOR_SOCKET_RECV_SIZE
213 .INDENT 0.0
214 .TP
215 .B \-\-SOCKET\-SEND\-SIZE=
216 .UNINDENT
217 .sp
218 See \fImemcached_behavior_set(3)\fP for MEMCACHED_BEHAVIOR_SOCKET_SEND_SIZE
219 .INDENT 0.0
220 .TP
221 .B \-\-POLL\-TIMEOUT=
222 .UNINDENT
223 .sp
224 That sets the value of the timeout used by :manpage: \fIpoll()\fP.
225 .INDENT 0.0
226 .TP
227 .B \-\-IO\-BYTES\-WATERMARK=
228 .UNINDENT
229 .INDENT 0.0
230 .TP
231 .B \-\-IO\-KEY\-PREFETCH=
232 .UNINDENT
233 .INDENT 0.0
234 .TP
235 .B \-\-IO\-MSG\-WATERMARK=
236 .UNINDENT
237 .INDENT 0.0
238 .TP
239 .B \-\-TCP\-KEEPIDLE
240 .UNINDENT
241 .INDENT 0.0
242 .TP
243 .B \-\-RCV\-TIMEOUT=
244 .UNINDENT
245 .SS Other:
246 .INDENT 0.0
247 .TP
248 .B INCLUDE
249 .UNINDENT
250 .sp
251 Include a file in configuration. Unlike \-\-CONFIGURE\-FILE= this will not reset memcached_st
252 .INDENT 0.0
253 .TP
254 .B RESET
255 .UNINDENT
256 .sp
257 Reset memcached_st and continue to process.
258 .INDENT 0.0
259 .TP
260 .B END
261 .UNINDENT
262 .sp
263 End configutation processing.
264 .INDENT 0.0
265 .TP
266 .B ERROR
267 .UNINDENT
268 .sp
269 End configutation processing and throw an error.
270 .SH RETURN
271 .sp
272 \fI\%memcached()\fP returns a pointer to the memcached_st that was
273 created (or initialized). On an allocation failure, it returns NULL.
274 .SH EXAMPLE
275 .sp
276 .nf
277 .ft C
278 const char *config_string= "\-\-SERVER=host10.example.com \-\-SERVER=host11.example.com \-\-SERVER=host10.example.com"
279 memcached_st *memc= memcached(config_string, strlen(config_string);
280 {
281 ...
282 }
283 memcached_free(memc);
284 .ft P
285 .fi
286 .SH HOME
287 .sp
288 To find out more information please check:
289 \fI\%http://libmemcached.org/\fP
290 .SH SEE ALSO
291 .sp
292 \fImemcached(1)\fP \fIlibmemcached(3)\fP \fImemcached_strerror(3)\fP
293 .SH AUTHOR
294 Brian Aker
295 .SH COPYRIGHT
296 2011, Brian Aker DataDifferential, http://datadifferential.com/
297 .\" Generated by docutils manpage writer.
298 .\"
299 .