From: Sage Weil <sage@inktank.com>
Date: Thu, 28 Mar 2013 22:16:35 +0000 (-0700)
Subject: librbd: document diff_iterate in header
X-Git-Tag: v0.62~118^2~30
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=a69532e86450f45b4200d61914df8d80899eb3ba;p=ceph.git

librbd: document diff_iterate in header

Signed-off-by: Sage Weil <sage@inktank.com>
---

diff --git a/src/include/rbd/librbd.hpp b/src/include/rbd/librbd.hpp
index 15d184e0255..bf331d5e69e 100644
--- a/src/include/rbd/librbd.hpp
+++ b/src/include/rbd/librbd.hpp
@@ -155,6 +155,24 @@ public:
   ssize_t read(uint64_t ofs, size_t len, ceph::bufferlist& bl);
   int64_t read_iterate(uint64_t ofs, size_t len,
 		       int (*cb)(uint64_t, size_t, const char *, void *), void *arg);
+  /**
+   * get difference between two versions of an image
+   *
+   * This will return the differences between two versions of an image
+   * via a callback, which gets the offset and length and a flag
+   * indicating whether the extent is known/defined to be zeros (a
+   * hole).  If the source snapshot name is NULL, we interpret that as
+   * the beginning of time and return all allocated regions of the
+   * image.  The end version is whatever is currently selected for the
+   * image handle (either a snapshot or the writeable head).
+   *
+   * @param fromsnapname start snapshot name, or NULL
+   * @param ofs start offset
+   * @param len len in bytes of region to report on
+   * @param cb callback to call for each allocated region
+   * @param arg argument to pass to the callback
+   * @returns len on success, or negative error code on error
+   */
   int64_t diff_iterate(const char *fromsnapname,
 		       uint64_t ofs, size_t len,
 		       int (*cb)(uint64_t, size_t, bool, void *), void *arg);