Merge pull request #140 from hussainnaqvee/patch-1
[awesomized/libmemcached] / libmemcached / configuration.rst
1 libmemcached Configuration
2 ==========================
3
4 SYNOPSIS
5 --------
6
7 #include <libmemcached-|libmemcached_version|/memcached.h>
8 Compile and link with -lmemcached
9
10 .. function:: memcached_st *memcached(const char *string, size_t string_length)
11
12 :param string: configuration string
13 :param string_length: length of the configuration string without any terminating zero
14 :returns: allocated and initialized `memcached_st` struct
15
16 .. function:: memcached_return_t libmemcached_check_configuration(const char *option_string, size_t length, char *error_buffer, size_t error_buffer_size)
17
18 :param option_string: configuration string
19 :param length: length of the configuration string without any terminating zero
20 :param error_buffer: buffer used to store any error message
21 :param error_buffer_size: available size of the `error_buffer`
22 :returns: `memcached_return_t` indicating success
23
24 DESCRIPTION
25 -----------
26
27 `libmemcached` implements a custom language for configuring and modifying
28 servers. By passing in an option string you can generate a `memcached_st` object
29 that you can use in your application directly.
30
31 General Options:
32 ~~~~~~~~~~~~~~~~
33
34 .. describe:: --SERVER=<servername>:<optional_port>/?<optional_weight>
35
36 Provide a servername to be used by the client.
37
38 Providing a weight will cause weighting to occur with all hosts with each
39 server getting a default weight of 1.
40
41 .. describe:: --SOCKET=\"<filepath>/?<optional_weight>\"
42
43 Provide a filepath to a UNIX socket file. Providing a weight will cause
44 weighting to occur with all hosts with each server getting a default weight
45 of 1.
46
47 .. describe:: --VERIFY-KEY
48
49 Verify that keys that are being used fit within the design of the protocol
50 being used.
51
52 .. describe:: --REMOVE_FAILED_SERVERS
53
54 Enable the behavior `MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS`.
55
56 .. describe:: --BINARY-PROTOCOL
57
58 Force all connections to use the binary protocol.
59
60 .. describe:: --BUFFER-REQUESTS
61
62 Please see `MEMCACHED_BEHAVIOR_BUFFER_REQUESTS`.
63
64 .. describe:: --CONFIGURE-FILE=
65
66 Provide a configuration file to be used to load requests. Beware that by
67 using a configuration file `libmemcached` will reset `memcached_st` based
68 on information only contained in the file.
69
70 .. describe:: --CONNECT-TIMEOUT=
71
72 See `memcached_behavior_set` for `MEMCACHED_BEHAVIOR_CONNECT_TIMEOUT`.
73
74 .. describe:: --DISTRIBUTION=
75
76 Set the distribution model used by the client.
77 See `memcached_behavior_set` for more details.
78
79 .. describe:: --HASH=
80
81 Set the hashing algorithm used for placing keys on servers.
82
83 .. describe:: --HASH-WITH-NAMESPACE
84
85 When enabled the prefix key will be added to the key when determining which
86 server to store the data in.
87
88 .. describe:: --NOREPLY
89
90 Enable "no reply" for all calls that support this. It is highly recommended
91 that you use this option with the binary protocol only.
92
93 .. describe:: --NUMBER-OF-REPLICAS=
94
95 Set the number of servers that keys will be replicated to.
96
97 .. describe:: --RANDOMIZE-REPLICA-READ
98
99 Select randomly the server within the replication pool to read from.
100
101 .. describe:: --SORT-HOSTS
102
103 When adding new servers always calculate their distribution based on sorted
104 naming order.
105
106 .. describe:: --SUPPORT-CAS
107
108 See `memcached_behavior_set` for `MEMCACHED_BEHAVIOR_SUPPORT_CAS`
109
110 .. describe:: --USE-UDP
111
112 See `memcached_behavior_set` for `MEMCACHED_BEHAVIOR_USE_UDP`
113
114 .. describe:: --NAMESPACE=
115
116 A namespace is a container that provides context for keys, only other
117 requests that know the namespace can access these values. This is
118 accomplished by prepending the namespace value to all keys.
119
120 Memcached Pool Options:
121 ~~~~~~~~~~~~~~~~~~~~~~~
122
123 .. describe:: --POOL-MIN
124
125 Initial size of pool.
126
127 .. describe:: --POOL-MAX
128
129 Maximize size of the pool.
130
131 I/O Options:
132 ~~~~~~~~~~~~
133
134 .. describe:: --TCP-NODELAY
135
136 See `memcached_behavior_set` for `MEMCACHED_BEHAVIOR_TCP_NODELAY`
137
138 .. describe:: --TCP-KEEPALIVE
139
140 See `memcached_behavior_set` for `MEMCACHED_BEHAVIOR_TCP_KEEPALIVE`
141
142 .. describe:: --RETRY-TIMEOUT=
143
144 See `memcached_behavior_set` for `MEMCACHED_BEHAVIOR_RETRY_TIMEOUT`
145
146 .. describe:: --SERVER-FAILURE-LIMIT=
147
148 See `memcached_behavior_set` for `MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT`
149
150 .. describe:: --SND-TIMEOUT=
151
152 See `memcached_behavior_set` for `MEMCACHED_BEHAVIOR_SND_TIMEOUT`
153
154 .. describe:: --SOCKET-RECV-SIZE=
155
156 See `memcached_behavior_set` for `MEMCACHED_BEHAVIOR_SOCKET_RECV_SIZE`
157
158 .. describe:: --SOCKET-SEND-SIZE=
159
160 See `memcached_behavior_set` for `MEMCACHED_BEHAVIOR_SOCKET_SEND_SIZE`
161
162 .. describe:: --POLL-TIMEOUT=
163
164 Set the timeout used by :manpage:`poll(3)`.
165
166 .. describe:: --IO-BYTES-WATERMARK=
167
168 .. describe:: --IO-KEY-PREFETCH=
169
170 .. describe:: --IO-MSG-WATERMARK=
171
172 .. describe:: --TCP-KEEPIDLE
173
174 .. describe:: --RCV-TIMEOUT=
175
176 Other Options:
177 ~~~~~~~~~~~~~~
178
179 .. describe:: INCLUDE
180
181 Include a file in configuration.
182 Unlike ``--CONFIGURE-FILE=`` this will not reset `memcached_st`.
183
184 .. describe:: RESET
185
186 Reset `memcached_st` and continue to process.
187
188 .. describe:: END
189
190 End configuration processing.
191
192 .. describe:: ERROR
193
194 End configuration processing and throw an error.
195
196 ENVIRONMENT
197 -----------
198
199 .. envvar:: LIBMEMCACHED
200
201 RETURN VALUE
202 ------------
203
204 `memcached` returns a pointer to the `memcached_st` that was created (or
205 initialized). On an allocation failure, it returns NULL.
206
207 EXAMPLE
208 -------
209
210 .. code-block:: c
211
212 const char *config_string=
213 "--SERVER=host10.example.com "
214 "--SERVER=host11.example.com "
215 "--SERVER=host10.example.com";
216 memcached_st *memc= memcached(config_string, strlen(config_string));
217 {
218 // ...
219 }
220 memcached_free(memc);
221
222 SEE ALSO
223 --------
224
225 .. only:: man
226
227 :manpage:`memcached(1)`
228 :manpage:`libmemcached(3)`
229 :manpage:`memcached_strerror(3)`
230
231 .. only:: html
232
233 * :manpage:`memcached(1)`
234 * :doc:`../libmemcached`
235 * :doc:`memcached_strerror`