Merge Monty

[awesomized/libmemcached] / docs / memcached_get.pod

diff --git a/docs/memcached_get.pod b/docs/memcached_get.pod
old mode 100755 (executable)
new mode 100644 (file)
index 1cf0a60..330c075
--- a/docs/memcached_get.pod
+++ b/docs/memcached_get.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-memcached_get, memcached_mget, memcached_fetch
+memcached_get, memcached_mget, memcached_fetch - Get a value
 
 =head1 LIBRARY
 
@@ -16,7 +16,7 @@ C Client Library for memcached (libmemcached, -lmemcached)
                       memcached_return *error);
 
   char *memcached_get (memcached_st *ptr,
-                       char *key, size_t key_length,
+                       const char *key, size_t key_length,
                        size_t *value_length, 
                        uint32_t *flags,
                        memcached_return *error);
@@ -27,15 +27,15 @@ C Client Library for memcached (libmemcached, -lmemcached)
                   unsigned int number_of_keys);
   char *
   memcached_get_by_key(memcached_st *ptr, 
-                       char *master_key, size_t master_key_length, 
-                       char *key, size_t key_length, 
+                       const char *master_key, size_t master_key_length, 
+                       const char *key, size_t key_length, 
                        size_t *value_length, 
                        uint32_t *flags,
                        memcached_return *error);
 
   memcached_return 
   memcached_mget_by_key(memcached_st *ptr, 
-                        char *master_key, size_t master_key_length,
+                        const char *master_key, size_t master_key_length,
                         char **keys, size_t *key_length, 
                         unsigned int number_of_keys);
 
@@ -46,7 +46,7 @@ C Client Library for memcached (libmemcached, -lmemcached)
                          memcached_return *error);
   memcached_return 
   memcached_fetch_execute(memcached_st *ptr, 
-                          unsigned int (*callback[])(memcached_st *ptr, memcached_result_st *result, void *context),
+                          memcached_return (*callback[])(memcached_st *ptr, memcached_result_st *result, void *context),
                           void *context,
                           unsigned int number_of_callbacks);
 
@@ -58,7 +58,8 @@ 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 pointer to hold any error. The object will be returned
-upon success and NULL will be returned on failure. 
+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
@@ -77,7 +78,10 @@ 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 pointer to hold any error. The object will be returned
-upon success and NULL will be returned on failure. 
+upon success and NULL will be returned on failure. MEMCACHD_END is returned
+by the *error value when all objects that have been found are returned. 
+The final value upon MEMCACHED_END is null. Values returned by
+memcached_fetch() musted be free'ed by the caller.
 
 memcached_fetch_result() is used to return a memcached_result_st(3) structure 
 from a memcached server. The result object is forward compatible with changes
@@ -100,6 +104,12 @@ 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 supported when the C<MEMCACHED_BEHAVIOR_USE_UDP>
+has been set. Executing any of these functions with this behavior on will result in 
+C<MEMCACHED_NOT_SUPPORTED> being returned or, for those functions which do not return
+a C<memcached_return>, the error function parameter will be set to 
+C<MEMCACHED_NOT_SUPPORTED>.
+
 =head1 RETURN
 
 All objects returned must be freed by the calling application.