update docs
[m6w6/libmemcached] / libmemcached / memcached_servers.html
1
2
3 <!DOCTYPE html>
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]-->
6 <head>
7 <meta charset="utf-8">
8
9 <meta name="viewport" content="width=device-width, initial-scale=1.0">
10
11 <title>Manipulate the server information stored in memcached_st &mdash; libmemcached 1.0.99 documentation</title>
12
13
14
15
16
17
18
19
20 <script type="text/javascript" src="../_static/js/modernizr.min.js"></script>
21
22
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>
28
29 <script type="text/javascript" src="../_static/js/theme.js"></script>
30
31
32
33
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="Affecting the memcached Daemon" href="index_advanced_daemon.html" />
40 <link rel="prev" title="Managing lists of servers" href="memcached_server_st.html" />
41 </head>
42
43 <body class="wy-body-for-nav">
44
45
46 <div class="wy-grid-for-nav">
47
48 <nav data-toggle="wy-nav-shift" class="wy-nav-side">
49 <div class="wy-side-scroll">
50 <div class="wy-side-nav-search" >
51
52
53
54 <a href="../index.html" class="icon icon-home"> libmemcached
55
56
57
58 </a>
59
60
61
62
63 <div class="version">
64 1.0
65 </div>
66
67
68
69
70 <div role="search">
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" />
75 </form>
76 </div>
77
78
79 </div>
80
81 <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
82
83
84
85
86
87
88 <p class="caption"><span class="caption-text">libmemcached</span></p>
89 <ul class="current">
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 &amp; 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"><a class="reference internal" href="memcached_server_st.html">Managing lists of servers</a></li>
100 <li class="toctree-l4 current"><a class="current reference internal" href="#">Manipulate the server information stored in memcached_st</a></li>
101 </ul>
102 </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>
105 </ul>
106 </li>
107 <li class="toctree-l2"><a class="reference internal" href="index_deprecated.html">Deprecated Functionality</a></li>
108 </ul>
109 </li>
110 <li class="toctree-l1"><a class="reference internal" href="index_misc.html">Misc</a></li>
111 </ul>
112 <p class="caption"><span class="caption-text">libmemcachedutil</span></p>
113 <ul>
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>
116 </ul>
117 <p class="caption"><span class="caption-text">libhashkit</span></p>
118 <ul>
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>
121 </ul>
122 <p class="caption"><span class="caption-text">Client Applications</span></p>
123 <ul>
124 <li class="toctree-l1"><a class="reference internal" href="../bin/index.html">Client Applications</a></li>
125 </ul>
126 <p class="caption"><span class="caption-text">Copyright</span></p>
127 <ul>
128 <li class="toctree-l1"><a class="reference internal" href="../copyright.html">Copyright</a></li>
129 </ul>
130
131
132
133 </div>
134 </div>
135 </nav>
136
137 <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
138
139
140 <nav class="wy-nav-top" aria-label="top navigation">
141
142 <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
143 <a href="../index.html">libmemcached</a>
144
145 </nav>
146
147
148 <div class="wy-nav-content">
149
150 <div class="rst-content">
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168 <div role="navigation" aria-label="breadcrumbs navigation">
169
170 <ul class="wy-breadcrumbs">
171
172 <li><a href="../index.html">Docs</a> &raquo;</li>
173
174 <li><a href="index.html">libmemcached API</a> &raquo;</li>
175
176 <li><a href="index_advanced.html">Advanced Topics</a> &raquo;</li>
177
178 <li><a href="index_advanced_servers.html">Servers and Server Lists</a> &raquo;</li>
179
180 <li>Manipulate the server information stored in memcached_st</li>
181
182
183 <li class="wy-breadcrumbs-aside">
184
185
186
187 </li>
188
189 </ul>
190
191
192 <hr/>
193 </div>
194 <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
195 <div itemprop="articleBody">
196
197 <div class="section" id="manipulate-the-server-information-stored-in-memcached-st">
198 <h1>Manipulate the server information stored in memcached_st<a class="headerlink" href="#manipulate-the-server-information-stored-in-memcached-st" 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 <p>#include &lt;libmemcached/memcached.h&gt;</p>
202 <dl class="cpp type">
203 <dt id="_CPPv419memcached_server_fn">
204 <span id="_CPPv319memcached_server_fn"></span><span id="_CPPv219memcached_server_fn"></span><span id="memcached_server_fn"></span><em class="property">type </em><code class="sig-name descname">memcached_server_fn</code><a class="headerlink" href="#_CPPv419memcached_server_fn" title="Permalink to this definition"></a><br /></dt>
205 <dd></dd></dl>
206
207 <dl class="cpp function">
208 <dt id="_CPPv422memcached_server_countP12memcached_st">
209 <span id="_CPPv322memcached_server_countP12memcached_st"></span><span id="_CPPv222memcached_server_countP12memcached_st"></span><span id="memcached_server_count__memcached_stP"></span>uint32_t <code class="sig-name descname">memcached_server_count</code><span class="sig-paren">(</span><a class="reference internal" href="memcached_create.html#_CPPv412memcached_st" title="memcached_st">memcached_st</a> *<em>ptr</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv422memcached_server_countP12memcached_st" title="Permalink to this definition"></a><br /></dt>
210 <dd></dd></dl>
211
212 <dl class="cpp function">
213 <dt id="_CPPv420memcached_server_addP12memcached_stPKc9in_port_t">
214 <span id="_CPPv320memcached_server_addP12memcached_stPKc9in_port_t"></span><span id="_CPPv220memcached_server_addP12memcached_stPKc9in_port_t"></span><span id="memcached_server_add__memcached_stP.cCP.in_port_t"></span><a class="reference internal" href="memcached_return_t.html#_CPPv418memcached_return_t" title="memcached_return_t">memcached_return_t</a> <code class="sig-name descname">memcached_server_add</code><span class="sig-paren">(</span><a class="reference internal" href="memcached_create.html#_CPPv412memcached_st" title="memcached_st">memcached_st</a> *<em>ptr</em>, <em class="property">const</em> char *<em>hostname</em>, in_port_t <em>port</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv420memcached_server_addP12memcached_stPKc9in_port_t" title="Permalink to this definition"></a><br /></dt>
215 <dd></dd></dl>
216
217 <dl class="cpp function">
218 <dt id="_CPPv424memcached_server_add_udpP12memcached_stPKc9in_port_t">
219 <span id="_CPPv324memcached_server_add_udpP12memcached_stPKc9in_port_t"></span><span id="_CPPv224memcached_server_add_udpP12memcached_stPKc9in_port_t"></span><span id="memcached_server_add_udp__memcached_stP.cCP.in_port_t"></span><a class="reference internal" href="memcached_return_t.html#_CPPv418memcached_return_t" title="memcached_return_t">memcached_return_t</a> <code class="sig-name descname">memcached_server_add_udp</code><span class="sig-paren">(</span><a class="reference internal" href="memcached_create.html#_CPPv412memcached_st" title="memcached_st">memcached_st</a> *<em>ptr</em>, <em class="property">const</em> char *<em>hostname</em>, in_port_t <em>port</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv424memcached_server_add_udpP12memcached_stPKc9in_port_t" title="Permalink to this definition"></a><br /></dt>
220 <dd></dd></dl>
221
222 <dl class="cpp function">
223 <dt id="_CPPv432memcached_server_add_unix_socketP12memcached_stPKc">
224 <span id="_CPPv332memcached_server_add_unix_socketP12memcached_stPKc"></span><span id="_CPPv232memcached_server_add_unix_socketP12memcached_stPKc"></span><span id="memcached_server_add_unix_socket__memcached_stP.cCP"></span><a class="reference internal" href="memcached_return_t.html#_CPPv418memcached_return_t" title="memcached_return_t">memcached_return_t</a> <code class="sig-name descname">memcached_server_add_unix_socket</code><span class="sig-paren">(</span><a class="reference internal" href="memcached_create.html#_CPPv412memcached_st" title="memcached_st">memcached_st</a> *<em>ptr</em>, <em class="property">const</em> char *<em>socket</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv432memcached_server_add_unix_socketP12memcached_stPKc" title="Permalink to this definition"></a><br /></dt>
225 <dd></dd></dl>
226
227 <dl class="cpp function">
228 <dt id="_CPPv421memcached_server_pushP12memcached_stPK19memcached_server_st">
229 <span id="_CPPv321memcached_server_pushP12memcached_stPK19memcached_server_st"></span><span id="_CPPv221memcached_server_pushP12memcached_stPK19memcached_server_st"></span><span id="memcached_server_push__memcached_stP.memcached_server_stCP"></span><a class="reference internal" href="memcached_return_t.html#_CPPv418memcached_return_t" title="memcached_return_t">memcached_return_t</a> <code class="sig-name descname">memcached_server_push</code><span class="sig-paren">(</span><a class="reference internal" href="memcached_create.html#_CPPv412memcached_st" title="memcached_st">memcached_st</a> *<em>ptr</em>, <em class="property">const</em> memcached_server_st *<em>list</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv421memcached_server_pushP12memcached_stPK19memcached_server_st" title="Permalink to this definition"></a><br /></dt>
230 <dd></dd></dl>
231
232 <dl class="cpp function">
233 <dt id="_CPPv423memcached_server_by_keyP12memcached_stPKc6size_tP18memcached_return_t">
234 <span id="_CPPv323memcached_server_by_keyP12memcached_stPKc6size_tP18memcached_return_t"></span><span id="_CPPv223memcached_server_by_keyP12memcached_stPKc6size_tP18memcached_return_t"></span><span id="memcached_server_by_key__memcached_stP.cCP.s.memcached_return_tP"></span><em class="property">const</em> memcached_instance_st *<code class="sig-name descname">memcached_server_by_key</code><span class="sig-paren">(</span><a class="reference internal" href="memcached_create.html#_CPPv412memcached_st" title="memcached_st">memcached_st</a> *<em>ptr</em>, <em class="property">const</em> char *<em>key</em>, size_t <em>key_length</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="#_CPPv423memcached_server_by_keyP12memcached_stPKc6size_tP18memcached_return_t" title="Permalink to this definition"></a><br /></dt>
235 <dd></dd></dl>
236
237 <dl class="cpp function">
238 <dt id="_CPPv436memcached_server_get_last_disconnectPK12memcached_st">
239 <span id="_CPPv336memcached_server_get_last_disconnectPK12memcached_st"></span><span id="_CPPv236memcached_server_get_last_disconnectPK12memcached_st"></span><span id="memcached_server_get_last_disconnect__memcached_stCP"></span><em class="property">const</em> memcached_instance_st *<code class="sig-name descname">memcached_server_get_last_disconnect</code><span class="sig-paren">(</span><em class="property">const</em> <a class="reference internal" href="memcached_create.html#_CPPv412memcached_st" title="memcached_st">memcached_st</a> *<em>ptr</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv436memcached_server_get_last_disconnectPK12memcached_st" title="Permalink to this definition"></a><br /></dt>
240 <dd></dd></dl>
241
242 <dl class="cpp function">
243 <dt id="_CPPv423memcached_server_cursorPK12memcached_stPK19memcached_server_fnPv8uint32_t">
244 <span id="_CPPv323memcached_server_cursorPK12memcached_stPK19memcached_server_fnPv8uint32_t"></span><span id="_CPPv223memcached_server_cursorPK12memcached_stPK19memcached_server_fnPv8uint32_t"></span><span id="memcached_server_cursor__memcached_stCP.memcached_server_fnCP.voidP.uint32_t"></span><a class="reference internal" href="memcached_return_t.html#_CPPv418memcached_return_t" title="memcached_return_t">memcached_return_t</a> <code class="sig-name descname">memcached_server_cursor</code><span class="sig-paren">(</span><em class="property">const</em> <a class="reference internal" href="memcached_create.html#_CPPv412memcached_st" title="memcached_st">memcached_st</a> *<em>ptr</em>, <em class="property">const</em> <a class="reference internal" href="#_CPPv419memcached_server_fn" title="memcached_server_fn">memcached_server_fn</a> *<em>callback</em>, void *<em>context</em>, uint32_t <em>number_of_callbacks</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv423memcached_server_cursorPK12memcached_stPK19memcached_server_fnPv8uint32_t" title="Permalink to this definition"></a><br /></dt>
245 <dd></dd></dl>
246
247 <p>compile and link with -lmemcached</p>
248 </div>
249 <div class="section" id="description">
250 <h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline"></a></h2>
251 <p><code class="xref cpp cpp-any docutils literal notranslate"><span class="pre">libmemcached</span></code> performs operations on a list of hosts. The order of
252 these hosts determine routing to keys. Functions are provided to add keys to
253 memcached_st structures. To manipulate lists of servers see
254 memcached_server_st(3).</p>
255 <p><a class="reference internal" href="#_CPPv422memcached_server_countP12memcached_st" title="memcached_server_count"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">memcached_server_count()</span></code></a> provides you a count of the current number of
256 servers being used by a <a class="reference internal" href="memcached_create.html#_CPPv412memcached_st" title="memcached_st"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">memcached_st</span></code></a> structure.</p>
257 <dl class="simple">
258 <dt><a class="reference internal" href="#_CPPv420memcached_server_addP12memcached_stPKc9in_port_t" title="memcached_server_add"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">memcached_server_add()</span></code></a> pushes a single TCP server into the <a class="reference internal" href="memcached_create.html#_CPPv412memcached_st" title="memcached_st"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">memcached_st</span></code></a> structure. This server will be placed at the end. Duplicate servers</dt><dd><p>are allowed, so duplication is not checked. Executing this function with the <code class="xref cpp cpp-any docutils literal notranslate"><span class="pre">MEMCACHED_BEHAVIOR_USE_UDP</span></code> behavior set will result in a <a class="reference internal" href="memcached_return_t.html#_CPPv4N18memcached_return_t31MEMCACHED_INVALID_HOST_PROTOCOLE" title="MEMCACHED_INVALID_HOST_PROTOCOL"><code class="xref cpp cpp-any docutils literal notranslate"><span class="pre">MEMCACHED_INVALID_HOST_PROTOCOL</span></code></a>.</p>
259 </dd>
260 </dl>
261 <p><a class="reference internal" href="#_CPPv424memcached_server_add_udpP12memcached_stPKc9in_port_t" title="memcached_server_add_udp"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">memcached_server_add_udp()</span></code></a> pushes a single UDP server into the <a class="reference internal" href="memcached_create.html#_CPPv412memcached_st" title="memcached_st"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">memcached_st</span></code></a> structure. This server will be placed at the end. Duplicate
262 servers are allowed, so duplication is not checked. Executing this function with out setting the <code class="xref cpp cpp-any docutils literal notranslate"><span class="pre">MEMCACHED_BEHAVIOR_USE_UDP</span></code> behavior will result in a
263 <a class="reference internal" href="memcached_return_t.html#_CPPv4N18memcached_return_t31MEMCACHED_INVALID_HOST_PROTOCOLE" title="MEMCACHED_INVALID_HOST_PROTOCOL"><code class="xref cpp cpp-any docutils literal notranslate"><span class="pre">MEMCACHED_INVALID_HOST_PROTOCOL</span></code></a>.</p>
264 <p><a class="reference internal" href="#_CPPv432memcached_server_add_unix_socketP12memcached_stPKc" title="memcached_server_add_unix_socket"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">memcached_server_add_unix_socket()</span></code></a> pushes a single UNIX socket into the <a class="reference internal" href="memcached_create.html#_CPPv412memcached_st" title="memcached_st"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">memcached_st</span></code></a> structure. This UNIX socket will be placed at the end.
265 Duplicate servers are allowed, so duplication is not checked. The length
266 of the filename must be one character less than <code class="xref cpp cpp-any docutils literal notranslate"><span class="pre">MEMCACHED_MAX_HOST_LENGTH</span></code>.</p>
267 <p><a class="reference internal" href="#_CPPv421memcached_server_pushP12memcached_stPK19memcached_server_st" title="memcached_server_push"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">memcached_server_push()</span></code></a> pushes an array of <code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">memcached_server_st</span></code> into the <a class="reference internal" href="memcached_create.html#_CPPv412memcached_st" title="memcached_st"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">memcached_st</span></code></a> structure. These servers will be placed at
268 the end. Duplicate servers are allowed, so duplication is not checked. A
269 copy is made of structure so the list provided (and any operations on
270 the list) are not saved.</p>
271 <p><a class="reference internal" href="#_CPPv423memcached_server_by_keyP12memcached_stPKc6size_tP18memcached_return_t" title="memcached_server_by_key"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">memcached_server_by_key()</span></code></a> allows you to provide a key and retrieve the
272 server which would be used for assignment.</p>
273 <p><a class="reference internal" href="#_CPPv436memcached_server_get_last_disconnectPK12memcached_st" title="memcached_server_get_last_disconnect"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">memcached_server_get_last_disconnect()</span></code></a> returns a pointer to the last
274 server for which there was a connection problem. It does not mean this
275 particular server is currently dead but if the library is reporting a server
276 is, the returned server is a very good candidate.</p>
277 <p><a class="reference internal" href="#_CPPv423memcached_server_cursorPK12memcached_stPK19memcached_server_fnPv8uint32_t" title="memcached_server_cursor"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">memcached_server_cursor()</span></code></a> takes a memcached_st and loops through the
278 list of hosts currently in the cursor calling the list of callback
279 functions provided. You can optionally pass in a value via
280 context which will be provided to each callback function. An error
281 return from any callback will terminate the loop. <a class="reference internal" href="#_CPPv423memcached_server_cursorPK12memcached_stPK19memcached_server_fnPv8uint32_t" title="memcached_server_cursor"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">memcached_server_cursor()</span></code></a> is passed the original caller <a class="reference internal" href="memcached_create.html#_CPPv412memcached_st" title="memcached_st"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">memcached_st</span></code></a> in its current state.</p>
282 </div>
283 <div class="section" id="return-value">
284 <h2>RETURN VALUE<a class="headerlink" href="#return-value" title="Permalink to this headline"></a></h2>
285 <p>Varies, see particular functions.</p>
286 </div>
287 <div class="section" id="see-also">
288 <h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline"></a></h2>
289 </div>
290 </div>
291
292
293 </div>
294
295 </div>
296 <footer>
297
298 <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
299
300 <a href="index_advanced_daemon.html" class="btn btn-neutral float-right" title="Affecting the memcached Daemon" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
301
302
303 <a href="memcached_server_st.html" class="btn btn-neutral float-left" title="Managing lists of servers" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
304
305 </div>
306
307
308 <hr/>
309
310 <div role="contentinfo">
311 <p>
312 &copy; <a href="../copyright.html">Copyright</a>
313
314 </p>
315 </div>
316 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>.
317
318 </footer>
319
320 </div>
321 </div>
322
323 </section>
324
325 </div>
326
327
328
329 <script type="text/javascript">
330 jQuery(function () {
331 SphinxRtdTheme.Navigation.enable(true);
332 });
333 </script>
334
335
336
337
338
339
340 </body>
341 </html>