From: Richard Jones <rjones@redhat.com>
Date: Thu, 2 Sep 2010 10:11:55 +0000 (+0100)
Subject: perl: Document handle is a hashref.
X-Git-Tag: 1.4.5~5
X-Git-Url: http://git.annexia.org/?a=commitdiff_plain;h=4a230979bb4f6d0a13b42b992b99aa8b94435e46;p=libguestfs.git

perl: Document handle is a hashref.

For details see commit eb566f7dc7974b42ac65729a2e5e5bcee329a0a9.
(cherry picked from commit b8b0c99b46172712aa190f70182734934587af7b)
---

diff --git a/src/generator.ml b/src/generator.ml
index b61e43c..d743c89 100755
--- a/src/generator.ml
+++ b/src/generator.ml
@@ -9282,6 +9282,24 @@ L<Sys::Guestfs::Lib(3)/feature_available>.
 For further discussion on this topic, refer to
 L<guestfs(3)/AVAILABILITY>.
 
+=head1 STORING DATA IN THE HANDLE
+
+The handle returned from L</new> is a hash reference.  The hash
+normally contains a single element:
+
+ {
+   _g => [private data used by libguestfs]
+ }
+
+Callers can add other elements to this hash to store data for their own
+purposes.  The data lasts for the lifetime of the handle.
+
+Any fields whose names begin with an underscore are reserved
+for private use by libguestfs.  We may add more in future.
+
+It is recommended that callers prefix the name of their field(s)
+with some unique string, to avoid conflicts with other users.
+
 =head1 COPYRIGHT
 
 Copyright (C) %s Red Hat Inc.