git.m6w6.name Git - awesomized/libmemcached/blob - docs/source/libmemcached/memcached_stats.rst

   1 Working with statistical information from a server
   2 ==================================================
   3
   4 Get memcached statistics
   5
   6 .. index:: object: memcached_st
   7
   8 SYNOPSIS
   9 --------
  10
  11 #include <libmemcached/memcached.h>
  12     Compile and link with -lmemcached
  13
  14 .. type:: struct memcached_stat_st memcached_stat_st
  15
  16 .. type:: memcached_return_t (*memcached_stat_fn)(const memcached_instance_st * server, const char *key, size_t key_length, const char *value, size_t value_length, void *context)
  17
  18     :param server: pointer to the `memcached_instance_st` being stat'ed
  19     :param key: the current key
  20     :param key_length: the length of the `key` without any terminating zero
  21     :param value: the value read
  22     :param value_length: the length of the value without any terminating zero
  23     :param context: pointer to the user supplied context
  24     :returns: `memcached_return_t` indicating success
  25
  26 .. function:: memcached_stat_st *memcached_stat (memcached_st *ptr, char *args, memcached_return_t *error)
  27
  28     :param ptr: pointer to an initialized `memcached_st` struct
  29     :param args: particular state object to query
  30     :param error: pointer to `memcached_return_t` indicating success
  31     :returns: array of `memcached_stat_st` objects for all available servers
  32
  33 .. function:: memcached_return_t memcached_stat_servername (memcached_stat_st *stat, char *args, const char *hostname, in_port_t port)
  34
  35     :param stat: pointer to a `memcached_stat_st` struct to fill
  36     :param args: particular state object to query
  37     :param hostname: the hostname or IP address of the server to stat
  38     :param port: the port of the server to stat
  39     :returns: `memcached_return_t` indicating success
  40
  41 .. function:: char * memcached_stat_get_value (memcached_st *ptr, memcached_stat_st *stat, const char *key, memcached_return_t *error)
  42
  43     :param ptr: pointer to initialized `memcached_st` struct
  44     :param stat: pointer to initialized `memcached_stat_st` struct
  45     :param key: the statistic to query
  46     :param error: pointer to `memcached_return_t` indicating success
  47     :returns: string value of the statistic
  48
  49 .. function:: char ** memcached_stat_get_keys (memcached_st *ptr, memcached_stat_st *stat, memcached_return_t *error)
  50
  51     :param ptr: pointer to initialized `memcached_st` struct
  52     :param stat: pointer to initialized `memcached_stat_st` struct
  53     :param error: pointer to `memcached_return_t` indicating success
  54     :returns: array of default keys probably available in the statistics
  55
  56 .. function:: memcached_return_t memcached_stat_execute (memcached_st *ptr, const char *args, memcached_stat_fn func, void *context)
  57
  58     :param ptr: pointer to initialized `memcached_st` struct
  59     :param args: particular state object to query
  60     :param func: `memcached_stat_fn` callback
  61     :param context: pointer to user supplied context
  62     :returns: `memcached_return_t` indication success
  63
  64 DESCRIPTION
  65 -----------
  66
  67 `libmemcached` has the ability to query a :manpage:`memcached(1)` server (or
  68 collection of servers) for their current state. Queries to find state return a
  69 :type:`memcached_stat_st` structure. You are responsible for freeing this
  70 structure. While it is possible to access the structure directly it is not
  71 advisable. :func:`memcached_stat_get_value` has been provided to query the structure.
  72
  73 :func:`memcached_stat_execute` uses the servers found in :type:`memcached_stat_st`
  74 and executes a "stat" command on each server. args is an optional argument that
  75 can be passed in to modify the behavior of "stats". You will need to supply a
  76 callback function that will be supplied each pair of values returned by
  77 the memcached server.
  78
  79 :func:`memcached_stat` fetches an array of :type:`memcached_stat_st` structures
  80 containing the state of all available memcached servers. The return value must
  81 be freed by the calling application. If called with the
  82 `MEMCACHED_BEHAVIOR_USE_UDP` behavior set, a NULL value is returned and the
  83 error parameter is set to `MEMCACHED_NOT_SUPPORTED`.
  84
  85 :func:`memcached_stat_servername` can be used standalone without a
  86 :type:`memcached_st` to obtain the state of a particular server.  "args" is used
  87 to define a particular state object (a list of these are not provided for by either
  88 the :func:`memcached_stat_get_keys` call nor are they defined in the memcached
  89 protocol). You must specify the hostname and port of the server you want to
  90 obtain information on.
  91
  92 :func:`memcached_stat_get_value` returns the value of a particular state key.
  93 You specify the key you wish to obtain.  The key must be null terminated.
  94
  95 :func:`memcached_stat_get_keys` returns a list of keys that the server has state
  96 objects on. You are responsible for freeing this list.
  97
  98 A command line tool, `memstat`, is provided so that you do not have to write
  99 an application to do this.
 100
 101 RETURN VALUE
 102 ------------
 103
 104 Varies, see particular functions.
 105
 106 Any method returning a :type:`memcached_stat_st` expects you to free the
 107 memory allocated for it.
 108
 109 SEE ALSO
 110 --------
 111
 112 .. only:: man
 113
 114     :manpage:`memcached(1)`
 115     :manpage:`libmemcached(3)`
 116     :manpage:`memcached_strerror(3)`
 117
 118 .. only:: html
 119
 120     * :manpage:`memcached(1)`
 121     * :doc:`../libmemcached`
 122     * :doc:`memcached_strerror`