4 <!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
5 <!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
9 <meta name=
"viewport" content=
"width=device-width, initial-scale=1.0">
11 <title>C/C++ Client Library for memcached
— libmemcached
1.0.99 documentation
</title>
20 <script type=
"text/javascript" src=
"_static/js/modernizr.min.js"></script>
23 <script type=
"text/javascript" id=
"documentation_options" data-url_root=
"./" src=
"_static/documentation_options.js"></script>
24 <script src=
"_static/jquery.js"></script>
25 <script src=
"_static/underscore.js"></script>
26 <script src=
"_static/doctools.js"></script>
27 <script src=
"_static/language_data.js"></script>
29 <script type=
"text/javascript" src=
"_static/js/theme.js"></script>
34 <link rel=
"stylesheet" href=
"_static/css/theme.css" type=
"text/css" />
35 <link rel=
"stylesheet" href=
"_static/pygments.css" type=
"text/css" />
36 <link rel=
"index" title=
"Index" href=
"genindex.html" />
37 <link rel=
"search" title=
"Search" href=
"search.html" />
38 <link rel=
"copyright" title=
"Copyright" href=
"copyright.html" />
39 <link rel=
"next" title=
"libmemcached API" href=
"libmemcached/index.html" />
40 <link rel=
"prev" title=
"libmemcached Manual" href=
"index.html" />
43 <body class=
"wy-body-for-nav">
46 <div class=
"wy-grid-for-nav">
48 <nav data-toggle=
"wy-nav-shift" class=
"wy-nav-side">
49 <div class=
"wy-side-scroll">
50 <div class=
"wy-side-nav-search" >
54 <a href=
"index.html" class=
"icon icon-home"> libmemcached
71 <form id=
"rtd-search-form" class=
"wy-form" action=
"search.html" method=
"get">
72 <input type=
"text" name=
"q" placeholder=
"Search docs" />
73 <input type=
"hidden" name=
"check_keywords" value=
"yes" />
74 <input type=
"hidden" name=
"area" value=
"default" />
81 <div class=
"wy-menu wy-menu-vertical" data-spy=
"affix" role=
"navigation" aria-label=
"main navigation">
88 <p class=
"caption"><span class=
"caption-text">libmemcached
</span></p>
90 <li class=
"toctree-l1 current"><a class=
"current reference internal" href=
"#">Introduction
</a></li>
91 <li class=
"toctree-l1"><a class=
"reference internal" href=
"libmemcached/index.html">libmemcached API
</a></li>
92 <li class=
"toctree-l1"><a class=
"reference internal" href=
"libmemcached/index_misc.html">Misc
</a></li>
94 <p class=
"caption"><span class=
"caption-text">libmemcachedutil
</span></p>
96 <li class=
"toctree-l1"><a class=
"reference internal" href=
"libmemcachedutil.html">Introduction
</a></li>
97 <li class=
"toctree-l1"><a class=
"reference internal" href=
"libmemcachedutil/index.html">libmemcachedutil API
</a></li>
99 <p class=
"caption"><span class=
"caption-text">libhashkit
</span></p>
101 <li class=
"toctree-l1"><a class=
"reference internal" href=
"libhashkit.html">Introduction
</a></li>
102 <li class=
"toctree-l1"><a class=
"reference internal" href=
"libhashkit/index.html">libhashkit API
</a></li>
104 <p class=
"caption"><span class=
"caption-text">Client Applications
</span></p>
106 <li class=
"toctree-l1"><a class=
"reference internal" href=
"bin/index.html">Client Applications
</a></li>
108 <p class=
"caption"><span class=
"caption-text">Copyright
</span></p>
110 <li class=
"toctree-l1"><a class=
"reference internal" href=
"copyright.html">Copyright
</a></li>
119 <section data-toggle=
"wy-nav-shift" class=
"wy-nav-content-wrap">
122 <nav class=
"wy-nav-top" aria-label=
"top navigation">
124 <i data-toggle=
"wy-nav-top" class=
"fa fa-bars"></i>
125 <a href=
"index.html">libmemcached
</a>
130 <div class=
"wy-nav-content">
132 <div class=
"rst-content">
150 <div role=
"navigation" aria-label=
"breadcrumbs navigation">
152 <ul class=
"wy-breadcrumbs">
154 <li><a href=
"index.html">Docs
</a> »</li>
156 <li>C/C++ Client Library for memcached
</li>
159 <li class=
"wy-breadcrumbs-aside">
170 <div role=
"main" class=
"document" itemscope=
"itemscope" itemtype=
"http://schema.org/Article">
171 <div itemprop=
"articleBody">
173 <div class=
"section" id=
"c-c-client-library-for-memcached">
174 <h1>C/C++ Client Library for memcached
<a class=
"headerlink" href=
"#c-c-client-library-for-memcached" title=
"Permalink to this headline">¶
</a></h1>
175 <div class=
"section" id=
"synopsis">
176 <h2>SYNOPSIS
<a class=
"headerlink" href=
"#synopsis" title=
"Permalink to this headline">¶
</a></h2>
178 <dt>#include
<libmemcached/memcached.h
></dt><dd><p>Compile and link with -lmemcached
</p>
181 <hr class=
"docutils" />
182 <p><code class=
"xref cpp cpp-any docutils literal notranslate"><span class=
"pre">libmemcached
</span></code> is an open source C/C++ client library and tools for the
183 memcached server (
<a class=
"reference external" href=
"http://memcached.org/">http://memcached.org/
</a>). It has been designed to be light on
184 memory usage, thread safe, and provide full access to server side methods.
</p>
185 <p><code class=
"xref cpp cpp-any docutils literal notranslate"><span class=
"pre">libmemcached
</span></code> was designed to provide the greatest number of options to use
186 Memcached. Some of the features provided:
</p>
187 <ol class=
"arabic simple">
188 <li><p>Asynchronous and Synchronous Transport Support.
</p></li>
189 <li><p>Consistent Hashing and Distribution.
</p></li>
190 <li><p>Tunable Hashing algorithm to match keys.
</p></li>
191 <li><p>Access to large object support.
</p></li>
192 <li><p>Local replication.
</p></li>
193 <li><p>A complete reference guide and documentation to the API.
</p></li>
194 <li><p>Tools to Manage your Memcached networks.
</p></li>
197 <div class=
"section" id=
"description">
198 <h2>DESCRIPTION
<a class=
"headerlink" href=
"#description" title=
"Permalink to this headline">¶
</a></h2>
199 <p>“Memcached is a high-performance, distributed memory object caching system,
200 generic in nature, but intended for use in speeding up dynamic web applications
201 by alleviating database load.”
<a class=
"reference external" href=
"http://memcached.org/">http://memcached.org/
</a></p>
202 <p><code class=
"xref cpp cpp-any docutils literal notranslate"><span class=
"pre">libmemcached
</span></code> is a small, thread-safe client library for the memcached
203 protocol. The code has all been written to allow for both web and embedded
204 usage. It handles the work behind routing individual keys to specific servers
205 specified by the developer (and values are matched based on server order as
206 supplied by the user). It implements a modular and consistent method of object
208 <p>There are multiple implemented routing and hashing methods. See the
209 <a class=
"reference internal" href=
"libmemcached/memcached_behavior.html#_CPPv422memcached_behavior_setP12memcached_st20memcached_behavior_t8uint64_t" title=
"memcached_behavior_set"><code class=
"xref cpp cpp-any docutils literal notranslate"><span class=
"pre">memcached_behavior_set()
</span></code></a> manpage for more information.
</p>
210 <p>All operations are performed against a
<a class=
"reference internal" href=
"libmemcached/memcached_create.html#_CPPv412memcached_st" title=
"memcached_st"><code class=
"xref cpp cpp-any docutils literal notranslate"><span class=
"pre">memcached_st
</span></code></a> structure. These
211 structures can either be dynamically allocated or statically allocated and then
212 initialized by
<a class=
"reference internal" href=
"libmemcached/memcached_create.html#_CPPv416memcached_createP12memcached_st" title=
"memcached_create"><code class=
"xref cpp cpp-any docutils literal notranslate"><span class=
"pre">memcached_create()
</span></code></a>. Functions have been written in order to
213 encapsulate the
<a class=
"reference internal" href=
"libmemcached/memcached_create.html#_CPPv412memcached_st" title=
"memcached_st"><code class=
"xref cpp cpp-any docutils literal notranslate"><span class=
"pre">memcached_st
</span></code></a>. It is not recommended that you operate directly
214 against the structure.
</p>
215 <p>Nearly all functions return a
<a class=
"reference internal" href=
"libmemcached/memcached_return_t.html#_CPPv418memcached_return_t" title=
"memcached_return_t"><code class=
"xref cpp cpp-any docutils literal notranslate"><span class=
"pre">memcached_return_t
</span></code></a> value. This value can be
216 translated to a printable string with
<a class=
"reference internal" href=
"libmemcached/memcached_strerror.html#_CPPv418memcached_strerrorP12memcached_st18memcached_return_t" title=
"memcached_strerror"><code class=
"xref cpp cpp-any docutils literal notranslate"><span class=
"pre">memcached_strerror()
</span></code></a>.
</p>
217 <p>Objects are stored on servers by hashing keys. The hash value maps the key to a
218 particular server. All clients understand how this hashing works, so it is
219 possibly to reliably both push data to a server and retrieve data from a server.
</p>
220 <p>Group keys can be optionally used to group sets of objects with servers.
</p>
221 <p>Namespaces are supported, and can be used to partition caches so that multiple
222 applications can use the same memcached servers.
</p>
223 <p>Some features of the library must be enabled through
<a class=
"reference internal" href=
"libmemcached/memcached_behavior.html#_CPPv422memcached_behavior_setP12memcached_st20memcached_behavior_t8uint64_t" title=
"memcached_behavior_set"><code class=
"xref cpp cpp-any docutils literal notranslate"><span class=
"pre">memcached_behavior_set()
</span></code></a>.
</p>
225 <div class=
"section" id=
"threads-and-processes">
226 <h2>THREADS AND PROCESSES
<a class=
"headerlink" href=
"#threads-and-processes" title=
"Permalink to this headline">¶
</a></h2>
227 <p>No global variables are used in this library.
</p>
228 <p><a class=
"reference internal" href=
"libmemcached/memcached_create.html#_CPPv412memcached_st" title=
"memcached_st"><code class=
"xref cpp cpp-any docutils literal notranslate"><span class=
"pre">memcached_st
</span></code></a> structures are thread-safe, but when using threads or forked
229 processes it is important to keep one instance of
<a class=
"reference internal" href=
"libmemcached/memcached_create.html#_CPPv412memcached_st" title=
"memcached_st"><code class=
"xref cpp cpp-any docutils literal notranslate"><span class=
"pre">memcached_st
</span></code></a> per process or
230 thread. Without creating your own locking structures you can not share a single
231 <a class=
"reference internal" href=
"libmemcached/memcached_create.html#_CPPv412memcached_st" title=
"memcached_st"><code class=
"xref cpp cpp-any docutils literal notranslate"><span class=
"pre">memcached_st
</span></code></a>. However, you can call
<a class=
"reference internal" href=
"libmemcached/memcached_quit.html#_CPPv414memcached_quitP12memcached_st" title=
"memcached_quit"><code class=
"xref cpp cpp-any docutils literal notranslate"><span class=
"pre">memcached_quit()
</span></code></a> on a
<a class=
"reference internal" href=
"libmemcached/memcached_create.html#_CPPv412memcached_st" title=
"memcached_st"><code class=
"xref cpp cpp-any docutils literal notranslate"><span class=
"pre">memcached_st
</span></code></a> and
232 then use the resulting cloned structure.
</p>
234 <div class=
"section" id=
"systemtap">
235 <h2>SYSTEMTAP
<a class=
"headerlink" href=
"#systemtap" title=
"Permalink to this headline">¶
</a></h2>
236 <p><code class=
"xref cpp cpp-any docutils literal notranslate"><span class=
"pre">libmemcached
</span></code> can be built to support Systemtap on Linux when enabled at
238 <p>Please see
<em class=
"manpage"><a class=
"manpage reference external" href=
"http://man7.org/linux/man-pages/man1/stap.1.html">stap(
1)
</a></em> and
<em class=
"manpage"><a class=
"manpage reference external" href=
"http://man7.org/linux/man-pages/man1/dtrace.1.html">dtrace(
1)
</a></em> for more information
241 <div class=
"section" id=
"client-programs">
242 <h2>CLIENT PROGRAMS
<a class=
"headerlink" href=
"#client-programs" title=
"Permalink to this headline">¶
</a></h2>
243 <p><code class=
"xref cpp cpp-any docutils literal notranslate"><span class=
"pre">libmemcached
</span></code> comes with a few useful client programs:
</p>
245 <li><p><a class=
"reference internal" href=
"bin/memaslap.html"><span class=
"doc">memaslap - Load testing and benchmarking a server
</span></a></p></li>
246 <li><p><a class=
"reference internal" href=
"bin/memcapable.html"><span class=
"doc">memcapable - Checking a Memcached server capabilities and compatibility
</span></a></p></li>
247 <li><p><a class=
"reference internal" href=
"bin/memcat.html"><span class=
"doc">memcat - “cat” data from a server
</span></a></p></li>
248 <li><p><a class=
"reference internal" href=
"bin/memcp.html"><span class=
"doc">memcp - Copy data to a server
</span></a></p></li>
249 <li><p><a class=
"reference internal" href=
"bin/memdump.html"><span class=
"doc">memdump - Dumping your server
</span></a></p></li>
250 <li><p><a class=
"reference internal" href=
"bin/memerror.html"><span class=
"doc">memerror - translate an error code to a string
</span></a></p></li>
251 <li><p><a class=
"reference internal" href=
"bin/memexist.html"><span class=
"doc">memexist - Check for the existence of a key
</span></a></p></li>
252 <li><p><a class=
"reference internal" href=
"bin/memflush.html"><span class=
"doc">memflush - flush all data from a server
</span></a></p></li>
253 <li><p><a class=
"reference internal" href=
"bin/memparse.html"><span class=
"doc">memparse - Parse an option string
</span></a></p></li>
254 <li><p><a class=
"reference internal" href=
"bin/memping.html"><span class=
"doc">memping - Test to see if a server is available.
</span></a></p></li>
255 <li><p><a class=
"reference internal" href=
"bin/memrm.html"><span class=
"doc">memrm - Remove data from a server
</span></a></p></li>
256 <li><p><a class=
"reference internal" href=
"bin/memslap.html"><span class=
"doc">memslap - Load testing and benchmarking a server
</span></a></p></li>
257 <li><p><a class=
"reference internal" href=
"bin/memstat.html"><span class=
"doc">memstat - Gather statistics from a server
</span></a></p></li>
258 <li><p><a class=
"reference internal" href=
"bin/memtouch.html"><span class=
"doc">memtouch - Touches a key.
</span></a></p></li>
261 <div class=
"section" id=
"utility-libraries">
262 <h2>UTILITY LIBRARIES
<a class=
"headerlink" href=
"#utility-libraries" title=
"Permalink to this headline">¶
</a></h2>
264 <li><p><a class=
"reference internal" href=
"libhashkit.html"><span class=
"doc">libhashkit - C/C++ hashing library
</span></a></p></li>
265 <li><p><a class=
"reference internal" href=
"libmemcachedutil.html"><span class=
"doc">libmemcachedutil - C/C++ utilities extending libmemcached
</span></a></p></li>
268 <div class=
"section" id=
"see-also">
269 <h2>SEE ALSO
<a class=
"headerlink" href=
"#see-also" title=
"Permalink to this headline">¶
</a></h2>
271 <li><p><em class=
"manpage"><a class=
"manpage reference external" href=
"http://man7.org/linux/man-pages/man1/memcached.1.html">memcached(
1)
</a></em></p></li>
272 <li><p><a class=
"reference internal" href=
"libmemcached/configuration.html"><span class=
"doc">libmemcached Configuration
</span></a></p></li>
273 <li><p><a class=
"reference internal" href=
"libmemcached/examples.html"><span class=
"doc">libmemcached Examples
</span></a></p></li>
284 <div class=
"rst-footer-buttons" role=
"navigation" aria-label=
"footer navigation">
286 <a href=
"libmemcached/index.html" class=
"btn btn-neutral float-right" title=
"libmemcached API" accesskey=
"n" rel=
"next">Next
<span class=
"fa fa-arrow-circle-right"></span></a>
289 <a href=
"index.html" class=
"btn btn-neutral float-left" title=
"libmemcached Manual" accesskey=
"p" rel=
"prev"><span class=
"fa fa-arrow-circle-left"></span> Previous
</a>
296 <div role=
"contentinfo">
298 © <a href=
"copyright.html">Copyright
</a>
302 Built with
<a href=
"http://sphinx-doc.org/">Sphinx
</a> using a
<a href=
"https://github.com/rtfd/sphinx_rtd_theme">theme
</a> provided by
<a href=
"https://readthedocs.org">Read the Docs
</a>.
315 <script type=
"text/javascript">
317 SphinxRtdTheme.Navigation.enable(true);