From: Richard W.M. Jones <rjones@redhat.com>
Date: Tue, 17 May 2011 19:57:56 +0000 (+0100)
Subject: Document that guestfs_file output depends on file(1) command.
X-Git-Tag: 1.11.8~5
X-Git-Url: http://git.annexia.org/?a=commitdiff_plain;h=ef6f877b9df261fad1fbf361b8ce7af1055dfbb7;hp=b777a5a64926e9bf9b7109a0e4fb1332b20fa37f;p=libguestfs.git

Document that guestfs_file output depends on file(1) command.

And therefore practically it cannot be part of the ABI since
the output of file(1) itself changes from time to time.
---

diff --git a/generator/generator_actions.ml b/generator/generator_actions.ml
index 9c5aefd..44f47df 100644
--- a/generator/generator_actions.ml
+++ b/generator/generator_actions.ml
@@ -2268,15 +2268,12 @@ The exact command which runs is C<file -zb path>.  Note in
 particular that the filename is not prepended to the output
 (the I<-b> option).
 
-This command can also be used on C</dev/> devices
-(and partitions, LV names).  You can for example use this
-to determine if a device contains a filesystem, although
-it's usually better to use C<guestfs_vfs_type>.
-
-If the C<path> does not begin with C</dev/> then
-this command only works for the content of regular files.
-For other file types (directory, symbolic link etc) it
-will just return the string C<directory> etc.");
+The output depends on the output of the underlying L<file(1)>
+command and it can change in future in ways beyond our control.
+In other words, the output is not guaranteed by the ABI.
+
+See also: L<file(1)>, C<guestfs_vfs_type>, C<guestfs_lstat>,
+C<guestfs_is_file>, C<guestfs_is_blockdev> (etc).");
 
   ("command", (RString "output", [StringList "arguments"], []), 50, [ProtocolLimitWarning],
    [InitScratchFS, Always, TestOutput (