Clarify documentation on distro backports in version command.

[libguestfs.git] / src / generator.ml

diff --git a/src/generator.ml b/src/generator.ml
index 6fee544..bab4bc0 100755 (executable)
--- a/src/generator.ml
+++ b/src/generator.ml
@@ -804,9 +804,13 @@ used for distro-specific information.
 To construct the original version string:
 C<$major.$minor.$release$extra>
 
 To construct the original version string:
 C<$major.$minor.$release$extra>
 

+See also: L<guestfs(3)/LIBGUESTFS VERSION NUMBERS>.
+

 I<Note:> Don't use this call to test for availability
 I<Note:> Don't use this call to test for availability

-of features.  Distro backports makes this unreliable.  Use
-C<guestfs_available> instead.");
+of features.  In enterprise distributions we backport
+features from later versions into earlier versions,
+making this an unreliable way to test for features.
+Use C<guestfs_available> instead.");

 
   ("set_selinux", (RErr, [Bool "selinux"]), -1, [FishAlias "selinux"],
    [InitNone, Always, TestOutputTrue (
 
   ("set_selinux", (RErr, [Bool "selinux"]), -1, [FishAlias "selinux"],
    [InitNone, Always, TestOutputTrue (


@@ -3141,7 +3145,7 @@ Unknown file type
 
 =item '?'
 
 
 =item '?'
 

-The L<readdir(3)> returned a C<d_type> field with an
+The L<readdir(3)> call returned a C<d_type> field with an

 unexpected value
 
 =back
 unexpected value
 
 =back


@@ -3783,8 +3787,8 @@ was built (see C<appliance/kmod.whitelist.in> in the source).");
     )],
    "echo arguments back to the client",
    "\
     )],
    "echo arguments back to the client",
    "\

-This command concatenate the list of C<words> passed with single spaces between
-them and returns the resulting string.
+This command concatenates the list of C<words> passed with single spaces
+between them and returns the resulting string.

 
 You can use this command to test the connection through to the daemon.
 
 
 You can use this command to test the connection through to the daemon.
 


@@ -3911,8 +3915,13 @@ file must exist already.");
    "truncate a file to a particular size",
    "\
 This command truncates C<path> to size C<size> bytes.  The file
    "truncate a file to a particular size",
    "\
 This command truncates C<path> to size C<size> bytes.  The file

-must exist already.  If the file is smaller than C<size> then
-the file is extended to the required size with null bytes.");
+must exist already.
+
+If the current file size is less than C<size> then
+the file is extended to the required size with zero bytes.
+This creates a sparse file (ie. disk blocks are not allocated
+for the file until you write to it).  To create a non-sparse
+file of zeroes, use C<guestfs_fallocate64> instead.");

 
   ("utimens", (RErr, [Pathname "path"; Int64 "atsecs"; Int64 "atnsecs"; Int64 "mtsecs"; Int64 "mtnsecs"]), 201, [],
    [InitBasicFS, Always, TestOutputStruct (
 
   ("utimens", (RErr, [Pathname "path"; Int64 "atsecs"; Int64 "atnsecs"; Int64 "mtsecs"; Int64 "mtnsecs"]), 201, [],
    [InitBasicFS, Always, TestOutputStruct (


@@ -4022,7 +4031,7 @@ C<names> is the list of files from this directory.
 
 On return you get a list of strings, with a one-to-one
 correspondence to the C<names> list.  Each string is the
 
 On return you get a list of strings, with a one-to-one
 correspondence to the C<names> list.  Each string is the

-value of the symbol link.
+value of the symbolic link.

 
 If the C<readlink(2)> operation fails on any name, then
 the corresponding result string is the empty string C<\"\">.
 
 If the C<readlink(2)> operation fails on any name, then
 the corresponding result string is the empty string C<\"\">.