1 ========================
2 Configuring Libmemcached
3 ========================
11 .. describe:: #include <libmemcached-1.0/memcached.h>
13 .. c:function:: memcached_st *\
14 memcached(const char *string, size_t string_length)
16 .. c:function:: memcached_return_t \
17 libmemcached_check_configuration(const char *option_string, size_t length, \
18 char *error_buffer, size_t error_buffer_size)
20 Compile and link with -lmemcached
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.
34 .. option:: --SERVER=<servername>:<optional_port>/?<optional_weight>
36 Provide a servername to be used by the client.
38 Providing a weight will cause weighting to occur with all hosts with each server getting a default weight of 1.
40 .. option:: --SOCKET=\"<filepath>/?<optional_weight>\"
42 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.
44 .. option:: --VERIFY-KEY
46 Verify that keys that are being used fit within the design of the protocol being used.
48 .. option:: --REMOVE_FAILED_SERVERS
50 Enable the behavior :c:type:`MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS`.
52 .. option:: --BINARY-PROTOCOL
54 Force all connections to use the binary protocol.
56 .. option:: --BUFFER-REQUESTS
58 Please see :c:type:`MEMCACHED_BEHAVIOR_BUFFER_REQUESTS`.
60 .. option:: --CONFIGURE-FILE=
62 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.
64 .. option:: --CONNECT-TIMEOUT=
66 Please see :c:type:`MEMCACHED_BEHAVIOR_CONNECT_TIMEOUT`.
68 .. option:: --DISTRIBUTION=
70 Set the distribution model used by the client. See :c:func:`memcached_behavior_set` for more details.
74 Set the hashing algorithm used for placing keys on servers.
76 .. option:: --HASH-WITH-NAMESPACE
78 When enabled the prefix key will be added to the key when determining which
79 server to store the data in.
83 Enable "no reply" for all calls that support this. It is highly recommended
84 that you use this option with the binary protocol only.
86 .. option:: --NUMBER-OF-REPLICAS=
88 Set the number of servers that keys will be replicated to.
90 .. option:: --RANDOMIZE-REPLICA-READ
92 Select randomly the server within the replication pool to read from.
94 .. option:: --SORT-HOSTS
96 When adding new servers always calculate their distribution based on sorted naming order.
98 .. option:: --SUPPORT-CAS
100 See :manpage:`memcached_behavior_set(3)` for :c:type:`MEMCACHED_BEHAVIOR_SUPPORT_CAS`
102 .. option:: --USE-UDP
104 See :manpage:`memcached_behavior_set(3)` for :c:type:`MEMCACHED_BEHAVIOR_USE_UDP`
106 .. option:: --NAMESPACE=
108 A namespace is a container that provides context for keys, only other
109 requests that know the namespace can access these values. This is
110 accomplished by prepending the namespace value to all keys.
113 ***********************
114 Memcached Pool Options:
115 ***********************
117 .. option:: --POOL-MIN
119 Initial size of pool.
121 .. option:: --POOL-MAX
123 Maximize size of the pool.
129 .. option:: --TCP-NODELAY
131 See :manpage:`memcached_behavior_set(3)` for MEMCACHED_BEHAVIOR_TCP_NODELAY
133 .. option:: --TCP-KEEPALIVE
135 See :manpage:`memcached_behavior_set(3)` for MEMCACHED_BEHAVIOR_TCP_KEEPALIVE
137 .. option:: --RETRY-TIMEOUT=
139 See :manpage:`memcached_behavior_set(3)` for MEMCACHED_BEHAVIOR_RETRY_TIMEOUT
141 .. option:: --SERVER-FAILURE-LIMIT=
143 See :manpage:`memcached_behavior_set(3)` for MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT
145 .. option:: --SND-TIMEOUT=
147 See :manpage:`memcached_behavior_set(3)` for MEMCACHED_BEHAVIOR_SND_TIMEOUT
149 .. option:: --SOCKET-RECV-SIZE=
151 See :manpage:`memcached_behavior_set(3)` for MEMCACHED_BEHAVIOR_SOCKET_RECV_SIZE
153 .. option:: --SOCKET-SEND-SIZE=
155 See :manpage:`memcached_behavior_set(3)` for MEMCACHED_BEHAVIOR_SOCKET_SEND_SIZE
157 .. option:: --POLL-TIMEOUT=
159 That sets the value of the timeout used by :manpage: `poll()`.
161 .. option:: --IO-BYTES-WATERMARK=
163 .. option:: --IO-KEY-PREFETCH=
165 .. option:: --IO-MSG-WATERMARK=
167 .. option:: --TCP-KEEPIDLE
169 .. option:: --RCV-TIMEOUT=
179 Include a file in configuration. Unlike --CONFIGURE-FILE= this will not reset memcached_st
183 Reset memcached_st and continue to process.
187 End configuration processing.
191 End configuration processing and throw an error.
198 .. envvar:: LIBMEMCACHED
206 :c:func:`memcached()` returns a pointer to the memcached_st that was
207 created (or initialized). On an allocation failure, it returns NULL.
218 const char *config_string=
219 "--SERVER=host10.example.com "
220 "--SERVER=host11.example.com "
221 "--SERVER=host10.example.com";
222 memcached_st *memc= memcached(config_string, strlen(config_string));
226 memcached_free(memc);
235 :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)`