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>Managing lists of servers
— 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 type=
"text/javascript" src=
"../_static/jquery.js"></script>
25 <script type=
"text/javascript" src=
"../_static/underscore.js"></script>
26 <script type=
"text/javascript" src=
"../_static/doctools.js"></script>
27 <script type=
"text/javascript" 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=
"Managing the servers used by memcached_st" href=
"memcached_servers.html" />
40 <link rel=
"prev" title=
"Servers and Server Lists" href=
"index_advanced_servers.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"><a class=
"reference internal" href=
"../libmemcached.html">Introduction
</a></li>
91 <li class=
"toctree-l1 current"><a class=
"reference internal" href=
"index.html">libmemcached API
</a><ul class=
"current">
92 <li class=
"toctree-l2"><a class=
"reference internal" href=
"index_basics.html">Basics
</a></li>
93 <li class=
"toctree-l2"><a class=
"reference internal" href=
"index_data.html">Working with Data
</a></li>
94 <li class=
"toctree-l2"><a class=
"reference internal" href=
"index_errors.html">Messages and Errors
</a></li>
95 <li class=
"toctree-l2 current"><a class=
"reference internal" href=
"index_advanced.html">Advanced Topics
</a><ul class=
"current">
96 <li class=
"toctree-l3"><a class=
"reference internal" href=
"index_advanced_internals.html">Internal Behavior
</a></li>
97 <li class=
"toctree-l3"><a class=
"reference internal" href=
"index_advanced_aeh.html">Authentication, Encryption
& Hashing
</a></li>
98 <li class=
"toctree-l3 current"><a class=
"reference internal" href=
"index_advanced_servers.html">Servers and Server Lists
</a><ul class=
"current">
99 <li class=
"toctree-l4 current"><a class=
"current reference internal" href=
"#">Managing lists of servers
</a></li>
100 <li class=
"toctree-l4"><a class=
"reference internal" href=
"memcached_servers.html">Managing the servers used by memcached_st
</a></li>
103 <li class=
"toctree-l3"><a class=
"reference internal" href=
"index_advanced_daemon.html">Affecting the memcached Daemon
</a></li>
104 <li class=
"toctree-l3"><a class=
"reference internal" href=
"index_advanced_stats.html">Statistics
</a></li>
107 <li class=
"toctree-l2"><a class=
"reference internal" href=
"index_deprecated.html">Deprecated Functionality
</a></li>
110 <li class=
"toctree-l1"><a class=
"reference internal" href=
"index_misc.html">Misc
</a></li>
112 <p class=
"caption"><span class=
"caption-text">libmemcachedutil
</span></p>
114 <li class=
"toctree-l1"><a class=
"reference internal" href=
"../libmemcachedutil.html">Introduction
</a></li>
115 <li class=
"toctree-l1"><a class=
"reference internal" href=
"../libmemcachedutil/index.html">libmemcachedutil API
</a></li>
117 <p class=
"caption"><span class=
"caption-text">libhashkit
</span></p>
119 <li class=
"toctree-l1"><a class=
"reference internal" href=
"../libhashkit.html">Introduction
</a></li>
120 <li class=
"toctree-l1"><a class=
"reference internal" href=
"../libhashkit/index.html">libhashkit API
</a></li>
122 <p class=
"caption"><span class=
"caption-text">Client Applications
</span></p>
124 <li class=
"toctree-l1"><a class=
"reference internal" href=
"../bin/index.html">Client Applications
</a></li>
126 <p class=
"caption"><span class=
"caption-text">Copyright
</span></p>
128 <li class=
"toctree-l1"><a class=
"reference internal" href=
"../copyright.html">Copyright
</a></li>
137 <section data-toggle=
"wy-nav-shift" class=
"wy-nav-content-wrap">
140 <nav class=
"wy-nav-top" aria-label=
"top navigation">
142 <i data-toggle=
"wy-nav-top" class=
"fa fa-bars"></i>
143 <a href=
"../index.html">libmemcached
</a>
148 <div class=
"wy-nav-content">
150 <div class=
"rst-content">
168 <div role=
"navigation" aria-label=
"breadcrumbs navigation">
170 <ul class=
"wy-breadcrumbs">
172 <li><a href=
"../index.html">Docs
</a> »</li>
174 <li><a href=
"index.html">libmemcached API
</a> »</li>
176 <li><a href=
"index_advanced.html">Advanced Topics
</a> »</li>
178 <li><a href=
"index_advanced_servers.html">Servers and Server Lists
</a> »</li>
180 <li>Managing lists of servers
</li>
183 <li class=
"wy-breadcrumbs-aside">
194 <div role=
"main" class=
"document" itemscope=
"itemscope" itemtype=
"http://schema.org/Article">
195 <div itemprop=
"articleBody">
197 <div class=
"section" id=
"managing-lists-of-servers">
198 <h1>Managing lists of servers
<a class=
"headerlink" href=
"#managing-lists-of-servers" title=
"Permalink to this headline">¶
</a></h1>
199 <div class=
"section" id=
"synopsis">
200 <h2>SYNOPSIS
<a class=
"headerlink" href=
"#synopsis" title=
"Permalink to this headline">¶
</a></h2>
201 <dl class=
"docutils">
202 <dt>#include
<libmemcached/memcached.h
></dt>
203 <dd>Compile and link with -lmemcached
</dd>
206 <dt id=
"c.memcached_instance_st">
207 struct
<a class=
"reference internal" href=
"#c.memcached_instance_st" title=
"memcached_instance_st">memcached_instance_st
</a> <code class=
"descname">memcached_instance_st
</code><a class=
"headerlink" href=
"#c.memcached_instance_st" title=
"Permalink to this definition">¶
</a></dt>
211 <dt id=
"c.memcached_server_st">
212 struct
<a class=
"reference internal" href=
"#c.memcached_server_st" title=
"memcached_server_st">memcached_server_st
</a> <code class=
"descname">memcached_server_st
</code><a class=
"headerlink" href=
"#c.memcached_server_st" title=
"Permalink to this definition">¶
</a></dt>
216 <dt id=
"c.memcached_server_list_st">
217 struct
<a class=
"reference internal" href=
"#c.memcached_server_st" title=
"memcached_server_st">memcached_server_st
</a> *
<code class=
"descname">memcached_server_list_st
</code><a class=
"headerlink" href=
"#c.memcached_server_list_st" title=
"Permalink to this definition">¶
</a></dt>
220 <dl class=
"function">
221 <dt id=
"_CPPv426memcached_server_list_free24memcached_server_list_st">
222 <span id=
"_CPPv326memcached_server_list_free24memcached_server_list_st"></span><span id=
"_CPPv226memcached_server_list_free24memcached_server_list_st"></span><span id=
"memcached_server_list_free__memcached_server_list_st"></span>void
<code class=
"descname">memcached_server_list_free
</code><span class=
"sig-paren">(
</span>memcached_server_list_st
<em>list
</em><span class=
"sig-paren">)
</span><a class=
"headerlink" href=
"#_CPPv426memcached_server_list_free24memcached_server_list_st" title=
"Permalink to this definition">¶
</a><br /></dt>
223 <dd><table class=
"docutils field-list" frame=
"void" rules=
"none">
224 <col class=
"field-name" />
225 <col class=
"field-body" />
227 <tr class=
"field-odd field"><th class=
"field-name">Parameters:
</th><td class=
"field-body"><strong>list
</strong> -- instance of initialized
<code class=
"xref cpp cpp-any docutils literal notranslate"><span class=
"pre">memcached_server_list_st
</span></code> object
</td>
233 <dl class=
"function">
234 <dt id=
"_CPPv428memcached_server_list_append24memcached_server_list_stPKc9in_port_tP18memcached_return_t">
235 <span id=
"_CPPv328memcached_server_list_append24memcached_server_list_stPKc9in_port_tP18memcached_return_t"></span><span id=
"_CPPv228memcached_server_list_append24memcached_server_list_stPKc9in_port_tP18memcached_return_t"></span><span id=
"memcached_server_list_append__memcached_server_list_st.cCP.in_port_t.memcached_return_tP"></span>memcached_server_list_st
<code class=
"descname">memcached_server_list_append
</code><span class=
"sig-paren">(
</span>memcached_server_list_st
<em>list
</em>,
<em class=
"property">const
</em> char *
<em>hostname
</em>, in_port_t
<em>port
</em>,
<a class=
"reference internal" href=
"memcached_return_t.html#_CPPv418memcached_return_t" title=
"memcached_return_t">memcached_return_t
</a> *
<em>error
</em><span class=
"sig-paren">)
</span><a class=
"headerlink" href=
"#_CPPv428memcached_server_list_append24memcached_server_list_stPKc9in_port_tP18memcached_return_t" title=
"Permalink to this definition">¶
</a><br /></dt>
236 <dd><table class=
"docutils field-list" frame=
"void" rules=
"none">
237 <col class=
"field-name" />
238 <col class=
"field-body" />
240 <tr class=
"field-odd field"><th class=
"field-name">Parameters:
</th><td class=
"field-body"><ul class=
"first simple">
241 <li><strong>list
</strong> -- instance of an existing
<code class=
"xref cpp cpp-any docutils literal notranslate"><span class=
"pre">memcached_server_list_st
</span></code> or nullptr to create one
</li>
242 <li><strong>hostname
</strong> -- the hostname or path to the socket, defaults to localhost if null
</li>
243 <li><strong>port
</strong> -- the port to use, defaults to
11211 if
0</li>
244 <li><strong>error
</strong> -- pointer to store any
<a class=
"reference internal" href=
"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> error indicating success
</li>
248 <tr class=
"field-even field"><th class=
"field-name">Returns:
</th><td class=
"field-body"><p class=
"first last">new instance of
<code class=
"xref cpp cpp-any docutils literal notranslate"><span class=
"pre">memcached_server_list_st
</span></code> on success or nullptr on failure
</p>
255 <dl class=
"function">
256 <dt id=
"_CPPv427memcached_server_list_count24memcached_server_list_st">
257 <span id=
"_CPPv327memcached_server_list_count24memcached_server_list_st"></span><span id=
"_CPPv227memcached_server_list_count24memcached_server_list_st"></span><span id=
"memcached_server_list_count__memcached_server_list_st"></span>uint32_t
<code class=
"descname">memcached_server_list_count
</code><span class=
"sig-paren">(
</span>memcached_server_list_st
<em>list
</em><span class=
"sig-paren">)
</span><a class=
"headerlink" href=
"#_CPPv427memcached_server_list_count24memcached_server_list_st" title=
"Permalink to this definition">¶
</a><br /></dt>
258 <dd><table class=
"docutils field-list" frame=
"void" rules=
"none">
259 <col class=
"field-name" />
260 <col class=
"field-body" />
262 <tr class=
"field-odd field"><th class=
"field-name">Parameters:
</th><td class=
"field-body"><strong>list
</strong> -- instance of
<code class=
"xref cpp cpp-any docutils literal notranslate"><span class=
"pre">memcached_server_list_st
</span></code></td>
264 <tr class=
"field-even field"><th class=
"field-name">Returns:
</th><td class=
"field-body">count of servers in the list
</td>
270 <dl class=
"function">
271 <dt id=
"_CPPv422memcached_server_errorPK21memcached_instance_st">
272 <span id=
"_CPPv322memcached_server_errorPK21memcached_instance_st"></span><span id=
"_CPPv222memcached_server_errorPK21memcached_instance_st"></span><span id=
"memcached_server_error__memcached_instance_stCP"></span><em class=
"property">const
</em> char *
<code class=
"descname">memcached_server_error
</code><span class=
"sig-paren">(
</span><em class=
"property">const
</em> memcached_instance_st *
<em>instance
</em><span class=
"sig-paren">)
</span><a class=
"headerlink" href=
"#_CPPv422memcached_server_errorPK21memcached_instance_st" title=
"Permalink to this definition">¶
</a><br /></dt>
273 <dd><table class=
"docutils field-list" frame=
"void" rules=
"none">
274 <col class=
"field-name" />
275 <col class=
"field-body" />
277 <tr class=
"field-odd field"><th class=
"field-name">Parameters:
</th><td class=
"field-body"><strong>instance
</strong> -- pointer to an initialized
<code class=
"xref cpp cpp-any docutils literal notranslate"><span class=
"pre">memcached_instance_st
</span></code> object
</td>
279 <tr class=
"field-even field"><th class=
"field-name">Returns:
</th><td class=
"field-body">last error message sent from the server to the client
</td>
285 <dl class=
"function">
286 <dt id=
"_CPPv428memcached_server_error_resetPK21memcached_instance_st">
287 <span id=
"_CPPv328memcached_server_error_resetPK21memcached_instance_st"></span><span id=
"_CPPv228memcached_server_error_resetPK21memcached_instance_st"></span><span id=
"memcached_server_error_reset__memcached_instance_stCP"></span>void
<code class=
"descname">memcached_server_error_reset
</code><span class=
"sig-paren">(
</span><em class=
"property">const
</em> memcached_instance_st *
<em>list
</em><span class=
"sig-paren">)
</span><a class=
"headerlink" href=
"#_CPPv428memcached_server_error_resetPK21memcached_instance_st" title=
"Permalink to this definition">¶
</a><br /></dt>
288 <dd><div class=
"deprecated">
289 <p><span class=
"versionmodified">Deprecated since version
0.39.
</span></p>
293 <dl class=
"function">
294 <dt id=
"_CPPv423memcached_servers_parsev">
295 <span id=
"_CPPv323memcached_servers_parsev"></span><span id=
"_CPPv223memcached_servers_parsev"></span><span id=
"memcached_servers_parse"></span>void
<code class=
"descname">memcached_servers_parse
</code><span class=
"sig-paren">(
</span><span class=
"sig-paren">)
</span><a class=
"headerlink" href=
"#_CPPv423memcached_servers_parsev" title=
"Permalink to this definition">¶
</a><br /></dt>
296 <dd><div class=
"deprecated">
297 <p><span class=
"versionmodified">Deprecated since version
0.39.
</span></p>
299 <p>See
<a class=
"reference internal" href=
"configuration.html#_CPPv49memcachedPKc6size_t" title=
"memcached"><code class=
"xref cpp cpp-any docutils literal notranslate"><span class=
"pre">memcached()
</span></code></a>.
</p>
303 <div class=
"section" id=
"description">
304 <h2>DESCRIPTION
<a class=
"headerlink" href=
"#description" title=
"Permalink to this headline">¶
</a></h2>
305 <p><code class=
"xref cpp cpp-any docutils literal notranslate"><span class=
"pre">libmemcached
</span></code> operates on a list of hosts which are stored in
306 <code class=
"xref cpp cpp-type docutils literal notranslate"><span class=
"pre">memcached_server_st
</span></code> structures. You should not modify these structures
307 directly. Functions are provided to modify these structures.
</p>
308 <p><code class=
"xref cpp cpp-func docutils literal notranslate"><span class=
"pre">memcached_server_list()
</span></code> is used to provide an array of all defined hosts.
309 This was incorrectly documented as
"requiring free
" up till version
0.39.
</p>
310 <p><a class=
"reference internal" href=
"#_CPPv426memcached_server_list_free24memcached_server_list_st" title=
"memcached_server_list_free"><code class=
"xref cpp cpp-func docutils literal notranslate"><span class=
"pre">memcached_server_list_free()
</span></code></a> deallocates all memory associated with the
311 array of
<code class=
"xref cpp cpp-type docutils literal notranslate"><span class=
"pre">memcached_server_st
</span></code> that you passed to it.
</p>
312 <p><a class=
"reference internal" href=
"#_CPPv428memcached_server_list_append24memcached_server_list_stPKc9in_port_tP18memcached_return_t" title=
"memcached_server_list_append"><code class=
"xref cpp cpp-func docutils literal notranslate"><span class=
"pre">memcached_server_list_append()
</span></code></a> adds a server to the end of a
313 <code class=
"xref cpp cpp-type docutils literal notranslate"><span class=
"pre">memcached_server_st
</span></code> array. On error null will be returned and the
314 <a class=
"reference internal" href=
"memcached_return_t.html#_CPPv418memcached_return_t" title=
"memcached_return_t"><code class=
"xref cpp cpp-type docutils literal notranslate"><span class=
"pre">memcached_return_t
</span></code></a> pointer you passed into the function will be set with the appropriate error. If the value of port is zero, it is set to the default
315 port of a memcached server.
</p>
316 <p>DEPRECATED
<a class=
"reference internal" href=
"#_CPPv423memcached_servers_parsev" title=
"memcached_servers_parse"><code class=
"xref cpp cpp-func docutils literal notranslate"><span class=
"pre">memcached_servers_parse()
</span></code></a>, please see
<a class=
"reference internal" href=
"configuration.html#_CPPv49memcachedPKc6size_t" title=
"memcached"><code class=
"xref cpp cpp-func docutils literal notranslate"><span class=
"pre">memcached()
</span></code></a></p>
317 <p><a class=
"reference internal" href=
"#_CPPv422memcached_server_errorPK21memcached_instance_st" title=
"memcached_server_error"><code class=
"xref cpp cpp-func docutils literal notranslate"><span class=
"pre">memcached_server_error()
</span></code></a> can be used to look at the text of the last
318 error message sent by the server to to the client.
</p>
319 <p>Before version
0.39 theses functions used a memcached_server_st *. In
0.39
320 memcached_server_st * was aliased to
<code class=
"xref cpp cpp-type docutils literal notranslate"><span class=
"pre">memcached_server_list_st
</span></code>.
321 This was done for a style reason to help clean up some concepts in the code.
</p>
323 <div class=
"section" id=
"return-value">
324 <h2>RETURN VALUE
<a class=
"headerlink" href=
"#return-value" title=
"Permalink to this headline">¶
</a></h2>
325 <p>Varies, see particular functions.
</p>
327 <div class=
"section" id=
"see-also">
328 <h2>SEE ALSO
<a class=
"headerlink" href=
"#see-also" title=
"Permalink to this headline">¶
</a></h2>
330 <li><em class=
"manpage"><a class=
"manpage reference external" href=
"https://linux.die.net/man/1/memcached">memcached(
1)
</a></em></li>
331 <li><a class=
"reference internal" href=
"../libmemcached.html"><span class=
"doc">C/C++ Client Library for memcached
</span></a></li>
332 <li><a class=
"reference internal" href=
"memcached_servers.html"><span class=
"doc">Managing the servers used by memcached_st
</span></a></li>
333 <li><a class=
"reference internal" href=
"memcached_strerror.html"><span class=
"doc">Converting Error Codes to Messages
</span></a></li>
344 <div class=
"rst-footer-buttons" role=
"navigation" aria-label=
"footer navigation">
346 <a href=
"memcached_servers.html" class=
"btn btn-neutral float-right" title=
"Managing the servers used by memcached_st" accesskey=
"n" rel=
"next">Next
<span class=
"fa fa-arrow-circle-right"></span></a>
349 <a href=
"index_advanced_servers.html" class=
"btn btn-neutral float-left" title=
"Servers and Server Lists" accesskey=
"p" rel=
"prev"><span class=
"fa fa-arrow-circle-left"></span> Previous
</a>
356 <div role=
"contentinfo">
358 © <a href=
"../copyright.html">Copyright
</a>
362 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>.
375 <script type=
"text/javascript">
377 SphinxRtdTheme.Navigation.enable(true);