Don't stash strings in the handle.

[libguestfs.git] / python / guestfs.py

diff --git a/python/guestfs.py b/python/guestfs.py
index 3cfc86a..e61ba65 100644 (file)
--- a/python/guestfs.py
+++ b/python/guestfs.py
@@ -152,10 +152,6 @@ class GuestFS:
         You can also override this by setting the
         "LIBGUESTFS_QEMU" environment variable.
         
         You can also override this by setting the
         "LIBGUESTFS_QEMU" environment variable.
         

-        The string "qemu" is stashed in the libguestfs handle,
-        so the caller must make sure it remains valid for the
-        lifetime of the handle.
-        

         Setting "qemu" to "NULL" restores the default qemu
         binary.
         """
         Setting "qemu" to "NULL" restores the default qemu
         binary.
         """


@@ -176,10 +172,6 @@ class GuestFS:
         The default is "$libdir/guestfs" unless overridden by
         setting "LIBGUESTFS_PATH" environment variable.
         
         The default is "$libdir/guestfs" unless overridden by
         setting "LIBGUESTFS_PATH" environment variable.
         

-        The string "path" is stashed in the libguestfs handle,
-        so the caller must make sure it remains valid for the
-        lifetime of the handle.
-        

         Setting "path" to "NULL" restores the default path.
         """
         return libguestfsmod.set_path (self._o, path)
         Setting "path" to "NULL" restores the default path.
         """
         return libguestfsmod.set_path (self._o, path)


@@ -192,6 +184,26 @@ class GuestFS:
         """
         return libguestfsmod.get_path (self._o)
 
         """
         return libguestfsmod.get_path (self._o)
 

+    def set_append (self, append):
+        u"""This function is used to add additional options to the
+        guest kernel command line.
+        
+        The default is "NULL" unless overridden by setting
+        "LIBGUESTFS_APPEND" environment variable.
+        
+        Setting "append" to "NULL" means *no* additional options
+        are passed (libguestfs always adds a few of its own).
+        """
+        return libguestfsmod.set_append (self._o, append)
+
+    def get_append (self):
+        u"""Return the additional kernel options which are added to
+        the guest kernel command line.
+        
+        If "NULL" then no options are added.
+        """
+        return libguestfsmod.get_append (self._o)
+

     def set_autosync (self, autosync):
         u"""If "autosync" is true, this enables autosync. Libguestfs
         will make a best effort attempt to run "g.umount_all"
     def set_autosync (self, autosync):
         u"""If "autosync" is true, this enables autosync. Libguestfs
         will make a best effort attempt to run "g.umount_all"


@@ -279,6 +291,15 @@ class GuestFS:
         """
         return libguestfsmod.set_ready (self._o)
 
         """
         return libguestfsmod.set_ready (self._o)
 

+    def end_busy (self):
+        u"""This sets the state to "READY", or if in "CONFIG" then
+        it leaves the state as is. This is only used when
+        implementing actions using the low-level API.
+        
+        For more information on states, see guestfs(3).
+        """
+        return libguestfsmod.end_busy (self._o)
+

     def mount (self, device, mountpoint):
         u"""Mount a guest disk at a position in the filesystem.
         Block devices are named "/dev/sda", "/dev/sdb" and so
     def mount (self, device, mountpoint):
         u"""Mount a guest disk at a position in the filesystem.
         Block devices are named "/dev/sda", "/dev/sdb" and so


@@ -700,7 +721,7 @@ class GuestFS:
 
     def mkfs (self, fstype, device):
         u"""This creates a filesystem on "device" (usually a
 
     def mkfs (self, fstype, device):
         u"""This creates a filesystem on "device" (usually a

-        partition of LVM logical volume). The filesystem type is
+        partition or LVM logical volume). The filesystem type is

         "fstype", for example "ext3".
         """
         return libguestfsmod.mkfs (self._o, fstype, device)
         "fstype", for example "ext3".
         """
         return libguestfsmod.mkfs (self._o, fstype, device)


@@ -743,6 +764,11 @@ class GuestFS:
         calculated using "strlen" (so in this case the content
         cannot contain embedded ASCII NULs).
         
         calculated using "strlen" (so in this case the content
         cannot contain embedded ASCII NULs).
         

+        *NB.* Owing to a bug, writing content containing ASCII
+        NUL characters does *not* work, even if the length is
+        specified. We hope to resolve this bug in a future
+        version. In the meantime use "g.upload".
+        

         Because of the message protocol, there is a transfer
         limit of somewhere between 2MB and 4MB. To transfer
         large files you should use FTP.
         Because of the message protocol, there is a transfer
         limit of somewhere between 2MB and 4MB. To transfer
         large files you should use FTP.


@@ -806,6 +832,13 @@ class GuestFS:
         Subsequent elements are parameters. The list must be
         non-empty (ie. must contain a program name).
         
         Subsequent elements are parameters. The list must be
         non-empty (ie. must contain a program name).
         

+        The return value is anything printed to *stdout* by the
+        command.
+        
+        If the command returns a non-zero exit status, then this
+        function returns an error message. The error message
+        string is the content of *stderr* from the command.
+        

         The $PATH environment variable will contain at least
         "/usr/bin" and "/bin". If you require a program from
         another location, you should provide the full path in
         The $PATH environment variable will contain at least
         "/usr/bin" and "/bin". If you require a program from
         another location, you should provide the full path in


@@ -816,6 +849,10 @@ class GuestFS:
         the correct places. It is the caller's responsibility to
         ensure all filesystems that are needed are mounted at
         the right locations.
         the correct places. It is the caller's responsibility to
         ensure all filesystems that are needed are mounted at
         the right locations.

+        
+        Because of the message protocol, there is a transfer
+        limit of somewhere between 2MB and 4MB. To transfer
+        large files you should use FTP.

         """
         return libguestfsmod.command (self._o, arguments)
 
         """
         return libguestfsmod.command (self._o, arguments)
 


@@ -824,6 +861,10 @@ class GuestFS:
         into a list of lines.
         
         This function returns a list of strings.
         into a list of lines.
         
         This function returns a list of strings.

+        
+        Because of the message protocol, there is a transfer
+        limit of somewhere between 2MB and 4MB. To transfer
+        large files you should use FTP.

         """
         return libguestfsmod.command_lines (self._o, arguments)
 
         """
         return libguestfsmod.command_lines (self._o, arguments)
 


@@ -1154,12 +1195,21 @@ class GuestFS:
         which should have filesystem type "fstype".
         
         The returned integer is the status. See fsck(8) for the
         which should have filesystem type "fstype".
         
         The returned integer is the status. See fsck(8) for the

-        list of status codes from "fsck", and note that multiple
-        status codes can be summed together.
+        list of status codes from "fsck".
+        
+        Notes:
+        
+        *   Multiple status codes can be summed together.
+        
+        *   A non-zero return code can mean "success", for
+        example if errors have been corrected on the
+        filesystem.

         
         

-        It is entirely equivalent to running "fsck -a -t fstype
-        device". Note that checking or repairing NTFS volumes is
-        not supported (by linux-ntfs).
+        *   Checking or repairing NTFS volumes is not supported
+        (by linux-ntfs).
+        
+        This command is entirely equivalent to running "fsck -a
+        -t fstype device".

         """
         return libguestfsmod.fsck (self._o, fstype, device)
 
         """
         return libguestfsmod.fsck (self._o, fstype, device)
 


@@ -1174,3 +1224,113 @@ class GuestFS:
         """
         return libguestfsmod.zero (self._o, device)
 
         """
         return libguestfsmod.zero (self._o, device)
 

+    def grub_install (self, root, device):
+        u"""This command installs GRUB (the Grand Unified
+        Bootloader) on "device", with the root directory being
+        "root".
+        """
+        return libguestfsmod.grub_install (self._o, root, device)
+
+    def cp (self, src, dest):
+        u"""This copies a file from "src" to "dest" where "dest" is
+        either a destination filename or destination directory.
+        """
+        return libguestfsmod.cp (self._o, src, dest)
+
+    def cp_a (self, src, dest):
+        u"""This copies a file or directory from "src" to "dest"
+        recursively using the "cp -a" command.
+        """
+        return libguestfsmod.cp_a (self._o, src, dest)
+
+    def mv (self, src, dest):
+        u"""This moves a file from "src" to "dest" where "dest" is
+        either a destination filename or destination directory.
+        """
+        return libguestfsmod.mv (self._o, src, dest)
+
+    def drop_caches (self, whattodrop):
+        u"""This instructs the guest kernel to drop its page cache,
+        and/or dentries and inode caches. The parameter
+        "whattodrop" tells the kernel what precisely to drop,
+        see <http://linux-mm.org/Drop_Caches>
+        
+        Setting "whattodrop" to 3 should drop everything.
+        
+        This automatically calls sync(2) before the operation,
+        so that the maximum guest memory is freed.
+        """
+        return libguestfsmod.drop_caches (self._o, whattodrop)
+
+    def dmesg (self):
+        u"""This returns the kernel messages ("dmesg" output) from
+        the guest kernel. This is sometimes useful for extended
+        debugging of problems.
+        
+        Another way to get the same information is to enable
+        verbose messages with "g.set_verbose" or by setting the
+        environment variable "LIBGUESTFS_DEBUG=1" before running
+        the program.
+        """
+        return libguestfsmod.dmesg (self._o)
+
+    def ping_daemon (self):
+        u"""This is a test probe into the guestfs daemon running
+        inside the qemu subprocess. Calling this function checks
+        that the daemon responds to the ping message, without
+        affecting the daemon or attached block device(s) in any
+        other way.
+        """
+        return libguestfsmod.ping_daemon (self._o)
+
+    def equal (self, file1, file2):
+        u"""This compares the two files "file1" and "file2" and
+        returns true if their content is exactly equal, or false
+        otherwise.
+        
+        The external cmp(1) program is used for the comparison.
+        """
+        return libguestfsmod.equal (self._o, file1, file2)
+
+    def strings (self, path):
+        u"""This runs the strings(1) command on a file and returns
+        the list of printable strings found.
+        
+        This function returns a list of strings.
+        
+        Because of the message protocol, there is a transfer
+        limit of somewhere between 2MB and 4MB. To transfer
+        large files you should use FTP.
+        """
+        return libguestfsmod.strings (self._o, path)
+
+    def strings_e (self, encoding, path):
+        u"""This is like the "g.strings" command, but allows you to
+        specify the encoding.
+        
+        See the strings(1) manpage for the full list of
+        encodings.
+        
+        Commonly useful encodings are "l" (lower case L) which
+        will show strings inside Windows/x86 files.
+        
+        The returned strings are transcoded to UTF-8.
+        
+        This function returns a list of strings.
+        
+        Because of the message protocol, there is a transfer
+        limit of somewhere between 2MB and 4MB. To transfer
+        large files you should use FTP.
+        """
+        return libguestfsmod.strings_e (self._o, encoding, path)
+
+    def hexdump (self, path):
+        u"""This runs "hexdump -C" on the given "path". The result
+        is the human-readable, canonical hex dump of the file.
+        
+        Because of the message protocol, there is a transfer
+        limit of somewhere between 2MB and 4MB. To transfer
+        large files you should use FTP.
+        """
+        return libguestfsmod.hexdump (self._o, path)
+