Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Thursday, June 13, 2019
 
 

memcached_get (3libmemcached)

Name

memcached_get - Retrieving data from the server

Synopsis

#include <libmemcached/memcached.h>

memcached_result_st  *  memcached_fetch_result(memcached_st *ptr,  mem-
cached_result_st *result, memcached_return_t *error)

char    *     memcached_get(memcached_st *ptr,     const     char *key,
size_t key_length,    size_t *value_length,    uint32_t *flags,    mem-
cached_return_t *error)

memcached_return_t  memcached_mget(memcached_st *ptr,  const   char   *
const *keys, const size_t *key_length, size_t number_of_keys)

char  *  memcached_get_by_key(memcached_st *ptr, const char *group_key,
size_t group_key_length,    const     char *key,     size_t key_length,
size_t *value_length, uint32_t *flags, memcached_return_t *error)

memcached_return_t    memcached_mget_by_key(memcached_st *ptr,    const
char *group_key, size_t group_key_length,  const  char  *  const *keys,
const size_t *key_length, size_t number_of_keys)

memcached_return_t           memcached_fetch_execute(memcached_st *ptr,
memcached_execute_fn *callback, void *context, uint32_t number_of_call-
backs)

memcached_return_t memcached_mget_execute(memcached_st *ptr, const char
*   const *keys,   const   size_t *key_length,   size_t number_of_keys,
memcached_execute_fn *callback, void *context, uint32_t number_of_call-
backs)

memcached_return_t     memcached_mget_execute_by_key(memcached_st *ptr,
const    char *group_key,   size_t group_key_length,   const   char   *
const *keys,    const    size_t *key_length,     size_t number_of_keys,
memcached_execute_fn *callback, void *context, uint32_t number_of_call-
backs)

memcached_return_t   (*memcached_execute_fn)(const   memcached_st *ptr,
memcached_result_st *result, void *context)

Compile and link with -lmemcached

Description

libmemcached                                      MEMCACHED_GET(3libmemcached)



NAME
       memcached_get - Retrieving data from the server

SYNOPSIS
       #include <libmemcached/memcached.h>

       memcached_result_st  *  memcached_fetch_result(memcached_st *ptr,  mem-
       cached_result_st *result, memcached_return_t *error)

       char    *     memcached_get(memcached_st *ptr,     const     char *key,
       size_t key_length,    size_t *value_length,    uint32_t *flags,    mem-
       cached_return_t *error)

       memcached_return_t  memcached_mget(memcached_st *ptr,  const   char   *
       const *keys, const size_t *key_length, size_t number_of_keys)

       char  *  memcached_get_by_key(memcached_st *ptr, const char *group_key,
       size_t group_key_length,    const     char *key,     size_t key_length,
       size_t *value_length, uint32_t *flags, memcached_return_t *error)

       memcached_return_t    memcached_mget_by_key(memcached_st *ptr,    const
       char *group_key, size_t group_key_length,  const  char  *  const *keys,
       const size_t *key_length, size_t number_of_keys)

       memcached_return_t           memcached_fetch_execute(memcached_st *ptr,
       memcached_execute_fn *callback, void *context, uint32_t number_of_call-
       backs)

       memcached_return_t memcached_mget_execute(memcached_st *ptr, const char
       *   const *keys,   const   size_t *key_length,   size_t number_of_keys,
       memcached_execute_fn *callback, void *context, uint32_t number_of_call-
       backs)

       memcached_return_t     memcached_mget_execute_by_key(memcached_st *ptr,
       const    char *group_key,   size_t group_key_length,   const   char   *
       const *keys,    const    size_t *key_length,     size_t number_of_keys,
       memcached_execute_fn *callback, void *context, uint32_t number_of_call-
       backs)

       memcached_return_t   (*memcached_execute_fn)(const   memcached_st *ptr,
       memcached_result_st *result, void *context)

       Compile and link with -lmemcached

DESCRIPTION
       memcached_get()  is  used to fetch an individual value from the server.
       You must pass in a key and its length to fetch  the  object.  You  must
       supply  three  pointer  variables  which will give you the state of the
       returned object.  A uint32_t pointer  to  contain  whatever  flags  you
       stored  with the value, a size_t pointer which will be filled with size
       of of the object, and a memcached_return_t pointer to hold  any  error.
       The  object  will be returned upon success and NULL will be returned on
       failure. Any object returned by memcached_get() must be released by the
       caller application.

       memcached_mget()  is used to select multiple keys at once. For multiple
       key operations it is always faster to use this function. This  function
       always works asynchronously.

       To  retrieve data after a successful execution of memcached_mget(), you
       will need to call memcached_fetch_result().   You  should  continue  to
       call  this  function  until it returns a NULL (i.e. no more values). If
       you need to quit in the middle of a memcached_mget() call, you can exe-
       cute a memcached_quit(), those this is not required.

       memcached_fetch_result()  is used to fetch an individual value from the
       server. memcached_mget()  must  always  be  called  before  using  this
       method.  You must pass in a key and its length to fetch the object. You
       must supply three pointer variables which will give you  the  state  of
       the  returned object.  A uint32_t pointer to contain whatever flags you
       stored with the value, a size_t pointer which will be filled with  size
       of  of  the object, and a memcached_return_t pointer to hold any error.
       The object will be returned upon success and NULL will be  returned  on
       failure. MEMCACHED_END is returned by the *error value when all objects
       that have been found are returned. The final value  upon  MEMCACHED_END
       is null.

       memcached_fetch_result() is used to return a memcached_result_st struc-
       ture from a memcached server. The result object is  forward  compatible
       with  changes  to  the server. For more information please refer to the
       memcached_result_st help. This function  will  dynamically  allocate  a
       result structure for you if you do not pass one to the function.

       memcached_fetch_execute()  is  a  callback  function  for  result sets.
       Instead of returning the results to you for processing, it passes  each
       of  the  result sets to the list of functions you provide. It passes to
       the function a memcached_st that can be cloned for use  in  the  called
       function  (it  can  not  be used directly). It also passes a result set
       which does not need to be freed. Finally it passes a "context". This is
       just  a  pointer to a memory reference you supply the calling function.
       Currently only one value is being passed to each function call. In  the
       future there will be an option to allow this to be an array.

       memcached_mget_execute() and memcached_mget_execute_by_key() is similar
       to memcached_mget(), but it may trigger  the  supplied  callbacks  with
       result  sets  while  sending  out  the queries. If you try to perform a
       really large multiget with memcached_mget() you may encounter  a  dead-
       lock in the OS kernel (it will fail to write data to the socket because
       the input buffer is full). memcached_mget_execute() solves this problem
       by  processing  some  of  the  results  before  continuing  sending out
       requests. Please note that this  function  is  only  available  in  the
       binary protocol.

       memcached_get_by_key()  and memcached_mget_by_key() behave in a similar
       nature as memcached_get() and memcached_mget().  The difference is that
       they  take  a  master  key that is used for determining which server an
       object was stored if key partitioning was used for storage.

       All of the above functions are not  tested  when  the  MEMCACHED_BEHAV-
       IOR_USE_UDP  has  been  set. Executing any of these functions with this
       behavior on will result in MEMCACHED_NOT_SUPPORTED being  returned,  or
       for those functions which do not return a memcached_return_t, the error
       function parameter will be set to MEMCACHED_NOT_SUPPORTED.

RETURN
       All objects retrieved  via  memcached_get()  or  memcached_get_by_key()
       must be freed with free(3).

       memcached_get()  will  return NULL on error. You must look at the value
       of error to determine what the actual error was.

       memcached_fetch_execute() return MEMCACHED_SUCCESS  if  all  keys  were
       successful.  MEMCACHED_NOTFOUND  will  be return if no keys at all were
       found.

       memcached_fetch_result() sets error to  MEMCACHED_END  upon  successful
       conclusion.   MEMCACHED_NOTFOUND  will be return if no keys at all were
       found.

HOME
       To find out more information please check: http://libmemcached.org/


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+----------------------+
       |ATTRIBUTE TYPE |   ATTRIBUTE VALUE    |
       +---------------+----------------------+
       |Availability   | library/libmemcached |
       +---------------+----------------------+
       |Stability      | Uncommitted          |
       +---------------+----------------------+
SEE ALSO
       memcached(1) libmemcached(3) memcached_strerror(3)

AUTHOR
       Brian Aker

COPYRIGHT
       2011-2013, Brian Aker DataDifferential, http://datadifferential.com/



NOTES
       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source    was    downloaded     from      https://launchpad.net/libmem-
       cached/1.0/1.0.18/+download/libmemcached-1.0.18.tar.gz

       Further information about this software can be found on the open source
       community website at http://libmemcached.org/libMemcached.html.



1.0.18                         February 09, 2014
                                                  MEMCACHED_GET(3libmemcached)