inspect: Add function to read the first line of a file, with safety checks.

[libguestfs.git] / generator / generator_actions.ml

diff --git a/generator/generator_actions.ml b/generator/generator_actions.ml
index c5bd44b..34a82bd 100644 (file)
--- a/generator/generator_actions.ml
+++ b/generator/generator_actions.ml
@@ -789,7 +789,7 @@ Arch Linux.
 
 =item \"debian\"
 
-Debian or a Debian-derived distro such as Ubuntu.
+Debian.
 
 =item \"fedora\"
 
@@ -799,6 +799,14 @@ Fedora.
 
 Gentoo.
 
+=item \"linuxmint\"
+
+Linux Mint.
+
+=item \"mandriva\"
+
+Mandriva.
+
 =item \"meego\"
 
 MeeGo.
@@ -815,11 +823,6 @@ Some Red Hat-derived distro.
 
 Red Hat Enterprise Linux and some derivatives.
 
-=item \"windows\"
-
-Windows does not have distributions.  This string is
-returned if the OS type is Windows.
-
 =item \"ubuntu\"
 
 Ubuntu.
@@ -828,6 +831,11 @@ Ubuntu.
 
 The distro could not be determined.
 
+=item \"windows\"
+
+Windows does not have distributions.  This string is
+returned if the OS type is Windows.
+
 =back
 
 Future versions of libguestfs may return other strings here.
@@ -1164,11 +1172,110 @@ a real packaging system (eg. Windows).
 
 Possible strings include: C<yum>, C<up2date>,
 C<apt> (for all Debian derivatives),
-C<portage>, C<pisi>, C<pacman>.
+C<portage>, C<pisi>, C<pacman>, C<urpmi>.
 Future versions of libguestfs may return other strings.
 
 Please read L<guestfs(3)/INSPECTION> for more details.");
 
+  ("inspect_list_applications", (RStructList ("applications", "application"), [Device "root"], []), -1, [],
+   [],
+   "get list of applications installed in the operating system",
+   "\
+This function should only be called with a root device string
+as returned by C<guestfs_inspect_os>.
+
+Return the list of applications installed in the operating system.
+
+I<Note:> This call works differently from other parts of the
+inspection API.  You have to call C<guestfs_inspect_os>, then
+C<guestfs_inspect_get_mountpoints>, then mount up the disks,
+before calling this.  Listing applications is a significantly
+more difficult operation which requires access to the full
+filesystem.  Also note that unlike the other
+C<guestfs_inspect_get_*> calls which are just returning
+data cached in the libguestfs handle, this call actually reads
+parts of the mounted filesystems during the call.
+
+This returns an empty list if the inspection code was not able
+to determine the list of applications.
+
+The application structure contains the following fields:
+
+=over 4
+
+=item C<app_name>
+
+The name of the application.  For Red Hat-derived and Debian-derived
+Linux guests, this is the package name.
+
+=item C<app_display_name>
+
+The display name of the application, sometimes localized to the
+install language of the guest operating system.
+
+If unavailable this is returned as an empty string C<\"\">.
+Callers needing to display something can use C<app_name> instead.
+
+=item C<app_epoch>
+
+For package managers which use epochs, this contains the epoch of
+the package (an integer).  If unavailable, this is returned as C<0>.
+
+=item C<app_version>
+
+The version string of the application or package.  If unavailable
+this is returned as an empty string C<\"\">.
+
+=item C<app_release>
+
+The release string of the application or package, for package
+managers that use this.  If unavailable this is returned as an
+empty string C<\"\">.
+
+=item C<app_install_path>
+
+The installation path of the application (on operating systems
+such as Windows which use installation paths).  This path is
+in the format used by the guest operating system, it is not
+a libguestfs path.
+
+If unavailable this is returned as an empty string C<\"\">.
+
+=item C<app_trans_path>
+
+The install path translated into a libguestfs path.
+If unavailable this is returned as an empty string C<\"\">.
+
+=item C<app_publisher>
+
+The name of the publisher of the application, for package
+managers that use this.  If unavailable this is returned
+as an empty string C<\"\">.
+
+=item C<app_url>
+
+The URL (eg. upstream URL) of the application.
+If unavailable this is returned as an empty string C<\"\">.
+
+=item C<app_source_package>
+
+For packaging systems which support this, the name of the source
+package.  If unavailable this is returned as an empty string C<\"\">.
+
+=item C<app_summary>
+
+A short (usually one line) description of the application or package.
+If unavailable this is returned as an empty string C<\"\">.
+
+=item C<app_description>
+
+A longer description of the application or package.
+If unavailable this is returned as an empty string C<\"\">.
+
+=back
+
+Please read L<guestfs(3)/INSPECTION> for more details.");
+
 ]
 
 (* daemon_functions are any functions which cause some action