.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "MEMCACHED_SERVERS" "3" "Feb 01, 2024" "1.1" "libmemcached-awesome"
.SH NAME
memcached_servers \- libmemcached Documentation
.SH SYNOPSIS
.INDENT 0.0
.TP
.B #include <libmemcached/memcached.h>
Compile and link with \-lmemcached
.UNINDENT
.INDENT 0.0
.TP
.B uint32_t memcached_server_count(\fI\%memcached_st\fP *ptr) 
.INDENT 7.0
.TP
.B Parameters
\fBptr\fP \-\- pointer to initialized \fI\%memcached_st\fP struct
.TP
.B Returns
number of configured servers
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fI\%memcached_return_t\fP memcached_server_add(\fI\%memcached_st\fP *ptr, const char *hostname, in_port_t port) 
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBptr\fP \-\- pointer to initialized \fI\%memcached_st\fP struct
.IP \(bu 2
\fBhostname\fP \-\- hostname or IP address of the TCP server to add
.IP \(bu 2
\fBport\fP \-\- port of the TCP server
.UNINDENT
.TP
.B Returns
\fI\%memcached_return_t\fP indicating success
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fI\%memcached_return_t\fP memcached_server_add_udp(\fI\%memcached_st\fP *ptr, const char *hostname, in_port_t port) 
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBptr\fP \-\- pointer to initialized \fI\%memcached_st\fP struct
.IP \(bu 2
\fBhostname\fP \-\- hostname or IP address of the UDP server to add
.IP \(bu 2
\fBport\fP \-\- port of the UDP server
.UNINDENT
.TP
.B Returns
\fI\%memcached_return_t\fP indicating success
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fI\%memcached_return_t\fP memcached_server_add_unix_socket(\fI\%memcached_st\fP *ptr, const char *socket) 
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBptr\fP \-\- pointer to initialized \fI\%memcached_st\fP struct
.IP \(bu 2
\fBsocket\fP \-\- path to the UNIX socket of the server to add
.UNINDENT
.TP
.B Returns
\fI\%memcached_return_t\fP indicating success
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fI\%memcached_return_t\fP memcached_server_push(\fI\%memcached_st\fP *ptr, const memcached_server_st *list) 
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBptr\fP \-\- pointer to initialized \fI\%memcached_st\fP struct
.IP \(bu 2
\fBlist\fP \-\- pre\-configured list of servers to push
.UNINDENT
.TP
.B Returns
\fI\%memcached_return_t\fP indicating success
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B const memcached_instance_st *memcached_server_by_key(\fI\%memcached_st\fP *ptr, const char *key, size_t key_length, \fI\%memcached_return_t\fP *error) 
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBptr\fP \-\- pointer to initialized \fI\%memcached_st\fP struct
.IP \(bu 2
\fBkey\fP \-\- key to hash and lookup a server
.IP \(bu 2
\fBkey_length\fP \-\- length of \fI\%key\fP without any terminating zero
.IP \(bu 2
\fBerror\fP \-\- pointer to \fI\%memcached_return_t\fP indicating success
.UNINDENT
.TP
.B Returns
the server instance to be used for storing/retrieving \fI\%key\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B const memcached_instance_st *memcached_server_get_last_disconnect(const \fI\%memcached_st\fP *ptr) 
.INDENT 7.0
.TP
.B Parameters
\fBptr\fP \-\- pointer to initialized \fI\%memcached_st\fP struct
.TP
.B Returns
the instance of the last server for which there was a connection problem
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fI\%memcached_return_t\fP memcached_server_cursor(const \fI\%memcached_st\fP *ptr, const \fI\%memcached_server_fn\fP *callback, void *context, uint32_t number_of_callbacks) 
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBptr\fP \-\- pointer to initialized \fI\%memcached_st\fP struct
.IP \(bu 2
\fBcallback\fP \-\- list of \fI\%memcached_server_fn\fP to be called for each server instance
.IP \(bu 2
\fBcontext\fP \-\- pointer to user supplied context for the callback
.IP \(bu 2
\fBnumber_of_callbacks\fP \-\- number of callbacks supplied
.UNINDENT
.TP
.B Returns
\fI\%memcached_return_t\fP indicating success
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B typedef \fI\%memcached_return_t\fP (*memcached_server_fn)(const \fI\%memcached_st\fP *ptr, const memcached_instance_st *server, void *context) 
.INDENT 7.0
.TP
.B Param ptr
pointer to the \fI\%memcached_st\fP struct
.TP
.B Param server
pointer to \fBmemcached_instance_st\fP
.TP
.B Param context
pointer to user supplied context
.TP
.B Returns
\fI\%memcached_return_t\fP indicating success
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
\fBlibmemcached\fP performs operations on a list of hosts. The order of
these hosts determine routing to keys. Functions are provided to add keys to
\fI\%memcached_st\fP structures. To manipulate lists of servers see
\fBmemcached_server_st\fP\&.
.sp
\fI\%memcached_server_count()\fP provides you a count of the current number of
servers being used by a \fI\%memcached_st\fP structure.
.sp
\fI\%memcached_server_add()\fP pushes a single TCP server into the
\fI\%memcached_st\fP structure. This server will be placed at the end.
Duplicate servers are allowed, so duplication is not checked. Executing this
function with the \fI\%MEMCACHED_BEHAVIOR_USE_UDP\fP behavior set will result in
a \fI\%MEMCACHED_INVALID_HOST_PROTOCOL\fP\&.
.sp
\fI\%memcached_server_add_udp()\fP pushes a single UDP server into the
\fI\%memcached_st\fP structure. This server will be placed at the end. Duplicate
servers are allowed, so duplication is not checked. Executing this function
without setting the \fI\%MEMCACHED_BEHAVIOR_USE_UDP\fP behavior will result in a
\fI\%MEMCACHED_INVALID_HOST_PROTOCOL\fP\&.
.sp
\fI\%memcached_server_add_unix_socket()\fP pushes a single UNIX socket into the
\fI\%memcached_st\fP structure. This UNIX socket will be placed at the end.
Duplicate servers are allowed, so duplication is not checked. The length
of the filename must be one character less than \fBMEMCACHED_MAX_HOST_LENGTH\fP\&.
.sp
\fI\%memcached_server_push()\fP pushes an array of \fBmemcached_server_st\fP
into the \fI\%memcached_st\fP structure. These servers will be placed at
the end. Duplicate servers are allowed, so duplication is not checked. A
copy is made of structure so the list provided (and any operations on
the list) are not saved.
.sp
\fI\%memcached_server_by_key()\fP allows you to provide a key and retrieve the
server which would be used for assignment.
.sp
\fI\%memcached_server_get_last_disconnect()\fP returns a pointer to the last
server for which there was a connection problem. It does not mean this
particular server is currently dead but if the library is reporting a server
is, the returned server is a very good candidate.
.sp
\fI\%memcached_server_cursor()\fP takes a memcached_st and loops through the
list of hosts currently in the cursor calling the list of callback
functions provided. You can optionally pass in a value via
context which will be provided to each callback function. An error
return from any callback will terminate the loop.
\fI\%memcached_server_cursor()\fP is passed the original caller
\fI\%memcached_st\fP in its current state.
.SH RETURN VALUE
.sp
Varies, see particular functions.
.SH SEE ALSO
.sp
\fBmemcached(1)\fP
\fBlibmemcached(3)\fP
\fBmemcached_server_st(3)\fP
\fBmemcached_strerror(3)\fP
.\" Generated by docutils manpage writer.
.