tests: Remove use of sfdisk from tests.
[libguestfs.git] / generator / generator_actions.ml
1 (* libguestfs
2  * Copyright (C) 2009-2010 Red Hat Inc.
3  *
4  * This program is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU General Public License as published by
6  * the Free Software Foundation; either version 2 of the License, or
7  * (at your option) any later version.
8  *
9  * This program is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12  * GNU General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program; if not, write to the Free Software
16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17  *)
18
19 (* Please read generator/README first. *)
20
21 (* Note about long descriptions: When referring to another
22  * action, use the format C<guestfs_other> (ie. the full name of
23  * the C function).  This will be replaced as appropriate in other
24  * language bindings.
25  *
26  * Apart from that, long descriptions are just perldoc paragraphs.
27  *)
28
29 open Generator_types
30 open Generator_utils
31
32 (* These test functions are used in the language binding tests. *)
33
34 let test_all_args = [
35   String "str";
36   OptString "optstr";
37   StringList "strlist";
38   Bool "b";
39   Int "integer";
40   Int64 "integer64";
41   FileIn "filein";
42   FileOut "fileout";
43   BufferIn "bufferin";
44 ]
45
46 let test_all_rets = [
47   (* except for RErr, which is tested thoroughly elsewhere *)
48   "test0rint",         RInt "valout";
49   "test0rint64",       RInt64 "valout";
50   "test0rbool",        RBool "valout";
51   "test0rconststring", RConstString "valout";
52   "test0rconstoptstring", RConstOptString "valout";
53   "test0rstring",      RString "valout";
54   "test0rstringlist",  RStringList "valout";
55   "test0rstruct",      RStruct ("valout", "lvm_pv");
56   "test0rstructlist",  RStructList ("valout", "lvm_pv");
57   "test0rhashtable",   RHashtable "valout";
58 ]
59
60 let test_functions = [
61   ("test0", (RErr, test_all_args, []), -1, [NotInFish; NotInDocs],
62    [],
63    "internal test function - do not use",
64    "\
65 This is an internal test function which is used to test whether
66 the automatically generated bindings can handle every possible
67 parameter type correctly.
68
69 It echos the contents of each parameter to stdout.
70
71 You probably don't want to call this function.");
72 ] @ List.flatten (
73   List.map (
74     fun (name, ret) ->
75       [(name, (ret, [String "val"], []), -1, [NotInFish; NotInDocs],
76         [],
77         "internal test function - do not use",
78         "\
79 This is an internal test function which is used to test whether
80 the automatically generated bindings can handle every possible
81 return type correctly.
82
83 It converts string C<val> to the return type.
84
85 You probably don't want to call this function.");
86        (name ^ "err", (ret, [], []), -1, [NotInFish; NotInDocs],
87         [],
88         "internal test function - do not use",
89         "\
90 This is an internal test function which is used to test whether
91 the automatically generated bindings can handle every possible
92 return type correctly.
93
94 This function always returns an error.
95
96 You probably don't want to call this function.")]
97   ) test_all_rets
98 )
99
100 (* non_daemon_functions are any functions which don't get processed
101  * in the daemon, eg. functions for setting and getting local
102  * configuration values.
103  *)
104
105 let non_daemon_functions = test_functions @ [
106   ("launch", (RErr, [], []), -1, [FishAlias "run"],
107    [],
108    "launch the qemu subprocess",
109    "\
110 Internally libguestfs is implemented by running a virtual machine
111 using L<qemu(1)>.
112
113 You should call this after configuring the handle
114 (eg. adding drives) but before performing any actions.");
115
116   ("wait_ready", (RErr, [], []), -1, [NotInFish],
117    [],
118    "wait until the qemu subprocess launches (no op)",
119    "\
120 This function is a no op.
121
122 In versions of the API E<lt> 1.0.71 you had to call this function
123 just after calling C<guestfs_launch> to wait for the launch
124 to complete.  However this is no longer necessary because
125 C<guestfs_launch> now does the waiting.
126
127 If you see any calls to this function in code then you can just
128 remove them, unless you want to retain compatibility with older
129 versions of the API.");
130
131   ("kill_subprocess", (RErr, [], []), -1, [],
132    [],
133    "kill the qemu subprocess",
134    "\
135 This kills the qemu subprocess.  You should never need to call this.");
136
137   ("add_drive", (RErr, [String "filename"], []), -1, [],
138    [],
139    "add an image to examine or modify",
140    "\
141 This function is the equivalent of calling C<guestfs_add_drive_opts>
142 with no optional parameters, so the disk is added writable, with
143 the format being detected automatically.
144
145 Automatic detection of the format opens you up to a potential
146 security hole when dealing with untrusted raw-format images.
147 See CVE-2010-3851 and RHBZ#642934.  Specifying the format closes
148 this security hole.  Therefore you should think about replacing
149 calls to this function with calls to C<guestfs_add_drive_opts>,
150 and specifying the format.");
151
152   ("add_cdrom", (RErr, [String "filename"], []), -1, [DeprecatedBy "add_drive_opts"],
153    [],
154    "add a CD-ROM disk image to examine",
155    "\
156 This function adds a virtual CD-ROM disk image to the guest.
157
158 This is equivalent to the qemu parameter C<-cdrom filename>.
159
160 Notes:
161
162 =over 4
163
164 =item *
165
166 This call checks for the existence of C<filename>.  This
167 stops you from specifying other types of drive which are supported
168 by qemu such as C<nbd:> and C<http:> URLs.  To specify those, use
169 the general C<guestfs_config> call instead.
170
171 =item *
172
173 If you just want to add an ISO file (often you use this as an
174 efficient way to transfer large files into the guest), then you
175 should probably use C<guestfs_add_drive_ro> instead.
176
177 =back");
178
179   ("add_drive_ro", (RErr, [String "filename"], []), -1, [FishAlias "add-ro"],
180    [],
181    "add a drive in snapshot mode (read-only)",
182    "\
183 This function is the equivalent of calling C<guestfs_add_drive_opts>
184 with the optional parameter C<GUESTFS_ADD_DRIVE_OPTS_READONLY> set to 1,
185 so the disk is added read-only, with the format being detected
186 automatically.");
187
188   ("config", (RErr, [String "qemuparam"; OptString "qemuvalue"], []), -1, [],
189    [],
190    "add qemu parameters",
191    "\
192 This can be used to add arbitrary qemu command line parameters
193 of the form C<-param value>.  Actually it's not quite arbitrary - we
194 prevent you from setting some parameters which would interfere with
195 parameters that we use.
196
197 The first character of C<param> string must be a C<-> (dash).
198
199 C<value> can be NULL.");
200
201   ("set_qemu", (RErr, [OptString "qemu"], []), -1, [FishAlias "qemu"],
202    [],
203    "set the qemu binary",
204    "\
205 Set the qemu binary that we will use.
206
207 The default is chosen when the library was compiled by the
208 configure script.
209
210 You can also override this by setting the C<LIBGUESTFS_QEMU>
211 environment variable.
212
213 Setting C<qemu> to C<NULL> restores the default qemu binary.
214
215 Note that you should call this function as early as possible
216 after creating the handle.  This is because some pre-launch
217 operations depend on testing qemu features (by running C<qemu -help>).
218 If the qemu binary changes, we don't retest features, and
219 so you might see inconsistent results.  Using the environment
220 variable C<LIBGUESTFS_QEMU> is safest of all since that picks
221 the qemu binary at the same time as the handle is created.");
222
223   ("get_qemu", (RConstString "qemu", [], []), -1, [],
224    [InitNone, Always, TestRun (
225       [["get_qemu"]])],
226    "get the qemu binary",
227    "\
228 Return the current qemu binary.
229
230 This is always non-NULL.  If it wasn't set already, then this will
231 return the default qemu binary name.");
232
233   ("set_path", (RErr, [OptString "searchpath"], []), -1, [FishAlias "path"],
234    [],
235    "set the search path",
236    "\
237 Set the path that libguestfs searches for kernel and initrd.img.
238
239 The default is C<$libdir/guestfs> unless overridden by setting
240 C<LIBGUESTFS_PATH> environment variable.
241
242 Setting C<path> to C<NULL> restores the default path.");
243
244   ("get_path", (RConstString "path", [], []), -1, [],
245    [InitNone, Always, TestRun (
246       [["get_path"]])],
247    "get the search path",
248    "\
249 Return the current search path.
250
251 This is always non-NULL.  If it wasn't set already, then this will
252 return the default path.");
253
254   ("set_append", (RErr, [OptString "append"], []), -1, [FishAlias "append"],
255    [],
256    "add options to kernel command line",
257    "\
258 This function is used to add additional options to the
259 guest kernel command line.
260
261 The default is C<NULL> unless overridden by setting
262 C<LIBGUESTFS_APPEND> environment variable.
263
264 Setting C<append> to C<NULL> means I<no> additional options
265 are passed (libguestfs always adds a few of its own).");
266
267   ("get_append", (RConstOptString "append", [], []), -1, [],
268    (* This cannot be tested with the current framework.  The
269     * function can return NULL in normal operations, which the
270     * test framework interprets as an error.
271     *)
272    [],
273    "get the additional kernel options",
274    "\
275 Return the additional kernel options which are added to the
276 guest kernel command line.
277
278 If C<NULL> then no options are added.");
279
280   ("set_autosync", (RErr, [Bool "autosync"], []), -1, [FishAlias "autosync"],
281    [],
282    "set autosync mode",
283    "\
284 If C<autosync> is true, this enables autosync.  Libguestfs will make a
285 best effort attempt to run C<guestfs_umount_all> followed by
286 C<guestfs_sync> when the handle is closed
287 (also if the program exits without closing handles).
288
289 This is enabled by default (since libguestfs 1.5.24, previously it was
290 disabled by default).");
291
292   ("get_autosync", (RBool "autosync", [], []), -1, [],
293    [InitNone, Always, TestOutputTrue (
294       [["get_autosync"]])],
295    "get autosync mode",
296    "\
297 Get the autosync flag.");
298
299   ("set_verbose", (RErr, [Bool "verbose"], []), -1, [FishAlias "verbose"],
300    [],
301    "set verbose mode",
302    "\
303 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
304
305 Verbose messages are disabled unless the environment variable
306 C<LIBGUESTFS_DEBUG> is defined and set to C<1>.");
307
308   ("get_verbose", (RBool "verbose", [], []), -1, [],
309    [],
310    "get verbose mode",
311    "\
312 This returns the verbose messages flag.");
313
314   ("is_ready", (RBool "ready", [], []), -1, [],
315    [InitNone, Always, TestOutputTrue (
316       [["is_ready"]])],
317    "is ready to accept commands",
318    "\
319 This returns true iff this handle is ready to accept commands
320 (in the C<READY> state).
321
322 For more information on states, see L<guestfs(3)>.");
323
324   ("is_config", (RBool "config", [], []), -1, [],
325    [InitNone, Always, TestOutputFalse (
326       [["is_config"]])],
327    "is in configuration state",
328    "\
329 This returns true iff this handle is being configured
330 (in the C<CONFIG> state).
331
332 For more information on states, see L<guestfs(3)>.");
333
334   ("is_launching", (RBool "launching", [], []), -1, [],
335    [InitNone, Always, TestOutputFalse (
336       [["is_launching"]])],
337    "is launching subprocess",
338    "\
339 This returns true iff this handle is launching the subprocess
340 (in the C<LAUNCHING> state).
341
342 For more information on states, see L<guestfs(3)>.");
343
344   ("is_busy", (RBool "busy", [], []), -1, [],
345    [InitNone, Always, TestOutputFalse (
346       [["is_busy"]])],
347    "is busy processing a command",
348    "\
349 This returns true iff this handle is busy processing a command
350 (in the C<BUSY> state).
351
352 For more information on states, see L<guestfs(3)>.");
353
354   ("get_state", (RInt "state", [], []), -1, [],
355    [],
356    "get the current state",
357    "\
358 This returns the current state as an opaque integer.  This is
359 only useful for printing debug and internal error messages.
360
361 For more information on states, see L<guestfs(3)>.");
362
363   ("set_memsize", (RErr, [Int "memsize"], []), -1, [FishAlias "memsize"],
364    [InitNone, Always, TestOutputInt (
365       [["set_memsize"; "500"];
366        ["get_memsize"]], 500)],
367    "set memory allocated to the qemu subprocess",
368    "\
369 This sets the memory size in megabytes allocated to the
370 qemu subprocess.  This only has any effect if called before
371 C<guestfs_launch>.
372
373 You can also change this by setting the environment
374 variable C<LIBGUESTFS_MEMSIZE> before the handle is
375 created.
376
377 For more information on the architecture of libguestfs,
378 see L<guestfs(3)>.");
379
380   ("get_memsize", (RInt "memsize", [], []), -1, [],
381    [InitNone, Always, TestOutputIntOp (
382       [["get_memsize"]], ">=", 256)],
383    "get memory allocated to the qemu subprocess",
384    "\
385 This gets the memory size in megabytes allocated to the
386 qemu subprocess.
387
388 If C<guestfs_set_memsize> was not called
389 on this handle, and if C<LIBGUESTFS_MEMSIZE> was not set,
390 then this returns the compiled-in default value for memsize.
391
392 For more information on the architecture of libguestfs,
393 see L<guestfs(3)>.");
394
395   ("get_pid", (RInt "pid", [], []), -1, [FishAlias "pid"],
396    [InitNone, Always, TestOutputIntOp (
397       [["get_pid"]], ">=", 1)],
398    "get PID of qemu subprocess",
399    "\
400 Return the process ID of the qemu subprocess.  If there is no
401 qemu subprocess, then this will return an error.
402
403 This is an internal call used for debugging and testing.");
404
405   ("version", (RStruct ("version", "version"), [], []), -1, [],
406    [InitNone, Always, TestOutputStruct (
407       [["version"]], [CompareWithInt ("major", 1)])],
408    "get the library version number",
409    "\
410 Return the libguestfs version number that the program is linked
411 against.
412
413 Note that because of dynamic linking this is not necessarily
414 the version of libguestfs that you compiled against.  You can
415 compile the program, and then at runtime dynamically link
416 against a completely different C<libguestfs.so> library.
417
418 This call was added in version C<1.0.58>.  In previous
419 versions of libguestfs there was no way to get the version
420 number.  From C code you can use dynamic linker functions
421 to find out if this symbol exists (if it doesn't, then
422 it's an earlier version).
423
424 The call returns a structure with four elements.  The first
425 three (C<major>, C<minor> and C<release>) are numbers and
426 correspond to the usual version triplet.  The fourth element
427 (C<extra>) is a string and is normally empty, but may be
428 used for distro-specific information.
429
430 To construct the original version string:
431 C<$major.$minor.$release$extra>
432
433 See also: L<guestfs(3)/LIBGUESTFS VERSION NUMBERS>.
434
435 I<Note:> Don't use this call to test for availability
436 of features.  In enterprise distributions we backport
437 features from later versions into earlier versions,
438 making this an unreliable way to test for features.
439 Use C<guestfs_available> instead.");
440
441   ("set_selinux", (RErr, [Bool "selinux"], []), -1, [FishAlias "selinux"],
442    [InitNone, Always, TestOutputTrue (
443       [["set_selinux"; "true"];
444        ["get_selinux"]])],
445    "set SELinux enabled or disabled at appliance boot",
446    "\
447 This sets the selinux flag that is passed to the appliance
448 at boot time.  The default is C<selinux=0> (disabled).
449
450 Note that if SELinux is enabled, it is always in
451 Permissive mode (C<enforcing=0>).
452
453 For more information on the architecture of libguestfs,
454 see L<guestfs(3)>.");
455
456   ("get_selinux", (RBool "selinux", [], []), -1, [],
457    [],
458    "get SELinux enabled flag",
459    "\
460 This returns the current setting of the selinux flag which
461 is passed to the appliance at boot time.  See C<guestfs_set_selinux>.
462
463 For more information on the architecture of libguestfs,
464 see L<guestfs(3)>.");
465
466   ("set_trace", (RErr, [Bool "trace"], []), -1, [FishAlias "trace"],
467    [InitNone, Always, TestOutputFalse (
468       [["set_trace"; "false"];
469        ["get_trace"]])],
470    "enable or disable command traces",
471    "\
472 If the command trace flag is set to 1, then commands are
473 printed on stderr before they are executed in a format
474 which is very similar to the one used by guestfish.  In
475 other words, you can run a program with this enabled, and
476 you will get out a script which you can feed to guestfish
477 to perform the same set of actions.
478
479 If you want to trace C API calls into libguestfs (and
480 other libraries) then possibly a better way is to use
481 the external ltrace(1) command.
482
483 Command traces are disabled unless the environment variable
484 C<LIBGUESTFS_TRACE> is defined and set to C<1>.");
485
486   ("get_trace", (RBool "trace", [], []), -1, [],
487    [],
488    "get command trace enabled flag",
489    "\
490 Return the command trace flag.");
491
492   ("set_direct", (RErr, [Bool "direct"], []), -1, [FishAlias "direct"],
493    [InitNone, Always, TestOutputFalse (
494       [["set_direct"; "false"];
495        ["get_direct"]])],
496    "enable or disable direct appliance mode",
497    "\
498 If the direct appliance mode flag is enabled, then stdin and
499 stdout are passed directly through to the appliance once it
500 is launched.
501
502 One consequence of this is that log messages aren't caught
503 by the library and handled by C<guestfs_set_log_message_callback>,
504 but go straight to stdout.
505
506 You probably don't want to use this unless you know what you
507 are doing.
508
509 The default is disabled.");
510
511   ("get_direct", (RBool "direct", [], []), -1, [],
512    [],
513    "get direct appliance mode flag",
514    "\
515 Return the direct appliance mode flag.");
516
517   ("set_recovery_proc", (RErr, [Bool "recoveryproc"], []), -1, [FishAlias "recovery-proc"],
518    [InitNone, Always, TestOutputTrue (
519       [["set_recovery_proc"; "true"];
520        ["get_recovery_proc"]])],
521    "enable or disable the recovery process",
522    "\
523 If this is called with the parameter C<false> then
524 C<guestfs_launch> does not create a recovery process.  The
525 purpose of the recovery process is to stop runaway qemu
526 processes in the case where the main program aborts abruptly.
527
528 This only has any effect if called before C<guestfs_launch>,
529 and the default is true.
530
531 About the only time when you would want to disable this is
532 if the main process will fork itself into the background
533 (\"daemonize\" itself).  In this case the recovery process
534 thinks that the main program has disappeared and so kills
535 qemu, which is not very helpful.");
536
537   ("get_recovery_proc", (RBool "recoveryproc", [], []), -1, [],
538    [],
539    "get recovery process enabled flag",
540    "\
541 Return the recovery process enabled flag.");
542
543   ("add_drive_with_if", (RErr, [String "filename"; String "iface"], []), -1, [DeprecatedBy "add_drive_opts"],
544    [],
545    "add a drive specifying the QEMU block emulation to use",
546    "\
547 This is the same as C<guestfs_add_drive> but it allows you
548 to specify the QEMU interface emulation to use at run time.");
549
550   ("add_drive_ro_with_if", (RErr, [String "filename"; String "iface"], []), -1, [DeprecatedBy "add_drive_opts"],
551    [],
552    "add a drive read-only specifying the QEMU block emulation to use",
553    "\
554 This is the same as C<guestfs_add_drive_ro> but it allows you
555 to specify the QEMU interface emulation to use at run time.");
556
557   ("file_architecture", (RString "arch", [Pathname "filename"], []), -1, [],
558    [InitISOFS, Always, TestOutput (
559       [["file_architecture"; "/bin-i586-dynamic"]], "i386");
560     InitISOFS, Always, TestOutput (
561       [["file_architecture"; "/bin-sparc-dynamic"]], "sparc");
562     InitISOFS, Always, TestOutput (
563       [["file_architecture"; "/bin-win32.exe"]], "i386");
564     InitISOFS, Always, TestOutput (
565       [["file_architecture"; "/bin-win64.exe"]], "x86_64");
566     InitISOFS, Always, TestOutput (
567       [["file_architecture"; "/bin-x86_64-dynamic"]], "x86_64");
568     InitISOFS, Always, TestOutput (
569       [["file_architecture"; "/lib-i586.so"]], "i386");
570     InitISOFS, Always, TestOutput (
571       [["file_architecture"; "/lib-sparc.so"]], "sparc");
572     InitISOFS, Always, TestOutput (
573       [["file_architecture"; "/lib-win32.dll"]], "i386");
574     InitISOFS, Always, TestOutput (
575       [["file_architecture"; "/lib-win64.dll"]], "x86_64");
576     InitISOFS, Always, TestOutput (
577       [["file_architecture"; "/lib-x86_64.so"]], "x86_64");
578     InitISOFS, Always, TestOutput (
579       [["file_architecture"; "/initrd-x86_64.img"]], "x86_64");
580     InitISOFS, Always, TestOutput (
581       [["file_architecture"; "/initrd-x86_64.img.gz"]], "x86_64");],
582    "detect the architecture of a binary file",
583    "\
584 This detects the architecture of the binary C<filename>,
585 and returns it if known.
586
587 Currently defined architectures are:
588
589 =over 4
590
591 =item \"i386\"
592
593 This string is returned for all 32 bit i386, i486, i586, i686 binaries
594 irrespective of the precise processor requirements of the binary.
595
596 =item \"x86_64\"
597
598 64 bit x86-64.
599
600 =item \"sparc\"
601
602 32 bit SPARC.
603
604 =item \"sparc64\"
605
606 64 bit SPARC V9 and above.
607
608 =item \"ia64\"
609
610 Intel Itanium.
611
612 =item \"ppc\"
613
614 32 bit Power PC.
615
616 =item \"ppc64\"
617
618 64 bit Power PC.
619
620 =back
621
622 Libguestfs may return other architecture strings in future.
623
624 The function works on at least the following types of files:
625
626 =over 4
627
628 =item *
629
630 many types of Un*x and Linux binary
631
632 =item *
633
634 many types of Un*x and Linux shared library
635
636 =item *
637
638 Windows Win32 and Win64 binaries
639
640 =item *
641
642 Windows Win32 and Win64 DLLs
643
644 Win32 binaries and DLLs return C<i386>.
645
646 Win64 binaries and DLLs return C<x86_64>.
647
648 =item *
649
650 Linux kernel modules
651
652 =item *
653
654 Linux new-style initrd images
655
656 =item *
657
658 some non-x86 Linux vmlinuz kernels
659
660 =back
661
662 What it can't do currently:
663
664 =over 4
665
666 =item *
667
668 static libraries (libfoo.a)
669
670 =item *
671
672 Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
673
674 =item *
675
676 x86 Linux vmlinuz kernels
677
678 x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32- and
679 compressed code, and are horribly hard to unpack.  If you want to find
680 the architecture of a kernel, use the architecture of the associated
681 initrd or kernel module(s) instead.
682
683 =back");
684
685   ("inspect_os", (RStringList "roots", [], []), -1, [],
686    [],
687    "inspect disk and return list of operating systems found",
688    "\
689 This function uses other libguestfs functions and certain
690 heuristics to inspect the disk(s) (usually disks belonging to
691 a virtual machine), looking for operating systems.
692
693 The list returned is empty if no operating systems were found.
694
695 If one operating system was found, then this returns a list with
696 a single element, which is the name of the root filesystem of
697 this operating system.  It is also possible for this function
698 to return a list containing more than one element, indicating
699 a dual-boot or multi-boot virtual machine, with each element being
700 the root filesystem of one of the operating systems.
701
702 You can pass the root string(s) returned to other
703 C<guestfs_inspect_get_*> functions in order to query further
704 information about each operating system, such as the name
705 and version.
706
707 This function uses other libguestfs features such as
708 C<guestfs_mount_ro> and C<guestfs_umount_all> in order to mount
709 and unmount filesystems and look at the contents.  This should
710 be called with no disks currently mounted.  The function may also
711 use Augeas, so any existing Augeas handle will be closed.
712
713 This function cannot decrypt encrypted disks.  The caller
714 must do that first (supplying the necessary keys) if the
715 disk is encrypted.
716
717 Please read L<guestfs(3)/INSPECTION> for more details.
718
719 See also C<guestfs_list_filesystems>.");
720
721   ("inspect_get_type", (RString "name", [Device "root"], []), -1, [],
722    [],
723    "get type of inspected operating system",
724    "\
725 This function should only be called with a root device string
726 as returned by C<guestfs_inspect_os>.
727
728 This returns the type of the inspected operating system.
729 Currently defined types are:
730
731 =over 4
732
733 =item \"linux\"
734
735 Any Linux-based operating system.
736
737 =item \"windows\"
738
739 Any Microsoft Windows operating system.
740
741 =item \"unknown\"
742
743 The operating system type could not be determined.
744
745 =back
746
747 Future versions of libguestfs may return other strings here.
748 The caller should be prepared to handle any string.
749
750 Please read L<guestfs(3)/INSPECTION> for more details.");
751
752   ("inspect_get_arch", (RString "arch", [Device "root"], []), -1, [],
753    [],
754    "get architecture of inspected operating system",
755    "\
756 This function should only be called with a root device string
757 as returned by C<guestfs_inspect_os>.
758
759 This returns the architecture of the inspected operating system.
760 The possible return values are listed under
761 C<guestfs_file_architecture>.
762
763 If the architecture could not be determined, then the
764 string C<unknown> is returned.
765
766 Please read L<guestfs(3)/INSPECTION> for more details.");
767
768   ("inspect_get_distro", (RString "distro", [Device "root"], []), -1, [],
769    [],
770    "get distro of inspected operating system",
771    "\
772 This function should only be called with a root device string
773 as returned by C<guestfs_inspect_os>.
774
775 This returns the distro (distribution) of the inspected operating
776 system.
777
778 Currently defined distros are:
779
780 =over 4
781
782 =item \"archlinux\"
783
784 Arch Linux.
785
786 =item \"debian\"
787
788 Debian or a Debian-derived distro such as Ubuntu.
789
790 =item \"fedora\"
791
792 Fedora.
793
794 =item \"gentoo\"
795
796 Gentoo.
797
798 =item \"meego\"
799
800 MeeGo.
801
802 =item \"pardus\"
803
804 Pardus.
805
806 =item \"redhat-based\"
807
808 Some Red Hat-derived distro.
809
810 =item \"rhel\"
811
812 Red Hat Enterprise Linux and some derivatives.
813
814 =item \"windows\"
815
816 Windows does not have distributions.  This string is
817 returned if the OS type is Windows.
818
819 =item \"ubuntu\"
820
821 Ubuntu.
822
823 =item \"unknown\"
824
825 The distro could not be determined.
826
827 =back
828
829 Future versions of libguestfs may return other strings here.
830 The caller should be prepared to handle any string.
831
832 Please read L<guestfs(3)/INSPECTION> for more details.");
833
834   ("inspect_get_major_version", (RInt "major", [Device "root"], []), -1, [],
835    [],
836    "get major version of inspected operating system",
837    "\
838 This function should only be called with a root device string
839 as returned by C<guestfs_inspect_os>.
840
841 This returns the major version number of the inspected operating
842 system.
843
844 Windows uses a consistent versioning scheme which is I<not>
845 reflected in the popular public names used by the operating system.
846 Notably the operating system known as \"Windows 7\" is really
847 version 6.1 (ie. major = 6, minor = 1).  You can find out the
848 real versions corresponding to releases of Windows by consulting
849 Wikipedia or MSDN.
850
851 If the version could not be determined, then C<0> is returned.
852
853 Please read L<guestfs(3)/INSPECTION> for more details.");
854
855   ("inspect_get_minor_version", (RInt "minor", [Device "root"], []), -1, [],
856    [],
857    "get minor version of inspected operating system",
858    "\
859 This function should only be called with a root device string
860 as returned by C<guestfs_inspect_os>.
861
862 This returns the minor version number of the inspected operating
863 system.
864
865 If the version could not be determined, then C<0> is returned.
866
867 Please read L<guestfs(3)/INSPECTION> for more details.
868 See also C<guestfs_inspect_get_major_version>.");
869
870   ("inspect_get_product_name", (RString "product", [Device "root"], []), -1, [],
871    [],
872    "get product name of inspected operating system",
873    "\
874 This function should only be called with a root device string
875 as returned by C<guestfs_inspect_os>.
876
877 This returns the product name of the inspected operating
878 system.  The product name is generally some freeform string
879 which can be displayed to the user, but should not be
880 parsed by programs.
881
882 If the product name could not be determined, then the
883 string C<unknown> is returned.
884
885 Please read L<guestfs(3)/INSPECTION> for more details.");
886
887   ("inspect_get_mountpoints", (RHashtable "mountpoints", [Device "root"], []), -1, [],
888    [],
889    "get mountpoints of inspected operating system",
890    "\
891 This function should only be called with a root device string
892 as returned by C<guestfs_inspect_os>.
893
894 This returns a hash of where we think the filesystems
895 associated with this operating system should be mounted.
896 Callers should note that this is at best an educated guess
897 made by reading configuration files such as C</etc/fstab>.
898
899 Each element in the returned hashtable has a key which
900 is the path of the mountpoint (eg. C</boot>) and a value
901 which is the filesystem that would be mounted there
902 (eg. C</dev/sda1>).
903
904 Non-mounted devices such as swap devices are I<not>
905 returned in this list.
906
907 Please read L<guestfs(3)/INSPECTION> for more details.
908 See also C<guestfs_inspect_get_filesystems>.");
909
910   ("inspect_get_filesystems", (RStringList "filesystems", [Device "root"], []), -1, [],
911    [],
912    "get filesystems associated with inspected operating system",
913    "\
914 This function should only be called with a root device string
915 as returned by C<guestfs_inspect_os>.
916
917 This returns a list of all the filesystems that we think
918 are associated with this operating system.  This includes
919 the root filesystem, other ordinary filesystems, and
920 non-mounted devices like swap partitions.
921
922 In the case of a multi-boot virtual machine, it is possible
923 for a filesystem to be shared between operating systems.
924
925 Please read L<guestfs(3)/INSPECTION> for more details.
926 See also C<guestfs_inspect_get_mountpoints>.");
927
928   ("set_network", (RErr, [Bool "network"], []), -1, [FishAlias "network"],
929    [],
930    "set enable network flag",
931    "\
932 If C<network> is true, then the network is enabled in the
933 libguestfs appliance.  The default is false.
934
935 This affects whether commands are able to access the network
936 (see L<guestfs(3)/RUNNING COMMANDS>).
937
938 You must call this before calling C<guestfs_launch>, otherwise
939 it has no effect.");
940
941   ("get_network", (RBool "network", [], []), -1, [],
942    [],
943    "get enable network flag",
944    "\
945 This returns the enable network flag.");
946
947   ("list_filesystems", (RHashtable "fses", [], []), -1, [],
948    [],
949    "list filesystems",
950    "\
951 This inspection command looks for filesystems on partitions,
952 block devices and logical volumes, returning a list of devices
953 containing filesystems and their type.
954
955 The return value is a hash, where the keys are the devices
956 containing filesystems, and the values are the filesystem types.
957 For example:
958
959  \"/dev/sda1\" => \"ntfs\"
960  \"/dev/sda2\" => \"ext2\"
961  \"/dev/vg_guest/lv_root\" => \"ext4\"
962  \"/dev/vg_guest/lv_swap\" => \"swap\"
963
964 The value can have the special value \"unknown\", meaning the
965 content of the device is undetermined or empty.
966 \"swap\" means a Linux swap partition.
967
968 This command runs other libguestfs commands, which might include
969 C<guestfs_mount> and C<guestfs_umount>, and therefore you should
970 use this soon after launch and only when nothing is mounted.
971
972 Not all of the filesystems returned will be mountable.  In
973 particular, swap partitions are returned in the list.  Also
974 this command does not check that each filesystem
975 found is valid and mountable, and some filesystems might
976 be mountable but require special options.  Filesystems may
977 not all belong to a single logical operating system
978 (use C<guestfs_inspect_os> to look for OSes).");
979
980   ("add_drive_opts", (RErr, [String "filename"], [Bool "readonly"; String "format"; String "iface"]), -1, [FishAlias "add"],
981    [],
982    "add an image to examine or modify",
983    "\
984 This function adds a virtual machine disk image C<filename> to
985 libguestfs.  The first time you call this function, the disk
986 appears as C</dev/sda>, the second time as C</dev/sdb>, and
987 so on.
988
989 You don't necessarily need to be root when using libguestfs.  However
990 you obviously do need sufficient permissions to access the filename
991 for whatever operations you want to perform (ie. read access if you
992 just want to read the image or write access if you want to modify the
993 image).
994
995 This call checks that C<filename> exists.
996
997 The optional arguments are:
998
999 =over 4
1000
1001 =item C<readonly>
1002
1003 If true then the image is treated as read-only.  Writes are still
1004 allowed, but they are stored in a temporary snapshot overlay which
1005 is discarded at the end.  The disk that you add is not modified.
1006
1007 =item C<format>
1008
1009 This forces the image format.  If you omit this (or use C<guestfs_add_drive>
1010 or C<guestfs_add_drive_ro>) then the format is automatically detected.
1011 Possible formats include C<raw> and C<qcow2>.
1012
1013 Automatic detection of the format opens you up to a potential
1014 security hole when dealing with untrusted raw-format images.
1015 See CVE-2010-3851 and RHBZ#642934.  Specifying the format closes
1016 this security hole.
1017
1018 =item C<iface>
1019
1020 This rarely-used option lets you emulate the behaviour of the
1021 deprecated C<guestfs_add_drive_with_if> call (q.v.)
1022
1023 =back");
1024
1025   ("inspect_get_windows_systemroot", (RString "systemroot", [Device "root"], []), -1, [],
1026    [],
1027    "get Windows systemroot of inspected operating system",
1028    "\
1029 This function should only be called with a root device string
1030 as returned by C<guestfs_inspect_os>.
1031
1032 This returns the Windows systemroot of the inspected guest.
1033 The systemroot is a directory path such as C</WINDOWS>.
1034
1035 This call assumes that the guest is Windows and that the
1036 systemroot could be determined by inspection.  If this is not
1037 the case then an error is returned.
1038
1039 Please read L<guestfs(3)/INSPECTION> for more details.");
1040
1041 ]
1042
1043 (* daemon_functions are any functions which cause some action
1044  * to take place in the daemon.
1045  *)
1046
1047 let daemon_functions = [
1048   ("mount", (RErr, [Device "device"; String "mountpoint"], []), 1, [],
1049    [InitEmpty, Always, TestOutput (
1050       [["part_disk"; "/dev/sda"; "mbr"];
1051        ["mkfs"; "ext2"; "/dev/sda1"];
1052        ["mount"; "/dev/sda1"; "/"];
1053        ["write"; "/new"; "new file contents"];
1054        ["cat"; "/new"]], "new file contents")],
1055    "mount a guest disk at a position in the filesystem",
1056    "\
1057 Mount a guest disk at a position in the filesystem.  Block devices
1058 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
1059 the guest.  If those block devices contain partitions, they will have
1060 the usual names (eg. C</dev/sda1>).  Also LVM C</dev/VG/LV>-style
1061 names can be used.
1062
1063 The rules are the same as for L<mount(2)>:  A filesystem must
1064 first be mounted on C</> before others can be mounted.  Other
1065 filesystems can only be mounted on directories which already
1066 exist.
1067
1068 The mounted filesystem is writable, if we have sufficient permissions
1069 on the underlying device.
1070
1071 B<Important note:>
1072 When you use this call, the filesystem options C<sync> and C<noatime>
1073 are set implicitly.  This was originally done because we thought it
1074 would improve reliability, but it turns out that I<-o sync> has a
1075 very large negative performance impact and negligible effect on
1076 reliability.  Therefore we recommend that you avoid using
1077 C<guestfs_mount> in any code that needs performance, and instead
1078 use C<guestfs_mount_options> (use an empty string for the first
1079 parameter if you don't want any options).");
1080
1081   ("sync", (RErr, [], []), 2, [],
1082    [ InitEmpty, Always, TestRun [["sync"]]],
1083    "sync disks, writes are flushed through to the disk image",
1084    "\
1085 This syncs the disk, so that any writes are flushed through to the
1086 underlying disk image.
1087
1088 You should always call this if you have modified a disk image, before
1089 closing the handle.");
1090
1091   ("touch", (RErr, [Pathname "path"], []), 3, [],
1092    [InitBasicFS, Always, TestOutputTrue (
1093       [["touch"; "/new"];
1094        ["exists"; "/new"]])],
1095    "update file timestamps or create a new file",
1096    "\
1097 Touch acts like the L<touch(1)> command.  It can be used to
1098 update the timestamps on a file, or, if the file does not exist,
1099 to create a new zero-length file.
1100
1101 This command only works on regular files, and will fail on other
1102 file types such as directories, symbolic links, block special etc.");
1103
1104   ("cat", (RString "content", [Pathname "path"], []), 4, [ProtocolLimitWarning],
1105    [InitISOFS, Always, TestOutput (
1106       [["cat"; "/known-2"]], "abcdef\n")],
1107    "list the contents of a file",
1108    "\
1109 Return the contents of the file named C<path>.
1110
1111 Note that this function cannot correctly handle binary files
1112 (specifically, files containing C<\\0> character which is treated
1113 as end of string).  For those you need to use the C<guestfs_read_file>
1114 or C<guestfs_download> functions which have a more complex interface.");
1115
1116   ("ll", (RString "listing", [Pathname "directory"], []), 5, [],
1117    [], (* XXX Tricky to test because it depends on the exact format
1118         * of the 'ls -l' command, which changes between F10 and F11.
1119         *)
1120    "list the files in a directory (long format)",
1121    "\
1122 List the files in C<directory> (relative to the root directory,
1123 there is no cwd) in the format of 'ls -la'.
1124
1125 This command is mostly useful for interactive sessions.  It
1126 is I<not> intended that you try to parse the output string.");
1127
1128   ("ls", (RStringList "listing", [Pathname "directory"], []), 6, [],
1129    [InitBasicFS, Always, TestOutputList (
1130       [["touch"; "/new"];
1131        ["touch"; "/newer"];
1132        ["touch"; "/newest"];
1133        ["ls"; "/"]], ["lost+found"; "new"; "newer"; "newest"])],
1134    "list the files in a directory",
1135    "\
1136 List the files in C<directory> (relative to the root directory,
1137 there is no cwd).  The '.' and '..' entries are not returned, but
1138 hidden files are shown.
1139
1140 This command is mostly useful for interactive sessions.  Programs
1141 should probably use C<guestfs_readdir> instead.");
1142
1143   ("list_devices", (RStringList "devices", [], []), 7, [],
1144    [InitEmpty, Always, TestOutputListOfDevices (
1145       [["list_devices"]], ["/dev/sda"; "/dev/sdb"; "/dev/sdc"; "/dev/sdd"])],
1146    "list the block devices",
1147    "\
1148 List all the block devices.
1149
1150 The full block device names are returned, eg. C</dev/sda>.
1151
1152 See also C<guestfs_list_filesystems>.");
1153
1154   ("list_partitions", (RStringList "partitions", [], []), 8, [],
1155    [InitBasicFS, Always, TestOutputListOfDevices (
1156       [["list_partitions"]], ["/dev/sda1"]);
1157     InitEmpty, Always, TestOutputListOfDevices (
1158       [["part_init"; "/dev/sda"; "mbr"];
1159        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1160        ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1161        ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1162        ["list_partitions"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
1163    "list the partitions",
1164    "\
1165 List all the partitions detected on all block devices.
1166
1167 The full partition device names are returned, eg. C</dev/sda1>
1168
1169 This does not return logical volumes.  For that you will need to
1170 call C<guestfs_lvs>.
1171
1172 See also C<guestfs_list_filesystems>.");
1173
1174   ("pvs", (RStringList "physvols", [], []), 9, [Optional "lvm2"],
1175    [InitBasicFSonLVM, Always, TestOutputListOfDevices (
1176       [["pvs"]], ["/dev/sda1"]);
1177     InitEmpty, Always, TestOutputListOfDevices (
1178       [["part_init"; "/dev/sda"; "mbr"];
1179        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1180        ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1181        ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1182        ["pvcreate"; "/dev/sda1"];
1183        ["pvcreate"; "/dev/sda2"];
1184        ["pvcreate"; "/dev/sda3"];
1185        ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
1186    "list the LVM physical volumes (PVs)",
1187    "\
1188 List all the physical volumes detected.  This is the equivalent
1189 of the L<pvs(8)> command.
1190
1191 This returns a list of just the device names that contain
1192 PVs (eg. C</dev/sda2>).
1193
1194 See also C<guestfs_pvs_full>.");
1195
1196   ("vgs", (RStringList "volgroups", [], []), 10, [Optional "lvm2"],
1197    [InitBasicFSonLVM, Always, TestOutputList (
1198       [["vgs"]], ["VG"]);
1199     InitEmpty, Always, TestOutputList (
1200       [["part_init"; "/dev/sda"; "mbr"];
1201        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1202        ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1203        ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1204        ["pvcreate"; "/dev/sda1"];
1205        ["pvcreate"; "/dev/sda2"];
1206        ["pvcreate"; "/dev/sda3"];
1207        ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1208        ["vgcreate"; "VG2"; "/dev/sda3"];
1209        ["vgs"]], ["VG1"; "VG2"])],
1210    "list the LVM volume groups (VGs)",
1211    "\
1212 List all the volumes groups detected.  This is the equivalent
1213 of the L<vgs(8)> command.
1214
1215 This returns a list of just the volume group names that were
1216 detected (eg. C<VolGroup00>).
1217
1218 See also C<guestfs_vgs_full>.");
1219
1220   ("lvs", (RStringList "logvols", [], []), 11, [Optional "lvm2"],
1221    [InitBasicFSonLVM, Always, TestOutputList (
1222       [["lvs"]], ["/dev/VG/LV"]);
1223     InitEmpty, Always, TestOutputList (
1224       [["part_init"; "/dev/sda"; "mbr"];
1225        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1226        ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1227        ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1228        ["pvcreate"; "/dev/sda1"];
1229        ["pvcreate"; "/dev/sda2"];
1230        ["pvcreate"; "/dev/sda3"];
1231        ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1232        ["vgcreate"; "VG2"; "/dev/sda3"];
1233        ["lvcreate"; "LV1"; "VG1"; "50"];
1234        ["lvcreate"; "LV2"; "VG1"; "50"];
1235        ["lvcreate"; "LV3"; "VG2"; "50"];
1236        ["lvs"]], ["/dev/VG1/LV1"; "/dev/VG1/LV2"; "/dev/VG2/LV3"])],
1237    "list the LVM logical volumes (LVs)",
1238    "\
1239 List all the logical volumes detected.  This is the equivalent
1240 of the L<lvs(8)> command.
1241
1242 This returns a list of the logical volume device names
1243 (eg. C</dev/VolGroup00/LogVol00>).
1244
1245 See also C<guestfs_lvs_full>, C<guestfs_list_filesystems>.");
1246
1247   ("pvs_full", (RStructList ("physvols", "lvm_pv"), [], []), 12, [Optional "lvm2"],
1248    [], (* XXX how to test? *)
1249    "list the LVM physical volumes (PVs)",
1250    "\
1251 List all the physical volumes detected.  This is the equivalent
1252 of the L<pvs(8)> command.  The \"full\" version includes all fields.");
1253
1254   ("vgs_full", (RStructList ("volgroups", "lvm_vg"), [], []), 13, [Optional "lvm2"],
1255    [], (* XXX how to test? *)
1256    "list the LVM volume groups (VGs)",
1257    "\
1258 List all the volumes groups detected.  This is the equivalent
1259 of the L<vgs(8)> command.  The \"full\" version includes all fields.");
1260
1261   ("lvs_full", (RStructList ("logvols", "lvm_lv"), [], []), 14, [Optional "lvm2"],
1262    [], (* XXX how to test? *)
1263    "list the LVM logical volumes (LVs)",
1264    "\
1265 List all the logical volumes detected.  This is the equivalent
1266 of the L<lvs(8)> command.  The \"full\" version includes all fields.");
1267
1268   ("read_lines", (RStringList "lines", [Pathname "path"], []), 15, [],
1269    [InitISOFS, Always, TestOutputList (
1270       [["read_lines"; "/known-4"]], ["abc"; "def"; "ghi"]);
1271     InitISOFS, Always, TestOutputList (
1272       [["read_lines"; "/empty"]], [])],
1273    "read file as lines",
1274    "\
1275 Return the contents of the file named C<path>.
1276
1277 The file contents are returned as a list of lines.  Trailing
1278 C<LF> and C<CRLF> character sequences are I<not> returned.
1279
1280 Note that this function cannot correctly handle binary files
1281 (specifically, files containing C<\\0> character which is treated
1282 as end of line).  For those you need to use the C<guestfs_read_file>
1283 function which has a more complex interface.");
1284
1285   ("aug_init", (RErr, [Pathname "root"; Int "flags"], []), 16, [Optional "augeas"],
1286    [], (* XXX Augeas code needs tests. *)
1287    "create a new Augeas handle",
1288    "\
1289 Create a new Augeas handle for editing configuration files.
1290 If there was any previous Augeas handle associated with this
1291 guestfs session, then it is closed.
1292
1293 You must call this before using any other C<guestfs_aug_*>
1294 commands.
1295
1296 C<root> is the filesystem root.  C<root> must not be NULL,
1297 use C</> instead.
1298
1299 The flags are the same as the flags defined in
1300 E<lt>augeas.hE<gt>, the logical I<or> of the following
1301 integers:
1302
1303 =over 4
1304
1305 =item C<AUG_SAVE_BACKUP> = 1
1306
1307 Keep the original file with a C<.augsave> extension.
1308
1309 =item C<AUG_SAVE_NEWFILE> = 2
1310
1311 Save changes into a file with extension C<.augnew>, and
1312 do not overwrite original.  Overrides C<AUG_SAVE_BACKUP>.
1313
1314 =item C<AUG_TYPE_CHECK> = 4
1315
1316 Typecheck lenses (can be expensive).
1317
1318 =item C<AUG_NO_STDINC> = 8
1319
1320 Do not use standard load path for modules.
1321
1322 =item C<AUG_SAVE_NOOP> = 16
1323
1324 Make save a no-op, just record what would have been changed.
1325
1326 =item C<AUG_NO_LOAD> = 32
1327
1328 Do not load the tree in C<guestfs_aug_init>.
1329
1330 =back
1331
1332 To close the handle, you can call C<guestfs_aug_close>.
1333
1334 To find out more about Augeas, see L<http://augeas.net/>.");
1335
1336   ("aug_close", (RErr, [], []), 26, [Optional "augeas"],
1337    [], (* XXX Augeas code needs tests. *)
1338    "close the current Augeas handle",
1339    "\
1340 Close the current Augeas handle and free up any resources
1341 used by it.  After calling this, you have to call
1342 C<guestfs_aug_init> again before you can use any other
1343 Augeas functions.");
1344
1345   ("aug_defvar", (RInt "nrnodes", [String "name"; OptString "expr"], []), 17, [Optional "augeas"],
1346    [], (* XXX Augeas code needs tests. *)
1347    "define an Augeas variable",
1348    "\
1349 Defines an Augeas variable C<name> whose value is the result
1350 of evaluating C<expr>.  If C<expr> is NULL, then C<name> is
1351 undefined.
1352
1353 On success this returns the number of nodes in C<expr>, or
1354 C<0> if C<expr> evaluates to something which is not a nodeset.");
1355
1356   ("aug_defnode", (RStruct ("nrnodescreated", "int_bool"), [String "name"; String "expr"; String "val"], []), 18, [Optional "augeas"],
1357    [], (* XXX Augeas code needs tests. *)
1358    "define an Augeas node",
1359    "\
1360 Defines a variable C<name> whose value is the result of
1361 evaluating C<expr>.
1362
1363 If C<expr> evaluates to an empty nodeset, a node is created,
1364 equivalent to calling C<guestfs_aug_set> C<expr>, C<value>.
1365 C<name> will be the nodeset containing that single node.
1366
1367 On success this returns a pair containing the
1368 number of nodes in the nodeset, and a boolean flag
1369 if a node was created.");
1370
1371   ("aug_get", (RString "val", [String "augpath"], []), 19, [Optional "augeas"],
1372    [], (* XXX Augeas code needs tests. *)
1373    "look up the value of an Augeas path",
1374    "\
1375 Look up the value associated with C<path>.  If C<path>
1376 matches exactly one node, the C<value> is returned.");
1377
1378   ("aug_set", (RErr, [String "augpath"; String "val"], []), 20, [Optional "augeas"],
1379    [], (* XXX Augeas code needs tests. *)
1380    "set Augeas path to value",
1381    "\
1382 Set the value associated with C<path> to C<val>.
1383
1384 In the Augeas API, it is possible to clear a node by setting
1385 the value to NULL.  Due to an oversight in the libguestfs API
1386 you cannot do that with this call.  Instead you must use the
1387 C<guestfs_aug_clear> call.");
1388
1389   ("aug_insert", (RErr, [String "augpath"; String "label"; Bool "before"], []), 21, [Optional "augeas"],
1390    [], (* XXX Augeas code needs tests. *)
1391    "insert a sibling Augeas node",
1392    "\
1393 Create a new sibling C<label> for C<path>, inserting it into
1394 the tree before or after C<path> (depending on the boolean
1395 flag C<before>).
1396
1397 C<path> must match exactly one existing node in the tree, and
1398 C<label> must be a label, ie. not contain C</>, C<*> or end
1399 with a bracketed index C<[N]>.");
1400
1401   ("aug_rm", (RInt "nrnodes", [String "augpath"], []), 22, [Optional "augeas"],
1402    [], (* XXX Augeas code needs tests. *)
1403    "remove an Augeas path",
1404    "\
1405 Remove C<path> and all of its children.
1406
1407 On success this returns the number of entries which were removed.");
1408
1409   ("aug_mv", (RErr, [String "src"; String "dest"], []), 23, [Optional "augeas"],
1410    [], (* XXX Augeas code needs tests. *)
1411    "move Augeas node",
1412    "\
1413 Move the node C<src> to C<dest>.  C<src> must match exactly
1414 one node.  C<dest> is overwritten if it exists.");
1415
1416   ("aug_match", (RStringList "matches", [String "augpath"], []), 24, [Optional "augeas"],
1417    [], (* XXX Augeas code needs tests. *)
1418    "return Augeas nodes which match augpath",
1419    "\
1420 Returns a list of paths which match the path expression C<path>.
1421 The returned paths are sufficiently qualified so that they match
1422 exactly one node in the current tree.");
1423
1424   ("aug_save", (RErr, [], []), 25, [Optional "augeas"],
1425    [], (* XXX Augeas code needs tests. *)
1426    "write all pending Augeas changes to disk",
1427    "\
1428 This writes all pending changes to disk.
1429
1430 The flags which were passed to C<guestfs_aug_init> affect exactly
1431 how files are saved.");
1432
1433   ("aug_load", (RErr, [], []), 27, [Optional "augeas"],
1434    [], (* XXX Augeas code needs tests. *)
1435    "load files into the tree",
1436    "\
1437 Load files into the tree.
1438
1439 See C<aug_load> in the Augeas documentation for the full gory
1440 details.");
1441
1442   ("aug_ls", (RStringList "matches", [String "augpath"], []), 28, [Optional "augeas"],
1443    [], (* XXX Augeas code needs tests. *)
1444    "list Augeas nodes under augpath",
1445    "\
1446 This is just a shortcut for listing C<guestfs_aug_match>
1447 C<path/*> and sorting the resulting nodes into alphabetical order.");
1448
1449   ("rm", (RErr, [Pathname "path"], []), 29, [],
1450    [InitBasicFS, Always, TestRun
1451       [["touch"; "/new"];
1452        ["rm"; "/new"]];
1453     InitBasicFS, Always, TestLastFail
1454       [["rm"; "/new"]];
1455     InitBasicFS, Always, TestLastFail
1456       [["mkdir"; "/new"];
1457        ["rm"; "/new"]]],
1458    "remove a file",
1459    "\
1460 Remove the single file C<path>.");
1461
1462   ("rmdir", (RErr, [Pathname "path"], []), 30, [],
1463    [InitBasicFS, Always, TestRun
1464       [["mkdir"; "/new"];
1465        ["rmdir"; "/new"]];
1466     InitBasicFS, Always, TestLastFail
1467       [["rmdir"; "/new"]];
1468     InitBasicFS, Always, TestLastFail
1469       [["touch"; "/new"];
1470        ["rmdir"; "/new"]]],
1471    "remove a directory",
1472    "\
1473 Remove the single directory C<path>.");
1474
1475   ("rm_rf", (RErr, [Pathname "path"], []), 31, [],
1476    [InitBasicFS, Always, TestOutputFalse
1477       [["mkdir"; "/new"];
1478        ["mkdir"; "/new/foo"];
1479        ["touch"; "/new/foo/bar"];
1480        ["rm_rf"; "/new"];
1481        ["exists"; "/new"]]],
1482    "remove a file or directory recursively",
1483    "\
1484 Remove the file or directory C<path>, recursively removing the
1485 contents if its a directory.  This is like the C<rm -rf> shell
1486 command.");
1487
1488   ("mkdir", (RErr, [Pathname "path"], []), 32, [],
1489    [InitBasicFS, Always, TestOutputTrue
1490       [["mkdir"; "/new"];
1491        ["is_dir"; "/new"]];
1492     InitBasicFS, Always, TestLastFail
1493       [["mkdir"; "/new/foo/bar"]]],
1494    "create a directory",
1495    "\
1496 Create a directory named C<path>.");
1497
1498   ("mkdir_p", (RErr, [Pathname "path"], []), 33, [],
1499    [InitBasicFS, Always, TestOutputTrue
1500       [["mkdir_p"; "/new/foo/bar"];
1501        ["is_dir"; "/new/foo/bar"]];
1502     InitBasicFS, Always, TestOutputTrue
1503       [["mkdir_p"; "/new/foo/bar"];
1504        ["is_dir"; "/new/foo"]];
1505     InitBasicFS, Always, TestOutputTrue
1506       [["mkdir_p"; "/new/foo/bar"];
1507        ["is_dir"; "/new"]];
1508     (* Regression tests for RHBZ#503133: *)
1509     InitBasicFS, Always, TestRun
1510       [["mkdir"; "/new"];
1511        ["mkdir_p"; "/new"]];
1512     InitBasicFS, Always, TestLastFail
1513       [["touch"; "/new"];
1514        ["mkdir_p"; "/new"]]],
1515    "create a directory and parents",
1516    "\
1517 Create a directory named C<path>, creating any parent directories
1518 as necessary.  This is like the C<mkdir -p> shell command.");
1519
1520   ("chmod", (RErr, [Int "mode"; Pathname "path"], []), 34, [],
1521    [], (* XXX Need stat command to test *)
1522    "change file mode",
1523    "\
1524 Change the mode (permissions) of C<path> to C<mode>.  Only
1525 numeric modes are supported.
1526
1527 I<Note>: When using this command from guestfish, C<mode>
1528 by default would be decimal, unless you prefix it with
1529 C<0> to get octal, ie. use C<0700> not C<700>.
1530
1531 The mode actually set is affected by the umask.");
1532
1533   ("chown", (RErr, [Int "owner"; Int "group"; Pathname "path"], []), 35, [],
1534    [], (* XXX Need stat command to test *)
1535    "change file owner and group",
1536    "\
1537 Change the file owner to C<owner> and group to C<group>.
1538
1539 Only numeric uid and gid are supported.  If you want to use
1540 names, you will need to locate and parse the password file
1541 yourself (Augeas support makes this relatively easy).");
1542
1543   ("exists", (RBool "existsflag", [Pathname "path"], []), 36, [],
1544    [InitISOFS, Always, TestOutputTrue (
1545       [["exists"; "/empty"]]);
1546     InitISOFS, Always, TestOutputTrue (
1547       [["exists"; "/directory"]])],
1548    "test if file or directory exists",
1549    "\
1550 This returns C<true> if and only if there is a file, directory
1551 (or anything) with the given C<path> name.
1552
1553 See also C<guestfs_is_file>, C<guestfs_is_dir>, C<guestfs_stat>.");
1554
1555   ("is_file", (RBool "fileflag", [Pathname "path"], []), 37, [],
1556    [InitISOFS, Always, TestOutputTrue (
1557       [["is_file"; "/known-1"]]);
1558     InitISOFS, Always, TestOutputFalse (
1559       [["is_file"; "/directory"]])],
1560    "test if a regular file",
1561    "\
1562 This returns C<true> if and only if there is a regular file
1563 with the given C<path> name.  Note that it returns false for
1564 other objects like directories.
1565
1566 See also C<guestfs_stat>.");
1567
1568   ("is_dir", (RBool "dirflag", [Pathname "path"], []), 38, [],
1569    [InitISOFS, Always, TestOutputFalse (
1570       [["is_dir"; "/known-3"]]);
1571     InitISOFS, Always, TestOutputTrue (
1572       [["is_dir"; "/directory"]])],
1573    "test if a directory",
1574    "\
1575 This returns C<true> if and only if there is a directory
1576 with the given C<path> name.  Note that it returns false for
1577 other objects like files.
1578
1579 See also C<guestfs_stat>.");
1580
1581   ("pvcreate", (RErr, [Device "device"], []), 39, [Optional "lvm2"],
1582    [InitEmpty, Always, TestOutputListOfDevices (
1583       [["part_init"; "/dev/sda"; "mbr"];
1584        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1585        ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1586        ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1587        ["pvcreate"; "/dev/sda1"];
1588        ["pvcreate"; "/dev/sda2"];
1589        ["pvcreate"; "/dev/sda3"];
1590        ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
1591    "create an LVM physical volume",
1592    "\
1593 This creates an LVM physical volume on the named C<device>,
1594 where C<device> should usually be a partition name such
1595 as C</dev/sda1>.");
1596
1597   ("vgcreate", (RErr, [String "volgroup"; DeviceList "physvols"], []), 40, [Optional "lvm2"],
1598    [InitEmpty, Always, TestOutputList (
1599       [["part_init"; "/dev/sda"; "mbr"];
1600        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1601        ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1602        ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1603        ["pvcreate"; "/dev/sda1"];
1604        ["pvcreate"; "/dev/sda2"];
1605        ["pvcreate"; "/dev/sda3"];
1606        ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1607        ["vgcreate"; "VG2"; "/dev/sda3"];
1608        ["vgs"]], ["VG1"; "VG2"])],
1609    "create an LVM volume group",
1610    "\
1611 This creates an LVM volume group called C<volgroup>
1612 from the non-empty list of physical volumes C<physvols>.");
1613
1614   ("lvcreate", (RErr, [String "logvol"; String "volgroup"; Int "mbytes"], []), 41, [Optional "lvm2"],
1615    [InitEmpty, Always, TestOutputList (
1616       [["part_init"; "/dev/sda"; "mbr"];
1617        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1618        ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1619        ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1620        ["pvcreate"; "/dev/sda1"];
1621        ["pvcreate"; "/dev/sda2"];
1622        ["pvcreate"; "/dev/sda3"];
1623        ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1624        ["vgcreate"; "VG2"; "/dev/sda3"];
1625        ["lvcreate"; "LV1"; "VG1"; "50"];
1626        ["lvcreate"; "LV2"; "VG1"; "50"];
1627        ["lvcreate"; "LV3"; "VG2"; "50"];
1628        ["lvcreate"; "LV4"; "VG2"; "50"];
1629        ["lvcreate"; "LV5"; "VG2"; "50"];
1630        ["lvs"]],
1631       ["/dev/VG1/LV1"; "/dev/VG1/LV2";
1632        "/dev/VG2/LV3"; "/dev/VG2/LV4"; "/dev/VG2/LV5"])],
1633    "create an LVM logical volume",
1634    "\
1635 This creates an LVM logical volume called C<logvol>
1636 on the volume group C<volgroup>, with C<size> megabytes.");
1637
1638   ("mkfs", (RErr, [String "fstype"; Device "device"], []), 42, [],
1639    [InitEmpty, Always, TestOutput (
1640       [["part_disk"; "/dev/sda"; "mbr"];
1641        ["mkfs"; "ext2"; "/dev/sda1"];
1642        ["mount_options"; ""; "/dev/sda1"; "/"];
1643        ["write"; "/new"; "new file contents"];
1644        ["cat"; "/new"]], "new file contents")],
1645    "make a filesystem",
1646    "\
1647 This creates a filesystem on C<device> (usually a partition
1648 or LVM logical volume).  The filesystem type is C<fstype>, for
1649 example C<ext3>.");
1650
1651   ("sfdisk", (RErr, [Device "device";
1652                      Int "cyls"; Int "heads"; Int "sectors";
1653                      StringList "lines"], []), 43, [DangerWillRobinson],
1654    [],
1655    "create partitions on a block device",
1656    "\
1657 This is a direct interface to the L<sfdisk(8)> program for creating
1658 partitions on block devices.
1659
1660 C<device> should be a block device, for example C</dev/sda>.
1661
1662 C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads
1663 and sectors on the device, which are passed directly to sfdisk as
1664 the I<-C>, I<-H> and I<-S> parameters.  If you pass C<0> for any
1665 of these, then the corresponding parameter is omitted.  Usually for
1666 'large' disks, you can just pass C<0> for these, but for small
1667 (floppy-sized) disks, sfdisk (or rather, the kernel) cannot work
1668 out the right geometry and you will need to tell it.
1669
1670 C<lines> is a list of lines that we feed to C<sfdisk>.  For more
1671 information refer to the L<sfdisk(8)> manpage.
1672
1673 To create a single partition occupying the whole disk, you would
1674 pass C<lines> as a single element list, when the single element being
1675 the string C<,> (comma).
1676
1677 See also: C<guestfs_sfdisk_l>, C<guestfs_sfdisk_N>,
1678 C<guestfs_part_init>");
1679
1680   ("write_file", (RErr, [Pathname "path"; String "content"; Int "size"], []), 44, [ProtocolLimitWarning; DeprecatedBy "write"],
1681    (* Regression test for RHBZ#597135. *)
1682    [InitBasicFS, Always, TestLastFail
1683       [["write_file"; "/new"; "abc"; "10000"]]],
1684    "create a file",
1685    "\
1686 This call creates a file called C<path>.  The contents of the
1687 file is the string C<content> (which can contain any 8 bit data),
1688 with length C<size>.
1689
1690 As a special case, if C<size> is C<0>
1691 then the length is calculated using C<strlen> (so in this case
1692 the content cannot contain embedded ASCII NULs).
1693
1694 I<NB.> Owing to a bug, writing content containing ASCII NUL
1695 characters does I<not> work, even if the length is specified.");
1696
1697   ("umount", (RErr, [String "pathordevice"], []), 45, [FishAlias "unmount"],
1698    [InitEmpty, Always, TestOutputListOfDevices (
1699       [["part_disk"; "/dev/sda"; "mbr"];
1700        ["mkfs"; "ext2"; "/dev/sda1"];
1701        ["mount_options"; ""; "/dev/sda1"; "/"];
1702        ["mounts"]], ["/dev/sda1"]);
1703     InitEmpty, Always, TestOutputList (
1704       [["part_disk"; "/dev/sda"; "mbr"];
1705        ["mkfs"; "ext2"; "/dev/sda1"];
1706        ["mount_options"; ""; "/dev/sda1"; "/"];
1707        ["umount"; "/"];
1708        ["mounts"]], [])],
1709    "unmount a filesystem",
1710    "\
1711 This unmounts the given filesystem.  The filesystem may be
1712 specified either by its mountpoint (path) or the device which
1713 contains the filesystem.");
1714
1715   ("mounts", (RStringList "devices", [], []), 46, [],
1716    [InitBasicFS, Always, TestOutputListOfDevices (
1717       [["mounts"]], ["/dev/sda1"])],
1718    "show mounted filesystems",
1719    "\
1720 This returns the list of currently mounted filesystems.  It returns
1721 the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
1722
1723 Some internal mounts are not shown.
1724
1725 See also: C<guestfs_mountpoints>");
1726
1727   ("umount_all", (RErr, [], []), 47, [FishAlias "unmount-all"],
1728    [InitBasicFS, Always, TestOutputList (
1729       [["umount_all"];
1730        ["mounts"]], []);
1731     (* check that umount_all can unmount nested mounts correctly: *)
1732     InitEmpty, Always, TestOutputList (
1733       [["part_init"; "/dev/sda"; "mbr"];
1734        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1735        ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1736        ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1737        ["mkfs"; "ext2"; "/dev/sda1"];
1738        ["mkfs"; "ext2"; "/dev/sda2"];
1739        ["mkfs"; "ext2"; "/dev/sda3"];
1740        ["mount_options"; ""; "/dev/sda1"; "/"];
1741        ["mkdir"; "/mp1"];
1742        ["mount_options"; ""; "/dev/sda2"; "/mp1"];
1743        ["mkdir"; "/mp1/mp2"];
1744        ["mount_options"; ""; "/dev/sda3"; "/mp1/mp2"];
1745        ["mkdir"; "/mp1/mp2/mp3"];
1746        ["umount_all"];
1747        ["mounts"]], [])],
1748    "unmount all filesystems",
1749    "\
1750 This unmounts all mounted filesystems.
1751
1752 Some internal mounts are not unmounted by this call.");
1753
1754   ("lvm_remove_all", (RErr, [], []), 48, [DangerWillRobinson; Optional "lvm2"],
1755    [],
1756    "remove all LVM LVs, VGs and PVs",
1757    "\
1758 This command removes all LVM logical volumes, volume groups
1759 and physical volumes.");
1760
1761   ("file", (RString "description", [Dev_or_Path "path"], []), 49, [],
1762    [InitISOFS, Always, TestOutput (
1763       [["file"; "/empty"]], "empty");
1764     InitISOFS, Always, TestOutput (
1765       [["file"; "/known-1"]], "ASCII text");
1766     InitISOFS, Always, TestLastFail (
1767       [["file"; "/notexists"]]);
1768     InitISOFS, Always, TestOutput (
1769       [["file"; "/abssymlink"]], "symbolic link");
1770     InitISOFS, Always, TestOutput (
1771       [["file"; "/directory"]], "directory")],
1772    "determine file type",
1773    "\
1774 This call uses the standard L<file(1)> command to determine
1775 the type or contents of the file.
1776
1777 This call will also transparently look inside various types
1778 of compressed file.
1779
1780 The exact command which runs is C<file -zb path>.  Note in
1781 particular that the filename is not prepended to the output
1782 (the C<-b> option).
1783
1784 This command can also be used on C</dev/> devices
1785 (and partitions, LV names).  You can for example use this
1786 to determine if a device contains a filesystem, although
1787 it's usually better to use C<guestfs_vfs_type>.
1788
1789 If the C<path> does not begin with C</dev/> then
1790 this command only works for the content of regular files.
1791 For other file types (directory, symbolic link etc) it
1792 will just return the string C<directory> etc.");
1793
1794   ("command", (RString "output", [StringList "arguments"], []), 50, [ProtocolLimitWarning],
1795    [InitBasicFS, Always, TestOutput (
1796       [["upload"; "test-command"; "/test-command"];
1797        ["chmod"; "0o755"; "/test-command"];
1798        ["command"; "/test-command 1"]], "Result1");
1799     InitBasicFS, Always, TestOutput (
1800       [["upload"; "test-command"; "/test-command"];
1801        ["chmod"; "0o755"; "/test-command"];
1802        ["command"; "/test-command 2"]], "Result2\n");
1803     InitBasicFS, Always, TestOutput (
1804       [["upload"; "test-command"; "/test-command"];
1805        ["chmod"; "0o755"; "/test-command"];
1806        ["command"; "/test-command 3"]], "\nResult3");
1807     InitBasicFS, Always, TestOutput (
1808       [["upload"; "test-command"; "/test-command"];
1809        ["chmod"; "0o755"; "/test-command"];
1810        ["command"; "/test-command 4"]], "\nResult4\n");
1811     InitBasicFS, Always, TestOutput (
1812       [["upload"; "test-command"; "/test-command"];
1813        ["chmod"; "0o755"; "/test-command"];
1814        ["command"; "/test-command 5"]], "\nResult5\n\n");
1815     InitBasicFS, Always, TestOutput (
1816       [["upload"; "test-command"; "/test-command"];
1817        ["chmod"; "0o755"; "/test-command"];
1818        ["command"; "/test-command 6"]], "\n\nResult6\n\n");
1819     InitBasicFS, Always, TestOutput (
1820       [["upload"; "test-command"; "/test-command"];
1821        ["chmod"; "0o755"; "/test-command"];
1822        ["command"; "/test-command 7"]], "");
1823     InitBasicFS, Always, TestOutput (
1824       [["upload"; "test-command"; "/test-command"];
1825        ["chmod"; "0o755"; "/test-command"];
1826        ["command"; "/test-command 8"]], "\n");
1827     InitBasicFS, Always, TestOutput (
1828       [["upload"; "test-command"; "/test-command"];
1829        ["chmod"; "0o755"; "/test-command"];
1830        ["command"; "/test-command 9"]], "\n\n");
1831     InitBasicFS, Always, TestOutput (
1832       [["upload"; "test-command"; "/test-command"];
1833        ["chmod"; "0o755"; "/test-command"];
1834        ["command"; "/test-command 10"]], "Result10-1\nResult10-2\n");
1835     InitBasicFS, Always, TestOutput (
1836       [["upload"; "test-command"; "/test-command"];
1837        ["chmod"; "0o755"; "/test-command"];
1838        ["command"; "/test-command 11"]], "Result11-1\nResult11-2");
1839     InitBasicFS, Always, TestLastFail (
1840       [["upload"; "test-command"; "/test-command"];
1841        ["chmod"; "0o755"; "/test-command"];
1842        ["command"; "/test-command"]])],
1843    "run a command from the guest filesystem",
1844    "\
1845 This call runs a command from the guest filesystem.  The
1846 filesystem must be mounted, and must contain a compatible
1847 operating system (ie. something Linux, with the same
1848 or compatible processor architecture).
1849
1850 The single parameter is an argv-style list of arguments.
1851 The first element is the name of the program to run.
1852 Subsequent elements are parameters.  The list must be
1853 non-empty (ie. must contain a program name).  Note that
1854 the command runs directly, and is I<not> invoked via
1855 the shell (see C<guestfs_sh>).
1856
1857 The return value is anything printed to I<stdout> by
1858 the command.
1859
1860 If the command returns a non-zero exit status, then
1861 this function returns an error message.  The error message
1862 string is the content of I<stderr> from the command.
1863
1864 The C<$PATH> environment variable will contain at least
1865 C</usr/bin> and C</bin>.  If you require a program from
1866 another location, you should provide the full path in the
1867 first parameter.
1868
1869 Shared libraries and data files required by the program
1870 must be available on filesystems which are mounted in the
1871 correct places.  It is the caller's responsibility to ensure
1872 all filesystems that are needed are mounted at the right
1873 locations.");
1874
1875   ("command_lines", (RStringList "lines", [StringList "arguments"], []), 51, [ProtocolLimitWarning],
1876    [InitBasicFS, Always, TestOutputList (
1877       [["upload"; "test-command"; "/test-command"];
1878        ["chmod"; "0o755"; "/test-command"];
1879        ["command_lines"; "/test-command 1"]], ["Result1"]);
1880     InitBasicFS, Always, TestOutputList (
1881       [["upload"; "test-command"; "/test-command"];
1882        ["chmod"; "0o755"; "/test-command"];
1883        ["command_lines"; "/test-command 2"]], ["Result2"]);
1884     InitBasicFS, Always, TestOutputList (
1885       [["upload"; "test-command"; "/test-command"];
1886        ["chmod"; "0o755"; "/test-command"];
1887        ["command_lines"; "/test-command 3"]], ["";"Result3"]);
1888     InitBasicFS, Always, TestOutputList (
1889       [["upload"; "test-command"; "/test-command"];
1890        ["chmod"; "0o755"; "/test-command"];
1891        ["command_lines"; "/test-command 4"]], ["";"Result4"]);
1892     InitBasicFS, Always, TestOutputList (
1893       [["upload"; "test-command"; "/test-command"];
1894        ["chmod"; "0o755"; "/test-command"];
1895        ["command_lines"; "/test-command 5"]], ["";"Result5";""]);
1896     InitBasicFS, Always, TestOutputList (
1897       [["upload"; "test-command"; "/test-command"];
1898        ["chmod"; "0o755"; "/test-command"];
1899        ["command_lines"; "/test-command 6"]], ["";"";"Result6";""]);
1900     InitBasicFS, Always, TestOutputList (
1901       [["upload"; "test-command"; "/test-command"];
1902        ["chmod"; "0o755"; "/test-command"];
1903        ["command_lines"; "/test-command 7"]], []);
1904     InitBasicFS, Always, TestOutputList (
1905       [["upload"; "test-command"; "/test-command"];
1906        ["chmod"; "0o755"; "/test-command"];
1907        ["command_lines"; "/test-command 8"]], [""]);
1908     InitBasicFS, Always, TestOutputList (
1909       [["upload"; "test-command"; "/test-command"];
1910        ["chmod"; "0o755"; "/test-command"];
1911        ["command_lines"; "/test-command 9"]], ["";""]);
1912     InitBasicFS, Always, TestOutputList (
1913       [["upload"; "test-command"; "/test-command"];
1914        ["chmod"; "0o755"; "/test-command"];
1915        ["command_lines"; "/test-command 10"]], ["Result10-1";"Result10-2"]);
1916     InitBasicFS, Always, TestOutputList (
1917       [["upload"; "test-command"; "/test-command"];
1918        ["chmod"; "0o755"; "/test-command"];
1919        ["command_lines"; "/test-command 11"]], ["Result11-1";"Result11-2"])],
1920    "run a command, returning lines",
1921    "\
1922 This is the same as C<guestfs_command>, but splits the
1923 result into a list of lines.
1924
1925 See also: C<guestfs_sh_lines>");
1926
1927   ("stat", (RStruct ("statbuf", "stat"), [Pathname "path"], []), 52, [],
1928    [InitISOFS, Always, TestOutputStruct (
1929       [["stat"; "/empty"]], [CompareWithInt ("size", 0)])],
1930    "get file information",
1931    "\
1932 Returns file information for the given C<path>.
1933
1934 This is the same as the C<stat(2)> system call.");
1935
1936   ("lstat", (RStruct ("statbuf", "stat"), [Pathname "path"], []), 53, [],
1937    [InitISOFS, Always, TestOutputStruct (
1938       [["lstat"; "/empty"]], [CompareWithInt ("size", 0)])],
1939    "get file information for a symbolic link",
1940    "\
1941 Returns file information for the given C<path>.
1942
1943 This is the same as C<guestfs_stat> except that if C<path>
1944 is a symbolic link, then the link is stat-ed, not the file it
1945 refers to.
1946
1947 This is the same as the C<lstat(2)> system call.");
1948
1949   ("statvfs", (RStruct ("statbuf", "statvfs"), [Pathname "path"], []), 54, [],
1950    [InitISOFS, Always, TestOutputStruct (
1951       [["statvfs"; "/"]], [CompareWithInt ("namemax", 255)])],
1952    "get file system statistics",
1953    "\
1954 Returns file system statistics for any mounted file system.
1955 C<path> should be a file or directory in the mounted file system
1956 (typically it is the mount point itself, but it doesn't need to be).
1957
1958 This is the same as the C<statvfs(2)> system call.");
1959
1960   ("tune2fs_l", (RHashtable "superblock", [Device "device"], []), 55, [],
1961    [], (* XXX test *)
1962    "get ext2/ext3/ext4 superblock details",
1963    "\
1964 This returns the contents of the ext2, ext3 or ext4 filesystem
1965 superblock on C<device>.
1966
1967 It is the same as running C<tune2fs -l device>.  See L<tune2fs(8)>
1968 manpage for more details.  The list of fields returned isn't
1969 clearly defined, and depends on both the version of C<tune2fs>
1970 that libguestfs was built against, and the filesystem itself.");
1971
1972   ("blockdev_setro", (RErr, [Device "device"], []), 56, [],
1973    [InitEmpty, Always, TestOutputTrue (
1974       [["blockdev_setro"; "/dev/sda"];
1975        ["blockdev_getro"; "/dev/sda"]])],
1976    "set block device to read-only",
1977    "\
1978 Sets the block device named C<device> to read-only.
1979
1980 This uses the L<blockdev(8)> command.");
1981
1982   ("blockdev_setrw", (RErr, [Device "device"], []), 57, [],
1983    [InitEmpty, Always, TestOutputFalse (
1984       [["blockdev_setrw"; "/dev/sda"];
1985        ["blockdev_getro"; "/dev/sda"]])],
1986    "set block device to read-write",
1987    "\
1988 Sets the block device named C<device> to read-write.
1989
1990 This uses the L<blockdev(8)> command.");
1991
1992   ("blockdev_getro", (RBool "ro", [Device "device"], []), 58, [],
1993    [InitEmpty, Always, TestOutputTrue (
1994       [["blockdev_setro"; "/dev/sda"];
1995        ["blockdev_getro"; "/dev/sda"]])],
1996    "is block device set to read-only",
1997    "\
1998 Returns a boolean indicating if the block device is read-only
1999 (true if read-only, false if not).
2000
2001 This uses the L<blockdev(8)> command.");
2002
2003   ("blockdev_getss", (RInt "sectorsize", [Device "device"], []), 59, [],
2004    [InitEmpty, Always, TestOutputInt (
2005       [["blockdev_getss"; "/dev/sda"]], 512)],
2006    "get sectorsize of block device",
2007    "\
2008 This returns the size of sectors on a block device.
2009 Usually 512, but can be larger for modern devices.
2010
2011 (Note, this is not the size in sectors, use C<guestfs_blockdev_getsz>
2012 for that).
2013
2014 This uses the L<blockdev(8)> command.");
2015
2016   ("blockdev_getbsz", (RInt "blocksize", [Device "device"], []), 60, [],
2017    [InitEmpty, Always, TestOutputInt (
2018       [["blockdev_getbsz"; "/dev/sda"]], 4096)],
2019    "get blocksize of block device",
2020    "\
2021 This returns the block size of a device.
2022
2023 (Note this is different from both I<size in blocks> and
2024 I<filesystem block size>).
2025
2026 This uses the L<blockdev(8)> command.");
2027
2028   ("blockdev_setbsz", (RErr, [Device "device"; Int "blocksize"], []), 61, [],
2029    [], (* XXX test *)
2030    "set blocksize of block device",
2031    "\
2032 This sets the block size of a device.
2033
2034 (Note this is different from both I<size in blocks> and
2035 I<filesystem block size>).
2036
2037 This uses the L<blockdev(8)> command.");
2038
2039   ("blockdev_getsz", (RInt64 "sizeinsectors", [Device "device"], []), 62, [],
2040    [InitEmpty, Always, TestOutputInt (
2041       [["blockdev_getsz"; "/dev/sda"]], 1024000)],
2042    "get total size of device in 512-byte sectors",
2043    "\
2044 This returns the size of the device in units of 512-byte sectors
2045 (even if the sectorsize isn't 512 bytes ... weird).
2046
2047 See also C<guestfs_blockdev_getss> for the real sector size of
2048 the device, and C<guestfs_blockdev_getsize64> for the more
2049 useful I<size in bytes>.
2050
2051 This uses the L<blockdev(8)> command.");
2052
2053   ("blockdev_getsize64", (RInt64 "sizeinbytes", [Device "device"], []), 63, [],
2054    [InitEmpty, Always, TestOutputInt (
2055       [["blockdev_getsize64"; "/dev/sda"]], 524288000)],
2056    "get total size of device in bytes",
2057    "\
2058 This returns the size of the device in bytes.
2059
2060 See also C<guestfs_blockdev_getsz>.
2061
2062 This uses the L<blockdev(8)> command.");
2063
2064   ("blockdev_flushbufs", (RErr, [Device "device"], []), 64, [],
2065    [InitEmpty, Always, TestRun
2066       [["blockdev_flushbufs"; "/dev/sda"]]],
2067    "flush device buffers",
2068    "\
2069 This tells the kernel to flush internal buffers associated
2070 with C<device>.
2071
2072 This uses the L<blockdev(8)> command.");
2073
2074   ("blockdev_rereadpt", (RErr, [Device "device"], []), 65, [],
2075    [InitEmpty, Always, TestRun
2076       [["blockdev_rereadpt"; "/dev/sda"]]],
2077    "reread partition table",
2078    "\
2079 Reread the partition table on C<device>.
2080
2081 This uses the L<blockdev(8)> command.");
2082
2083   ("upload", (RErr, [FileIn "filename"; Dev_or_Path "remotefilename"], []), 66, [],
2084    [InitBasicFS, Always, TestOutput (
2085       (* Pick a file from cwd which isn't likely to change. *)
2086       [["upload"; "../COPYING.LIB"; "/COPYING.LIB"];
2087        ["checksum"; "md5"; "/COPYING.LIB"]],
2088       Digest.to_hex (Digest.file "COPYING.LIB"))],
2089    "upload a file from the local machine",
2090    "\
2091 Upload local file C<filename> to C<remotefilename> on the
2092 filesystem.
2093
2094 C<filename> can also be a named pipe.
2095
2096 See also C<guestfs_download>.");
2097
2098   ("download", (RErr, [Dev_or_Path "remotefilename"; FileOut "filename"], []), 67, [Progress],
2099    [InitBasicFS, Always, TestOutput (
2100       (* Pick a file from cwd which isn't likely to change. *)
2101       [["upload"; "../COPYING.LIB"; "/COPYING.LIB"];
2102        ["download"; "/COPYING.LIB"; "testdownload.tmp"];
2103        ["upload"; "testdownload.tmp"; "/upload"];
2104        ["checksum"; "md5"; "/upload"]],
2105       Digest.to_hex (Digest.file "COPYING.LIB"))],
2106    "download a file to the local machine",
2107    "\
2108 Download file C<remotefilename> and save it as C<filename>
2109 on the local machine.
2110
2111 C<filename> can also be a named pipe.
2112
2113 See also C<guestfs_upload>, C<guestfs_cat>.");
2114
2115   ("checksum", (RString "checksum", [String "csumtype"; Pathname "path"], []), 68, [],
2116    [InitISOFS, Always, TestOutput (
2117       [["checksum"; "crc"; "/known-3"]], "2891671662");
2118     InitISOFS, Always, TestLastFail (
2119       [["checksum"; "crc"; "/notexists"]]);
2120     InitISOFS, Always, TestOutput (
2121       [["checksum"; "md5"; "/known-3"]], "46d6ca27ee07cdc6fa99c2e138cc522c");
2122     InitISOFS, Always, TestOutput (
2123       [["checksum"; "sha1"; "/known-3"]], "b7ebccc3ee418311091c3eda0a45b83c0a770f15");
2124     InitISOFS, Always, TestOutput (
2125       [["checksum"; "sha224"; "/known-3"]], "d2cd1774b28f3659c14116be0a6dc2bb5c4b350ce9cd5defac707741");
2126     InitISOFS, Always, TestOutput (
2127       [["checksum"; "sha256"; "/known-3"]], "75bb71b90cd20cb13f86d2bea8dad63ac7194e7517c3b52b8d06ff52d3487d30");
2128     InitISOFS, Always, TestOutput (
2129       [["checksum"; "sha384"; "/known-3"]], "5fa7883430f357b5d7b7271d3a1d2872b51d73cba72731de6863d3dea55f30646af2799bef44d5ea776a5ec7941ac640");
2130     InitISOFS, Always, TestOutput (
2131       [["checksum"; "sha512"; "/known-3"]], "2794062c328c6b216dca90443b7f7134c5f40e56bd0ed7853123275a09982a6f992e6ca682f9d2fba34a4c5e870d8fe077694ff831e3032a004ee077e00603f6");
2132     (* Test for RHBZ#579608, absolute symbolic links. *)
2133     InitISOFS, Always, TestOutput (
2134       [["checksum"; "sha512"; "/abssymlink"]], "5f57d0639bc95081c53afc63a449403883818edc64da48930ad6b1a4fb49be90404686877743fbcd7c99811f3def7df7bc22635c885c6a8cf79c806b43451c1a")],
2135    "compute MD5, SHAx or CRC checksum of file",
2136    "\
2137 This call computes the MD5, SHAx or CRC checksum of the
2138 file named C<path>.
2139
2140 The type of checksum to compute is given by the C<csumtype>
2141 parameter which must have one of the following values:
2142
2143 =over 4
2144
2145 =item C<crc>
2146
2147 Compute the cyclic redundancy check (CRC) specified by POSIX
2148 for the C<cksum> command.
2149
2150 =item C<md5>
2151
2152 Compute the MD5 hash (using the C<md5sum> program).
2153
2154 =item C<sha1>
2155
2156 Compute the SHA1 hash (using the C<sha1sum> program).
2157
2158 =item C<sha224>
2159
2160 Compute the SHA224 hash (using the C<sha224sum> program).
2161
2162 =item C<sha256>
2163
2164 Compute the SHA256 hash (using the C<sha256sum> program).
2165
2166 =item C<sha384>
2167
2168 Compute the SHA384 hash (using the C<sha384sum> program).
2169
2170 =item C<sha512>
2171
2172 Compute the SHA512 hash (using the C<sha512sum> program).
2173
2174 =back
2175
2176 The checksum is returned as a printable string.
2177
2178 To get the checksum for a device, use C<guestfs_checksum_device>.
2179
2180 To get the checksums for many files, use C<guestfs_checksums_out>.");
2181
2182   ("tar_in", (RErr, [FileIn "tarfile"; Pathname "directory"], []), 69, [],
2183    [InitBasicFS, Always, TestOutput (
2184       [["tar_in"; "../images/helloworld.tar"; "/"];
2185        ["cat"; "/hello"]], "hello\n")],
2186    "unpack tarfile to directory",
2187    "\
2188 This command uploads and unpacks local file C<tarfile> (an
2189 I<uncompressed> tar file) into C<directory>.
2190
2191 To upload a compressed tarball, use C<guestfs_tgz_in>
2192 or C<guestfs_txz_in>.");
2193
2194   ("tar_out", (RErr, [String "directory"; FileOut "tarfile"], []), 70, [],
2195    [],
2196    "pack directory into tarfile",
2197    "\
2198 This command packs the contents of C<directory> and downloads
2199 it to local file C<tarfile>.
2200
2201 To download a compressed tarball, use C<guestfs_tgz_out>
2202 or C<guestfs_txz_out>.");
2203
2204   ("tgz_in", (RErr, [FileIn "tarball"; Pathname "directory"], []), 71, [],
2205    [InitBasicFS, Always, TestOutput (
2206       [["tgz_in"; "../images/helloworld.tar.gz"; "/"];
2207        ["cat"; "/hello"]], "hello\n")],
2208    "unpack compressed tarball to directory",
2209    "\
2210 This command uploads and unpacks local file C<tarball> (a
2211 I<gzip compressed> tar file) into C<directory>.
2212
2213 To upload an uncompressed tarball, use C<guestfs_tar_in>.");
2214
2215   ("tgz_out", (RErr, [Pathname "directory"; FileOut "tarball"], []), 72, [],
2216    [],
2217    "pack directory into compressed tarball",
2218    "\
2219 This command packs the contents of C<directory> and downloads
2220 it to local file C<tarball>.
2221
2222 To download an uncompressed tarball, use C<guestfs_tar_out>.");
2223
2224   ("mount_ro", (RErr, [Device "device"; String "mountpoint"], []), 73, [],
2225    [InitBasicFS, Always, TestLastFail (
2226       [["umount"; "/"];
2227        ["mount_ro"; "/dev/sda1"; "/"];
2228        ["touch"; "/new"]]);
2229     InitBasicFS, Always, TestOutput (
2230       [["write"; "/new"; "data"];
2231        ["umount"; "/"];
2232        ["mount_ro"; "/dev/sda1"; "/"];
2233        ["cat"; "/new"]], "data")],
2234    "mount a guest disk, read-only",
2235    "\
2236 This is the same as the C<guestfs_mount> command, but it
2237 mounts the filesystem with the read-only (I<-o ro>) flag.");
2238
2239   ("mount_options", (RErr, [String "options"; Device "device"; String "mountpoint"], []), 74, [],
2240    [],
2241    "mount a guest disk with mount options",
2242    "\
2243 This is the same as the C<guestfs_mount> command, but it
2244 allows you to set the mount options as for the
2245 L<mount(8)> I<-o> flag.
2246
2247 If the C<options> parameter is an empty string, then
2248 no options are passed (all options default to whatever
2249 the filesystem uses).");
2250
2251   ("mount_vfs", (RErr, [String "options"; String "vfstype"; Device "device"; String "mountpoint"], []), 75, [],
2252    [],
2253    "mount a guest disk with mount options and vfstype",
2254    "\
2255 This is the same as the C<guestfs_mount> command, but it
2256 allows you to set both the mount options and the vfstype
2257 as for the L<mount(8)> I<-o> and I<-t> flags.");
2258
2259   ("debug", (RString "result", [String "subcmd"; StringList "extraargs"], []), 76, [],
2260    [],
2261    "debugging and internals",
2262    "\
2263 The C<guestfs_debug> command exposes some internals of
2264 C<guestfsd> (the guestfs daemon) that runs inside the
2265 qemu subprocess.
2266
2267 There is no comprehensive help for this command.  You have
2268 to look at the file C<daemon/debug.c> in the libguestfs source
2269 to find out what you can do.");
2270
2271   ("lvremove", (RErr, [Device "device"], []), 77, [Optional "lvm2"],
2272    [InitEmpty, Always, TestOutputList (
2273       [["part_disk"; "/dev/sda"; "mbr"];
2274        ["pvcreate"; "/dev/sda1"];
2275        ["vgcreate"; "VG"; "/dev/sda1"];
2276        ["lvcreate"; "LV1"; "VG"; "50"];
2277        ["lvcreate"; "LV2"; "VG"; "50"];
2278        ["lvremove"; "/dev/VG/LV1"];
2279        ["lvs"]], ["/dev/VG/LV2"]);
2280     InitEmpty, Always, TestOutputList (
2281       [["part_disk"; "/dev/sda"; "mbr"];
2282        ["pvcreate"; "/dev/sda1"];
2283        ["vgcreate"; "VG"; "/dev/sda1"];
2284        ["lvcreate"; "LV1"; "VG"; "50"];
2285        ["lvcreate"; "LV2"; "VG"; "50"];
2286        ["lvremove"; "/dev/VG"];
2287        ["lvs"]], []);
2288     InitEmpty, Always, TestOutputList (
2289       [["part_disk"; "/dev/sda"; "mbr"];
2290        ["pvcreate"; "/dev/sda1"];
2291        ["vgcreate"; "VG"; "/dev/sda1"];
2292        ["lvcreate"; "LV1"; "VG"; "50"];
2293        ["lvcreate"; "LV2"; "VG"; "50"];
2294        ["lvremove"; "/dev/VG"];
2295        ["vgs"]], ["VG"])],
2296    "remove an LVM logical volume",
2297    "\
2298 Remove an LVM logical volume C<device>, where C<device> is
2299 the path to the LV, such as C</dev/VG/LV>.
2300
2301 You can also remove all LVs in a volume group by specifying
2302 the VG name, C</dev/VG>.");
2303
2304   ("vgremove", (RErr, [String "vgname"], []), 78, [Optional "lvm2"],
2305    [InitEmpty, Always, TestOutputList (
2306       [["part_disk"; "/dev/sda"; "mbr"];
2307        ["pvcreate"; "/dev/sda1"];
2308        ["vgcreate"; "VG"; "/dev/sda1"];
2309        ["lvcreate"; "LV1"; "VG"; "50"];
2310        ["lvcreate"; "LV2"; "VG"; "50"];
2311        ["vgremove"; "VG"];
2312        ["lvs"]], []);
2313     InitEmpty, Always, TestOutputList (
2314       [["part_disk"; "/dev/sda"; "mbr"];
2315        ["pvcreate"; "/dev/sda1"];
2316        ["vgcreate"; "VG"; "/dev/sda1"];
2317        ["lvcreate"; "LV1"; "VG"; "50"];
2318        ["lvcreate"; "LV2"; "VG"; "50"];
2319        ["vgremove"; "VG"];
2320        ["vgs"]], [])],
2321    "remove an LVM volume group",
2322    "\
2323 Remove an LVM volume group C<vgname>, (for example C<VG>).
2324
2325 This also forcibly removes all logical volumes in the volume
2326 group (if any).");
2327
2328   ("pvremove", (RErr, [Device "device"], []), 79, [Optional "lvm2"],
2329    [InitEmpty, Always, TestOutputListOfDevices (
2330       [["part_disk"; "/dev/sda"; "mbr"];
2331        ["pvcreate"; "/dev/sda1"];
2332        ["vgcreate"; "VG"; "/dev/sda1"];
2333        ["lvcreate"; "LV1"; "VG"; "50"];
2334        ["lvcreate"; "LV2"; "VG"; "50"];
2335        ["vgremove"; "VG"];
2336        ["pvremove"; "/dev/sda1"];
2337        ["lvs"]], []);
2338     InitEmpty, Always, TestOutputListOfDevices (
2339       [["part_disk"; "/dev/sda"; "mbr"];
2340        ["pvcreate"; "/dev/sda1"];
2341        ["vgcreate"; "VG"; "/dev/sda1"];
2342        ["lvcreate"; "LV1"; "VG"; "50"];
2343        ["lvcreate"; "LV2"; "VG"; "50"];
2344        ["vgremove"; "VG"];
2345        ["pvremove"; "/dev/sda1"];
2346        ["vgs"]], []);
2347     InitEmpty, Always, TestOutputListOfDevices (
2348       [["part_disk"; "/dev/sda"; "mbr"];
2349        ["pvcreate"; "/dev/sda1"];
2350        ["vgcreate"; "VG"; "/dev/sda1"];
2351        ["lvcreate"; "LV1"; "VG"; "50"];
2352        ["lvcreate"; "LV2"; "VG"; "50"];
2353        ["vgremove"; "VG"];
2354        ["pvremove"; "/dev/sda1"];
2355        ["pvs"]], [])],
2356    "remove an LVM physical volume",
2357    "\
2358 This wipes a physical volume C<device> so that LVM will no longer
2359 recognise it.
2360
2361 The implementation uses the C<pvremove> command which refuses to
2362 wipe physical volumes that contain any volume groups, so you have
2363 to remove those first.");
2364
2365   ("set_e2label", (RErr, [Device "device"; String "label"], []), 80, [],
2366    [InitBasicFS, Always, TestOutput (
2367       [["set_e2label"; "/dev/sda1"; "testlabel"];
2368        ["get_e2label"; "/dev/sda1"]], "testlabel")],
2369    "set the ext2/3/4 filesystem label",
2370    "\
2371 This sets the ext2/3/4 filesystem label of the filesystem on
2372 C<device> to C<label>.  Filesystem labels are limited to
2373 16 characters.
2374
2375 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2label>
2376 to return the existing label on a filesystem.");
2377
2378   ("get_e2label", (RString "label", [Device "device"], []), 81, [DeprecatedBy "vfs_label"],
2379    [],
2380    "get the ext2/3/4 filesystem label",
2381    "\
2382 This returns the ext2/3/4 filesystem label of the filesystem on
2383 C<device>.");
2384
2385   ("set_e2uuid", (RErr, [Device "device"; String "uuid"], []), 82, [],
2386    (let uuid = uuidgen () in
2387     [InitBasicFS, Always, TestOutput (
2388        [["set_e2uuid"; "/dev/sda1"; uuid];
2389         ["get_e2uuid"; "/dev/sda1"]], uuid);
2390      InitBasicFS, Always, TestOutput (
2391        [["set_e2uuid"; "/dev/sda1"; "clear"];
2392         ["get_e2uuid"; "/dev/sda1"]], "");
2393      (* We can't predict what UUIDs will be, so just check the commands run. *)
2394      InitBasicFS, Always, TestRun (
2395        [["set_e2uuid"; "/dev/sda1"; "random"]]);
2396      InitBasicFS, Always, TestRun (
2397        [["set_e2uuid"; "/dev/sda1"; "time"]])]),
2398    "set the ext2/3/4 filesystem UUID",
2399    "\
2400 This sets the ext2/3/4 filesystem UUID of the filesystem on
2401 C<device> to C<uuid>.  The format of the UUID and alternatives
2402 such as C<clear>, C<random> and C<time> are described in the
2403 L<tune2fs(8)> manpage.
2404
2405 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2uuid>
2406 to return the existing UUID of a filesystem.");
2407
2408   ("get_e2uuid", (RString "uuid", [Device "device"], []), 83, [DeprecatedBy "vfs_uuid"],
2409    (* Regression test for RHBZ#597112. *)
2410    (let uuid = uuidgen () in
2411     [InitBasicFS, Always, TestOutput (
2412        [["mke2journal"; "1024"; "/dev/sdb"];
2413         ["set_e2uuid"; "/dev/sdb"; uuid];
2414         ["get_e2uuid"; "/dev/sdb"]], uuid)]),
2415    "get the ext2/3/4 filesystem UUID",
2416    "\
2417 This returns the ext2/3/4 filesystem UUID of the filesystem on
2418 C<device>.");
2419
2420   ("fsck", (RInt "status", [String "fstype"; Device "device"], []), 84, [FishOutput FishOutputHexadecimal],
2421    [InitBasicFS, Always, TestOutputInt (
2422       [["umount"; "/dev/sda1"];
2423        ["fsck"; "ext2"; "/dev/sda1"]], 0);
2424     InitBasicFS, Always, TestOutputInt (
2425       [["umount"; "/dev/sda1"];
2426        ["zero"; "/dev/sda1"];
2427        ["fsck"; "ext2"; "/dev/sda1"]], 8)],
2428    "run the filesystem checker",
2429    "\
2430 This runs the filesystem checker (fsck) on C<device> which
2431 should have filesystem type C<fstype>.
2432
2433 The returned integer is the status.  See L<fsck(8)> for the
2434 list of status codes from C<fsck>.
2435
2436 Notes:
2437
2438 =over 4
2439
2440 =item *
2441
2442 Multiple status codes can be summed together.
2443
2444 =item *
2445
2446 A non-zero return code can mean \"success\", for example if
2447 errors have been corrected on the filesystem.
2448
2449 =item *
2450
2451 Checking or repairing NTFS volumes is not supported
2452 (by linux-ntfs).
2453
2454 =back
2455
2456 This command is entirely equivalent to running C<fsck -a -t fstype device>.");
2457
2458   ("zero", (RErr, [Device "device"], []), 85, [Progress],
2459    [InitBasicFS, Always, TestOutput (
2460       [["umount"; "/dev/sda1"];
2461        ["zero"; "/dev/sda1"];
2462        ["file"; "/dev/sda1"]], "data")],
2463    "write zeroes to the device",
2464    "\
2465 This command writes zeroes over the first few blocks of C<device>.
2466
2467 How many blocks are zeroed isn't specified (but it's I<not> enough
2468 to securely wipe the device).  It should be sufficient to remove
2469 any partition tables, filesystem superblocks and so on.
2470
2471 See also: C<guestfs_zero_device>, C<guestfs_scrub_device>.");
2472
2473   ("grub_install", (RErr, [Pathname "root"; Device "device"], []), 86, [],
2474    (* See:
2475     * https://bugzilla.redhat.com/show_bug.cgi?id=484986
2476     * https://bugzilla.redhat.com/show_bug.cgi?id=479760
2477     *)
2478    [InitBasicFS, Always, TestOutputTrue (
2479       [["mkdir_p"; "/boot/grub"];
2480        ["write"; "/boot/grub/device.map"; "(hd0) /dev/vda"];
2481        ["grub_install"; "/"; "/dev/vda"];
2482        ["is_dir"; "/boot"]])],
2483    "install GRUB",
2484    "\
2485 This command installs GRUB (the Grand Unified Bootloader) on
2486 C<device>, with the root directory being C<root>.
2487
2488 Note: If grub-install reports the error
2489 \"No suitable drive was found in the generated device map.\"
2490 it may be that you need to create a C</boot/grub/device.map>
2491 file first that contains the mapping between grub device names
2492 and Linux device names.  It is usually sufficient to create
2493 a file containing:
2494
2495  (hd0) /dev/vda
2496
2497 replacing C</dev/vda> with the name of the installation device.");
2498
2499   ("cp", (RErr, [Pathname "src"; Pathname "dest"], []), 87, [],
2500    [InitBasicFS, Always, TestOutput (
2501       [["write"; "/old"; "file content"];
2502        ["cp"; "/old"; "/new"];
2503        ["cat"; "/new"]], "file content");
2504     InitBasicFS, Always, TestOutputTrue (
2505       [["write"; "/old"; "file content"];
2506        ["cp"; "/old"; "/new"];
2507        ["is_file"; "/old"]]);
2508     InitBasicFS, Always, TestOutput (
2509       [["write"; "/old"; "file content"];
2510        ["mkdir"; "/dir"];
2511        ["cp"; "/old"; "/dir/new"];
2512        ["cat"; "/dir/new"]], "file content")],
2513    "copy a file",
2514    "\
2515 This copies a file from C<src> to C<dest> where C<dest> is
2516 either a destination filename or destination directory.");
2517
2518   ("cp_a", (RErr, [Pathname "src"; Pathname "dest"], []), 88, [],
2519    [InitBasicFS, Always, TestOutput (
2520       [["mkdir"; "/olddir"];
2521        ["mkdir"; "/newdir"];
2522        ["write"; "/olddir/file"; "file content"];
2523        ["cp_a"; "/olddir"; "/newdir"];
2524        ["cat"; "/newdir/olddir/file"]], "file content")],
2525    "copy a file or directory recursively",
2526    "\
2527 This copies a file or directory from C<src> to C<dest>
2528 recursively using the C<cp -a> command.");
2529
2530   ("mv", (RErr, [Pathname "src"; Pathname "dest"], []), 89, [],
2531    [InitBasicFS, Always, TestOutput (
2532       [["write"; "/old"; "file content"];
2533        ["mv"; "/old"; "/new"];
2534        ["cat"; "/new"]], "file content");
2535     InitBasicFS, Always, TestOutputFalse (
2536       [["write"; "/old"; "file content"];
2537        ["mv"; "/old"; "/new"];
2538        ["is_file"; "/old"]])],
2539    "move a file",
2540    "\
2541 This moves a file from C<src> to C<dest> where C<dest> is
2542 either a destination filename or destination directory.");
2543
2544   ("drop_caches", (RErr, [Int "whattodrop"], []), 90, [],
2545    [InitEmpty, Always, TestRun (
2546       [["drop_caches"; "3"]])],
2547    "drop kernel page cache, dentries and inodes",
2548    "\
2549 This instructs the guest kernel to drop its page cache,
2550 and/or dentries and inode caches.  The parameter C<whattodrop>
2551 tells the kernel what precisely to drop, see
2552 L<http://linux-mm.org/Drop_Caches>
2553
2554 Setting C<whattodrop> to 3 should drop everything.
2555
2556 This automatically calls L<sync(2)> before the operation,
2557 so that the maximum guest memory is freed.");
2558
2559   ("dmesg", (RString "kmsgs", [], []), 91, [],
2560    [InitEmpty, Always, TestRun (
2561       [["dmesg"]])],
2562    "return kernel messages",
2563    "\
2564 This returns the kernel messages (C<dmesg> output) from
2565 the guest kernel.  This is sometimes useful for extended
2566 debugging of problems.
2567
2568 Another way to get the same information is to enable
2569 verbose messages with C<guestfs_set_verbose> or by setting
2570 the environment variable C<LIBGUESTFS_DEBUG=1> before
2571 running the program.");
2572
2573   ("ping_daemon", (RErr, [], []), 92, [],
2574    [InitEmpty, Always, TestRun (
2575       [["ping_daemon"]])],
2576    "ping the guest daemon",
2577    "\
2578 This is a test probe into the guestfs daemon running inside
2579 the qemu subprocess.  Calling this function checks that the
2580 daemon responds to the ping message, without affecting the daemon
2581 or attached block device(s) in any other way.");
2582
2583   ("equal", (RBool "equality", [Pathname "file1"; Pathname "file2"], []), 93, [],
2584    [InitBasicFS, Always, TestOutputTrue (
2585       [["write"; "/file1"; "contents of a file"];
2586        ["cp"; "/file1"; "/file2"];
2587        ["equal"; "/file1"; "/file2"]]);
2588     InitBasicFS, Always, TestOutputFalse (
2589       [["write"; "/file1"; "contents of a file"];
2590        ["write"; "/file2"; "contents of another file"];
2591        ["equal"; "/file1"; "/file2"]]);
2592     InitBasicFS, Always, TestLastFail (
2593       [["equal"; "/file1"; "/file2"]])],
2594    "test if two files have equal contents",
2595    "\
2596 This compares the two files C<file1> and C<file2> and returns
2597 true if their content is exactly equal, or false otherwise.
2598
2599 The external L<cmp(1)> program is used for the comparison.");
2600
2601   ("strings", (RStringList "stringsout", [Pathname "path"], []), 94, [ProtocolLimitWarning],
2602    [InitISOFS, Always, TestOutputList (
2603       [["strings"; "/known-5"]], ["abcdefghi"; "jklmnopqr"]);
2604     InitISOFS, Always, TestOutputList (
2605       [["strings"; "/empty"]], []);
2606     (* Test for RHBZ#579608, absolute symbolic links. *)
2607     InitISOFS, Always, TestRun (
2608       [["strings"; "/abssymlink"]])],
2609    "print the printable strings in a file",
2610    "\
2611 This runs the L<strings(1)> command on a file and returns
2612 the list of printable strings found.");
2613
2614   ("strings_e", (RStringList "stringsout", [String "encoding"; Pathname "path"], []), 95, [ProtocolLimitWarning],
2615    [InitISOFS, Always, TestOutputList (
2616       [["strings_e"; "b"; "/known-5"]], []);
2617     InitBasicFS, Always, TestOutputList (
2618       [["write"; "/new"; "\000h\000e\000l\000l\000o\000\n\000w\000o\000r\000l\000d\000\n"];
2619        ["strings_e"; "b"; "/new"]], ["hello"; "world"])],
2620    "print the printable strings in a file",
2621    "\
2622 This is like the C<guestfs_strings> command, but allows you to
2623 specify the encoding of strings that are looked for in
2624 the source file C<path>.
2625
2626 Allowed encodings are:
2627
2628 =over 4
2629
2630 =item s
2631
2632 Single 7-bit-byte characters like ASCII and the ASCII-compatible
2633 parts of ISO-8859-X (this is what C<guestfs_strings> uses).
2634
2635 =item S
2636
2637 Single 8-bit-byte characters.
2638
2639 =item b
2640
2641 16-bit big endian strings such as those encoded in
2642 UTF-16BE or UCS-2BE.
2643
2644 =item l (lower case letter L)
2645
2646 16-bit little endian such as UTF-16LE and UCS-2LE.
2647 This is useful for examining binaries in Windows guests.
2648
2649 =item B
2650
2651 32-bit big endian such as UCS-4BE.
2652
2653 =item L
2654
2655 32-bit little endian such as UCS-4LE.
2656
2657 =back
2658
2659 The returned strings are transcoded to UTF-8.");
2660
2661   ("hexdump", (RString "dump", [Pathname "path"], []), 96, [ProtocolLimitWarning],
2662    [InitISOFS, Always, TestOutput (
2663       [["hexdump"; "/known-4"]], "00000000  61 62 63 0a 64 65 66 0a  67 68 69                 |abc.def.ghi|\n0000000b\n");
2664     (* Test for RHBZ#501888c2 regression which caused large hexdump
2665      * commands to segfault.
2666      *)
2667     InitISOFS, Always, TestRun (
2668       [["hexdump"; "/100krandom"]]);
2669     (* Test for RHBZ#579608, absolute symbolic links. *)
2670     InitISOFS, Always, TestRun (
2671       [["hexdump"; "/abssymlink"]])],
2672    "dump a file in hexadecimal",
2673    "\
2674 This runs C<hexdump -C> on the given C<path>.  The result is
2675 the human-readable, canonical hex dump of the file.");
2676
2677   ("zerofree", (RErr, [Device "device"], []), 97, [Optional "zerofree"],
2678    [InitNone, Always, TestOutput (
2679       [["part_disk"; "/dev/sda"; "mbr"];
2680        ["mkfs"; "ext3"; "/dev/sda1"];
2681        ["mount_options"; ""; "/dev/sda1"; "/"];
2682        ["write"; "/new"; "test file"];
2683        ["umount"; "/dev/sda1"];
2684        ["zerofree"; "/dev/sda1"];
2685        ["mount_options"; ""; "/dev/sda1"; "/"];
2686        ["cat"; "/new"]], "test file")],
2687    "zero unused inodes and disk blocks on ext2/3 filesystem",
2688    "\
2689 This runs the I<zerofree> program on C<device>.  This program
2690 claims to zero unused inodes and disk blocks on an ext2/3
2691 filesystem, thus making it possible to compress the filesystem
2692 more effectively.
2693
2694 You should B<not> run this program if the filesystem is
2695 mounted.
2696
2697 It is possible that using this program can damage the filesystem
2698 or data on the filesystem.");
2699
2700   ("pvresize", (RErr, [Device "device"], []), 98, [Optional "lvm2"],
2701    [],
2702    "resize an LVM physical volume",
2703    "\
2704 This resizes (expands or shrinks) an existing LVM physical
2705 volume to match the new size of the underlying device.");
2706
2707   ("sfdisk_N", (RErr, [Device "device"; Int "partnum";
2708                        Int "cyls"; Int "heads"; Int "sectors";
2709                        String "line"], []), 99, [DangerWillRobinson],
2710    [],
2711    "modify a single partition on a block device",
2712    "\
2713 This runs L<sfdisk(8)> option to modify just the single
2714 partition C<n> (note: C<n> counts from 1).
2715
2716 For other parameters, see C<guestfs_sfdisk>.  You should usually
2717 pass C<0> for the cyls/heads/sectors parameters.
2718
2719 See also: C<guestfs_part_add>");
2720
2721   ("sfdisk_l", (RString "partitions", [Device "device"], []), 100, [],
2722    [],
2723    "display the partition table",
2724    "\
2725 This displays the partition table on C<device>, in the
2726 human-readable output of the L<sfdisk(8)> command.  It is
2727 not intended to be parsed.
2728
2729 See also: C<guestfs_part_list>");
2730
2731   ("sfdisk_kernel_geometry", (RString "partitions", [Device "device"], []), 101, [],
2732    [],
2733    "display the kernel geometry",
2734    "\
2735 This displays the kernel's idea of the geometry of C<device>.
2736
2737 The result is in human-readable format, and not designed to
2738 be parsed.");
2739
2740   ("sfdisk_disk_geometry", (RString "partitions", [Device "device"], []), 102, [],
2741    [],
2742    "display the disk geometry from the partition table",
2743    "\
2744 This displays the disk geometry of C<device> read from the
2745 partition table.  Especially in the case where the underlying
2746 block device has been resized, this can be different from the
2747 kernel's idea of the geometry (see C<guestfs_sfdisk_kernel_geometry>).
2748
2749 The result is in human-readable format, and not designed to
2750 be parsed.");
2751
2752   ("vg_activate_all", (RErr, [Bool "activate"], []), 103, [Optional "lvm2"],
2753    [],
2754    "activate or deactivate all volume groups",
2755    "\
2756 This command activates or (if C<activate> is false) deactivates
2757 all logical volumes in all volume groups.
2758 If activated, then they are made known to the
2759 kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
2760 then those devices disappear.
2761
2762 This command is the same as running C<vgchange -a y|n>");
2763
2764   ("vg_activate", (RErr, [Bool "activate"; StringList "volgroups"], []), 104, [Optional "lvm2"],
2765    [],
2766    "activate or deactivate some volume groups",
2767    "\
2768 This command activates or (if C<activate> is false) deactivates
2769 all logical volumes in the listed volume groups C<volgroups>.
2770 If activated, then they are made known to the
2771 kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
2772 then those devices disappear.
2773
2774 This command is the same as running C<vgchange -a y|n volgroups...>
2775
2776 Note that if C<volgroups> is an empty list then B<all> volume groups
2777 are activated or deactivated.");
2778
2779   ("lvresize", (RErr, [Device "device"; Int "mbytes"], []), 105, [Optional "lvm2"],
2780    [InitNone, Always, TestOutput (
2781       [["part_disk"; "/dev/sda"; "mbr"];
2782        ["pvcreate"; "/dev/sda1"];
2783        ["vgcreate"; "VG"; "/dev/sda1"];
2784        ["lvcreate"; "LV"; "VG"; "10"];
2785        ["mkfs"; "ext2"; "/dev/VG/LV"];
2786        ["mount_options"; ""; "/dev/VG/LV"; "/"];
2787        ["write"; "/new"; "test content"];
2788        ["umount"; "/"];
2789        ["lvresize"; "/dev/VG/LV"; "20"];
2790        ["e2fsck_f"; "/dev/VG/LV"];
2791        ["resize2fs"; "/dev/VG/LV"];
2792        ["mount_options"; ""; "/dev/VG/LV"; "/"];
2793        ["cat"; "/new"]], "test content");
2794     InitNone, Always, TestRun (
2795       (* Make an LV smaller to test RHBZ#587484. *)
2796       [["part_disk"; "/dev/sda"; "mbr"];
2797        ["pvcreate"; "/dev/sda1"];
2798        ["vgcreate"; "VG"; "/dev/sda1"];
2799        ["lvcreate"; "LV"; "VG"; "20"];
2800        ["lvresize"; "/dev/VG/LV"; "10"]])],
2801    "resize an LVM logical volume",
2802    "\
2803 This resizes (expands or shrinks) an existing LVM logical
2804 volume to C<mbytes>.  When reducing, data in the reduced part
2805 is lost.");
2806
2807   ("resize2fs", (RErr, [Device "device"], []), 106, [],
2808    [], (* lvresize tests this *)
2809    "resize an ext2, ext3 or ext4 filesystem",
2810    "\
2811 This resizes an ext2, ext3 or ext4 filesystem to match the size of
2812 the underlying device.
2813
2814 I<Note:> It is sometimes required that you run C<guestfs_e2fsck_f>
2815 on the C<device> before calling this command.  For unknown reasons
2816 C<resize2fs> sometimes gives an error about this and sometimes not.
2817 In any case, it is always safe to call C<guestfs_e2fsck_f> before
2818 calling this function.");
2819
2820   ("find", (RStringList "names", [Pathname "directory"], []), 107, [ProtocolLimitWarning],
2821    [InitBasicFS, Always, TestOutputList (
2822       [["find"; "/"]], ["lost+found"]);
2823     InitBasicFS, Always, TestOutputList (
2824       [["touch"; "/a"];
2825        ["mkdir"; "/b"];
2826        ["touch"; "/b/c"];
2827        ["find"; "/"]], ["a"; "b"; "b/c"; "lost+found"]);
2828     InitBasicFS, Always, TestOutputList (
2829       [["mkdir_p"; "/a/b/c"];
2830        ["touch"; "/a/b/c/d"];
2831        ["find"; "/a/b/"]], ["c"; "c/d"])],
2832    "find all files and directories",
2833    "\
2834 This command lists out all files and directories, recursively,
2835 starting at C<directory>.  It is essentially equivalent to
2836 running the shell command C<find directory -print> but some
2837 post-processing happens on the output, described below.
2838
2839 This returns a list of strings I<without any prefix>.  Thus
2840 if the directory structure was:
2841
2842  /tmp/a
2843  /tmp/b
2844  /tmp/c/d
2845
2846 then the returned list from C<guestfs_find> C</tmp> would be
2847 4 elements:
2848
2849  a
2850  b
2851  c
2852  c/d
2853
2854 If C<directory> is not a directory, then this command returns
2855 an error.
2856
2857 The returned list is sorted.
2858
2859 See also C<guestfs_find0>.");
2860
2861   ("e2fsck_f", (RErr, [Device "device"], []), 108, [],
2862    [], (* lvresize tests this *)
2863    "check an ext2/ext3 filesystem",
2864    "\
2865 This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3
2866 filesystem checker on C<device>, noninteractively (C<-p>),
2867 even if the filesystem appears to be clean (C<-f>).
2868
2869 This command is only needed because of C<guestfs_resize2fs>
2870 (q.v.).  Normally you should use C<guestfs_fsck>.");
2871
2872   ("sleep", (RErr, [Int "secs"], []), 109, [],
2873    [InitNone, Always, TestRun (
2874       [["sleep"; "1"]])],
2875    "sleep for some seconds",
2876    "\
2877 Sleep for C<secs> seconds.");
2878
2879   ("ntfs_3g_probe", (RInt "status", [Bool "rw"; Device "device"], []), 110, [Optional "ntfs3g"],
2880    [InitNone, Always, TestOutputInt (
2881       [["part_disk"; "/dev/sda"; "mbr"];
2882        ["mkfs"; "ntfs"; "/dev/sda1"];
2883        ["ntfs_3g_probe"; "true"; "/dev/sda1"]], 0);
2884     InitNone, Always, TestOutputInt (
2885       [["part_disk"; "/dev/sda"; "mbr"];
2886        ["mkfs"; "ext2"; "/dev/sda1"];
2887        ["ntfs_3g_probe"; "true"; "/dev/sda1"]], 12)],
2888    "probe NTFS volume",
2889    "\
2890 This command runs the L<ntfs-3g.probe(8)> command which probes
2891 an NTFS C<device> for mountability.  (Not all NTFS volumes can
2892 be mounted read-write, and some cannot be mounted at all).
2893
2894 C<rw> is a boolean flag.  Set it to true if you want to test
2895 if the volume can be mounted read-write.  Set it to false if
2896 you want to test if the volume can be mounted read-only.
2897
2898 The return value is an integer which C<0> if the operation
2899 would succeed, or some non-zero value documented in the
2900 L<ntfs-3g.probe(8)> manual page.");
2901
2902   ("sh", (RString "output", [String "command"], []), 111, [],
2903    [], (* XXX needs tests *)
2904    "run a command via the shell",
2905    "\
2906 This call runs a command from the guest filesystem via the
2907 guest's C</bin/sh>.
2908
2909 This is like C<guestfs_command>, but passes the command to:
2910
2911  /bin/sh -c \"command\"
2912
2913 Depending on the guest's shell, this usually results in
2914 wildcards being expanded, shell expressions being interpolated
2915 and so on.
2916
2917 All the provisos about C<guestfs_command> apply to this call.");
2918
2919   ("sh_lines", (RStringList "lines", [String "command"], []), 112, [],
2920    [], (* XXX needs tests *)
2921    "run a command via the shell returning lines",
2922    "\
2923 This is the same as C<guestfs_sh>, but splits the result
2924 into a list of lines.
2925
2926 See also: C<guestfs_command_lines>");
2927
2928   ("glob_expand", (RStringList "paths", [Pathname "pattern"], []), 113, [],
2929    (* Use Pathname here, and hence ABS_PATH (pattern,... in generated
2930     * code in stubs.c, since all valid glob patterns must start with "/".
2931     * There is no concept of "cwd" in libguestfs, hence no "."-relative names.
2932     *)
2933    [InitBasicFS, Always, TestOutputList (
2934       [["mkdir_p"; "/a/b/c"];
2935        ["touch"; "/a/b/c/d"];
2936        ["touch"; "/a/b/c/e"];
2937        ["glob_expand"; "/a/b/c/*"]], ["/a/b/c/d"; "/a/b/c/e"]);
2938     InitBasicFS, Always, TestOutputList (
2939       [["mkdir_p"; "/a/b/c"];
2940        ["touch"; "/a/b/c/d"];
2941        ["touch"; "/a/b/c/e"];
2942        ["glob_expand"; "/a/*/c/*"]], ["/a/b/c/d"; "/a/b/c/e"]);
2943     InitBasicFS, Always, TestOutputList (
2944       [["mkdir_p"; "/a/b/c"];
2945        ["touch"; "/a/b/c/d"];
2946        ["touch"; "/a/b/c/e"];
2947        ["glob_expand"; "/a/*/x/*"]], [])],
2948    "expand a wildcard path",
2949    "\
2950 This command searches for all the pathnames matching
2951 C<pattern> according to the wildcard expansion rules
2952 used by the shell.
2953
2954 If no paths match, then this returns an empty list
2955 (note: not an error).
2956
2957 It is just a wrapper around the C L<glob(3)> function
2958 with flags C<GLOB_MARK|GLOB_BRACE>.
2959 See that manual page for more details.");
2960
2961   ("scrub_device", (RErr, [Device "device"], []), 114, [DangerWillRobinson; Optional "scrub"],
2962    [InitNone, Always, TestRun ( (* use /dev/sdc because it's smaller *)
2963       [["scrub_device"; "/dev/sdc"]])],
2964    "scrub (securely wipe) a device",
2965    "\
2966 This command writes patterns over C<device> to make data retrieval
2967 more difficult.
2968
2969 It is an interface to the L<scrub(1)> program.  See that
2970 manual page for more details.");
2971
2972   ("scrub_file", (RErr, [Pathname "file"], []), 115, [Optional "scrub"],
2973    [InitBasicFS, Always, TestRun (
2974       [["write"; "/file"; "content"];
2975        ["scrub_file"; "/file"]])],
2976    "scrub (securely wipe) a file",
2977    "\
2978 This command writes patterns over a file to make data retrieval
2979 more difficult.
2980
2981 The file is I<removed> after scrubbing.
2982
2983 It is an interface to the L<scrub(1)> program.  See that
2984 manual page for more details.");
2985
2986   ("scrub_freespace", (RErr, [Pathname "dir"], []), 116, [Optional "scrub"],
2987    [], (* XXX needs testing *)
2988    "scrub (securely wipe) free space",
2989    "\
2990 This command creates the directory C<dir> and then fills it
2991 with files until the filesystem is full, and scrubs the files
2992 as for C<guestfs_scrub_file>, and deletes them.
2993 The intention is to scrub any free space on the partition
2994 containing C<dir>.
2995
2996 It is an interface to the L<scrub(1)> program.  See that
2997 manual page for more details.");
2998
2999   ("mkdtemp", (RString "dir", [Pathname "template"], []), 117, [],
3000    [InitBasicFS, Always, TestRun (
3001       [["mkdir"; "/tmp"];
3002        ["mkdtemp"; "/tmp/tmpXXXXXX"]])],
3003    "create a temporary directory",
3004    "\
3005 This command creates a temporary directory.  The
3006 C<template> parameter should be a full pathname for the
3007 temporary directory name with the final six characters being
3008 \"XXXXXX\".
3009
3010 For example: \"/tmp/myprogXXXXXX\" or \"/Temp/myprogXXXXXX\",
3011 the second one being suitable for Windows filesystems.
3012
3013 The name of the temporary directory that was created
3014 is returned.
3015
3016 The temporary directory is created with mode 0700
3017 and is owned by root.
3018
3019 The caller is responsible for deleting the temporary
3020 directory and its contents after use.
3021
3022 See also: L<mkdtemp(3)>");
3023
3024   ("wc_l", (RInt "lines", [Pathname "path"], []), 118, [],
3025    [InitISOFS, Always, TestOutputInt (
3026       [["wc_l"; "/10klines"]], 10000);
3027     (* Test for RHBZ#579608, absolute symbolic links. *)
3028     InitISOFS, Always, TestOutputInt (
3029       [["wc_l"; "/abssymlink"]], 10000)],
3030    "count lines in a file",
3031    "\
3032 This command counts the lines in a file, using the
3033 C<wc -l> external command.");
3034
3035   ("wc_w", (RInt "words", [Pathname "path"], []), 119, [],
3036    [InitISOFS, Always, TestOutputInt (
3037       [["wc_w"; "/10klines"]], 10000)],
3038    "count words in a file",
3039    "\
3040 This command counts the words in a file, using the
3041 C<wc -w> external command.");
3042
3043   ("wc_c", (RInt "chars", [Pathname "path"], []), 120, [],
3044    [InitISOFS, Always, TestOutputInt (
3045       [["wc_c"; "/100kallspaces"]], 102400)],
3046    "count characters in a file",
3047    "\
3048 This command counts the characters in a file, using the
3049 C<wc -c> external command.");
3050
3051   ("head", (RStringList "lines", [Pathname "path"], []), 121, [ProtocolLimitWarning],
3052    [InitISOFS, Always, TestOutputList (
3053       [["head"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz";"3abcdefghijklmnopqrstuvwxyz";"4abcdefghijklmnopqrstuvwxyz";"5abcdefghijklmnopqrstuvwxyz";"6abcdefghijklmnopqrstuvwxyz";"7abcdefghijklmnopqrstuvwxyz";"8abcdefghijklmnopqrstuvwxyz";"9abcdefghijklmnopqrstuvwxyz"]);
3054     (* Test for RHBZ#579608, absolute symbolic links. *)
3055     InitISOFS, Always, TestOutputList (
3056       [["head"; "/abssymlink"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz";"3abcdefghijklmnopqrstuvwxyz";"4abcdefghijklmnopqrstuvwxyz";"5abcdefghijklmnopqrstuvwxyz";"6abcdefghijklmnopqrstuvwxyz";"7abcdefghijklmnopqrstuvwxyz";"8abcdefghijklmnopqrstuvwxyz";"9abcdefghijklmnopqrstuvwxyz"])],
3057    "return first 10 lines of a file",
3058    "\
3059 This command returns up to the first 10 lines of a file as
3060 a list of strings.");
3061
3062   ("head_n", (RStringList "lines", [Int "nrlines"; Pathname "path"], []), 122, [ProtocolLimitWarning],
3063    [InitISOFS, Always, TestOutputList (
3064       [["head_n"; "3"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz"]);
3065     InitISOFS, Always, TestOutputList (
3066       [["head_n"; "-9997"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz"]);
3067     InitISOFS, Always, TestOutputList (
3068       [["head_n"; "0"; "/10klines"]], [])],
3069    "return first N lines of a file",
3070    "\
3071 If the parameter C<nrlines> is a positive number, this returns the first
3072 C<nrlines> lines of the file C<path>.
3073
3074 If the parameter C<nrlines> is a negative number, this returns lines
3075 from the file C<path>, excluding the last C<nrlines> lines.
3076
3077 If the parameter C<nrlines> is zero, this returns an empty list.");
3078
3079   ("tail", (RStringList "lines", [Pathname "path"], []), 123, [ProtocolLimitWarning],
3080    [InitISOFS, Always, TestOutputList (
3081       [["tail"; "/10klines"]], ["9990abcdefghijklmnopqrstuvwxyz";"9991abcdefghijklmnopqrstuvwxyz";"9992abcdefghijklmnopqrstuvwxyz";"9993abcdefghijklmnopqrstuvwxyz";"9994abcdefghijklmnopqrstuvwxyz";"9995abcdefghijklmnopqrstuvwxyz";"9996abcdefghijklmnopqrstuvwxyz";"9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"])],
3082    "return last 10 lines of a file",
3083    "\
3084 This command returns up to the last 10 lines of a file as
3085 a list of strings.");
3086
3087   ("tail_n", (RStringList "lines", [Int "nrlines"; Pathname "path"], []), 124, [ProtocolLimitWarning],
3088    [InitISOFS, Always, TestOutputList (
3089       [["tail_n"; "3"; "/10klines"]], ["9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"]);
3090     InitISOFS, Always, TestOutputList (
3091       [["tail_n"; "-9998"; "/10klines"]], ["9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"]);
3092     InitISOFS, Always, TestOutputList (
3093       [["tail_n"; "0"; "/10klines"]], [])],
3094    "return last N lines of a file",
3095    "\
3096 If the parameter C<nrlines> is a positive number, this returns the last
3097 C<nrlines> lines of the file C<path>.
3098
3099 If the parameter C<nrlines> is a negative number, this returns lines
3100 from the file C<path>, starting with the C<-nrlines>th line.
3101
3102 If the parameter C<nrlines> is zero, this returns an empty list.");
3103
3104   ("df", (RString "output", [], []), 125, [],
3105    [], (* XXX Tricky to test because it depends on the exact format
3106         * of the 'df' command and other imponderables.
3107         *)
3108    "report file system disk space usage",
3109    "\
3110 This command runs the C<df> command to report disk space used.
3111
3112 This command is mostly useful for interactive sessions.  It
3113 is I<not> intended that you try to parse the output string.
3114 Use C<statvfs> from programs.");
3115
3116   ("df_h", (RString "output", [], []), 126, [],
3117    [], (* XXX Tricky to test because it depends on the exact format
3118         * of the 'df' command and other imponderables.
3119         *)
3120    "report file system disk space usage (human readable)",
3121    "\
3122 This command runs the C<df -h> command to report disk space used
3123 in human-readable format.
3124
3125 This command is mostly useful for interactive sessions.  It
3126 is I<not> intended that you try to parse the output string.
3127 Use C<statvfs> from programs.");
3128
3129   ("du", (RInt64 "sizekb", [Pathname "path"], []), 127, [],
3130    [InitISOFS, Always, TestOutputInt (
3131       [["du"; "/directory"]], 2 (* ISO fs blocksize is 2K *))],
3132    "estimate file space usage",
3133    "\
3134 This command runs the C<du -s> command to estimate file space
3135 usage for C<path>.
3136
3137 C<path> can be a file or a directory.  If C<path> is a directory
3138 then the estimate includes the contents of the directory and all
3139 subdirectories (recursively).
3140
3141 The result is the estimated size in I<kilobytes>
3142 (ie. units of 1024 bytes).");
3143
3144   ("initrd_list", (RStringList "filenames", [Pathname "path"], []), 128, [],
3145    [InitISOFS, Always, TestOutputList (
3146       [["initrd_list"; "/initrd"]], ["empty";"known-1";"known-2";"known-3";"known-4"; "known-5"])],
3147    "list files in an initrd",
3148    "\
3149 This command lists out files contained in an initrd.
3150
3151 The files are listed without any initial C</> character.  The
3152 files are listed in the order they appear (not necessarily
3153 alphabetical).  Directory names are listed as separate items.
3154
3155 Old Linux kernels (2.4 and earlier) used a compressed ext2
3156 filesystem as initrd.  We I<only> support the newer initramfs
3157 format (compressed cpio files).");
3158
3159   ("mount_loop", (RErr, [Pathname "file"; Pathname "mountpoint"], []), 129, [],
3160    [],
3161    "mount a file using the loop device",
3162    "\
3163 This command lets you mount C<file> (a filesystem image
3164 in a file) on a mount point.  It is entirely equivalent to
3165 the command C<mount -o loop file mountpoint>.");
3166
3167   ("mkswap", (RErr, [Device "device"], []), 130, [],
3168    [InitEmpty, Always, TestRun (
3169       [["part_disk"; "/dev/sda"; "mbr"];
3170        ["mkswap"; "/dev/sda1"]])],
3171    "create a swap partition",
3172    "\
3173 Create a swap partition on C<device>.");
3174
3175   ("mkswap_L", (RErr, [String "label"; Device "device"], []), 131, [],
3176    [InitEmpty, Always, TestRun (
3177       [["part_disk"; "/dev/sda"; "mbr"];
3178        ["mkswap_L"; "hello"; "/dev/sda1"]])],
3179    "create a swap partition with a label",
3180    "\
3181 Create a swap partition on C<device> with label C<label>.
3182
3183 Note that you cannot attach a swap label to a block device
3184 (eg. C</dev/sda>), just to a partition.  This appears to be
3185 a limitation of the kernel or swap tools.");
3186
3187   ("mkswap_U", (RErr, [String "uuid"; Device "device"], []), 132, [Optional "linuxfsuuid"],
3188    (let uuid = uuidgen () in
3189     [InitEmpty, Always, TestRun (
3190        [["part_disk"; "/dev/sda"; "mbr"];
3191         ["mkswap_U"; uuid; "/dev/sda1"]])]),
3192    "create a swap partition with an explicit UUID",
3193    "\
3194 Create a swap partition on C<device> with UUID C<uuid>.");
3195
3196   ("mknod", (RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"], []), 133, [Optional "mknod"],
3197    [InitBasicFS, Always, TestOutputStruct (
3198       [["mknod"; "0o10777"; "0"; "0"; "/node"];
3199        (* NB: default umask 022 means 0777 -> 0755 in these tests *)
3200        ["stat"; "/node"]], [CompareWithInt ("mode", 0o10755)]);
3201     InitBasicFS, Always, TestOutputStruct (
3202       [["mknod"; "0o60777"; "66"; "99"; "/node"];
3203        ["stat"; "/node"]], [CompareWithInt ("mode", 0o60755)])],
3204    "make block, character or FIFO devices",
3205    "\
3206 This call creates block or character special devices, or
3207 named pipes (FIFOs).
3208
3209 The C<mode> parameter should be the mode, using the standard
3210 constants.  C<devmajor> and C<devminor> are the
3211 device major and minor numbers, only used when creating block
3212 and character special devices.
3213
3214 Note that, just like L<mknod(2)>, the mode must be bitwise
3215 OR'd with S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call
3216 just creates a regular file).  These constants are
3217 available in the standard Linux header files, or you can use
3218 C<guestfs_mknod_b>, C<guestfs_mknod_c> or C<guestfs_mkfifo>
3219 which are wrappers around this command which bitwise OR
3220 in the appropriate constant for you.
3221
3222 The mode actually set is affected by the umask.");
3223
3224   ("mkfifo", (RErr, [Int "mode"; Pathname "path"], []), 134, [Optional "mknod"],
3225    [InitBasicFS, Always, TestOutputStruct (
3226       [["mkfifo"; "0o777"; "/node"];
3227        ["stat"; "/node"]], [CompareWithInt ("mode", 0o10755)])],
3228    "make FIFO (named pipe)",
3229    "\
3230 This call creates a FIFO (named pipe) called C<path> with
3231 mode C<mode>.  It is just a convenient wrapper around
3232 C<guestfs_mknod>.
3233
3234 The mode actually set is affected by the umask.");
3235
3236   ("mknod_b", (RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"], []), 135, [Optional "mknod"],
3237    [InitBasicFS, Always, TestOutputStruct (
3238       [["mknod_b"; "0o777"; "99"; "66"; "/node"];
3239        ["stat"; "/node"]], [CompareWithInt ("mode", 0o60755)])],
3240    "make block device node",
3241    "\
3242 This call creates a block device node called C<path> with
3243 mode C<mode> and device major/minor C<devmajor> and C<devminor>.
3244 It is just a convenient wrapper around C<guestfs_mknod>.
3245
3246 The mode actually set is affected by the umask.");
3247
3248   ("mknod_c", (RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"], []), 136, [Optional "mknod"],
3249    [InitBasicFS, Always, TestOutputStruct (
3250       [["mknod_c"; "0o777"; "99"; "66"; "/node"];
3251        ["stat"; "/node"]], [CompareWithInt ("mode", 0o20755)])],
3252    "make char device node",
3253    "\
3254 This call creates a char device node called C<path> with
3255 mode C<mode> and device major/minor C<devmajor> and C<devminor>.
3256 It is just a convenient wrapper around C<guestfs_mknod>.
3257
3258 The mode actually set is affected by the umask.");
3259
3260   ("umask", (RInt "oldmask", [Int "mask"], []), 137, [FishOutput FishOutputOctal],
3261    [InitEmpty, Always, TestOutputInt (
3262       [["umask"; "0o22"]], 0o22)],
3263    "set file mode creation mask (umask)",
3264    "\
3265 This function sets the mask used for creating new files and
3266 device nodes to C<mask & 0777>.
3267
3268 Typical umask values would be C<022> which creates new files
3269 with permissions like \"-rw-r--r--\" or \"-rwxr-xr-x\", and
3270 C<002> which creates new files with permissions like
3271 \"-rw-rw-r--\" or \"-rwxrwxr-x\".
3272
3273 The default umask is C<022>.  This is important because it
3274 means that directories and device nodes will be created with
3275 C<0644> or C<0755> mode even if you specify C<0777>.
3276
3277 See also C<guestfs_get_umask>,
3278 L<umask(2)>, C<guestfs_mknod>, C<guestfs_mkdir>.
3279
3280 This call returns the previous umask.");
3281
3282   ("readdir", (RStructList ("entries", "dirent"), [Pathname "dir"], []), 138, [],
3283    [],
3284    "read directories entries",
3285    "\
3286 This returns the list of directory entries in directory C<dir>.
3287
3288 All entries in the directory are returned, including C<.> and
3289 C<..>.  The entries are I<not> sorted, but returned in the same
3290 order as the underlying filesystem.
3291
3292 Also this call returns basic file type information about each
3293 file.  The C<ftyp> field will contain one of the following characters:
3294
3295 =over 4
3296
3297 =item 'b'
3298
3299 Block special
3300
3301 =item 'c'
3302
3303 Char special
3304
3305 =item 'd'
3306
3307 Directory
3308
3309 =item 'f'
3310
3311 FIFO (named pipe)
3312
3313 =item 'l'
3314
3315 Symbolic link
3316
3317 =item 'r'
3318
3319 Regular file
3320
3321 =item 's'
3322
3323 Socket
3324
3325 =item 'u'
3326
3327 Unknown file type
3328
3329 =item '?'
3330
3331 The L<readdir(3)> call returned a C<d_type> field with an
3332 unexpected value
3333
3334 =back
3335
3336 This function is primarily intended for use by programs.  To
3337 get a simple list of names, use C<guestfs_ls>.  To get a printable
3338 directory for human consumption, use C<guestfs_ll>.");
3339
3340   ("sfdiskM", (RErr, [Device "device"; StringList "lines"], []), 139, [DangerWillRobinson],
3341    [],
3342    "create partitions on a block device",
3343    "\
3344 This is a simplified interface to the C<guestfs_sfdisk>
3345 command, where partition sizes are specified in megabytes
3346 only (rounded to the nearest cylinder) and you don't need
3347 to specify the cyls, heads and sectors parameters which
3348 were rarely if ever used anyway.
3349
3350 See also: C<guestfs_sfdisk>, the L<sfdisk(8)> manpage
3351 and C<guestfs_part_disk>");
3352
3353   ("zfile", (RString "description", [String "meth"; Pathname "path"], []), 140, [DeprecatedBy "file"],
3354    [],
3355    "determine file type inside a compressed file",
3356    "\
3357 This command runs C<file> after first decompressing C<path>
3358 using C<method>.
3359
3360 C<method> must be one of C<gzip>, C<compress> or C<bzip2>.
3361
3362 Since 1.0.63, use C<guestfs_file> instead which can now
3363 process compressed files.");
3364
3365   ("getxattrs", (RStructList ("xattrs", "xattr"), [Pathname "path"], []), 141, [Optional "linuxxattrs"],
3366    [],
3367    "list extended attributes of a file or directory",
3368    "\
3369 This call lists the extended attributes of the file or directory
3370 C<path>.
3371
3372 At the system call level, this is a combination of the
3373 L<listxattr(2)> and L<getxattr(2)> calls.
3374
3375 See also: C<guestfs_lgetxattrs>, L<attr(5)>.");
3376
3377   ("lgetxattrs", (RStructList ("xattrs", "xattr"), [Pathname "path"], []), 142, [Optional "linuxxattrs"],
3378    [],
3379    "list extended attributes of a file or directory",
3380    "\
3381 This is the same as C<guestfs_getxattrs>, but if C<path>
3382 is a symbolic link, then it returns the extended attributes
3383 of the link itself.");
3384
3385   ("setxattr", (RErr, [String "xattr";
3386                        String "val"; Int "vallen"; (* will be BufferIn *)
3387                        Pathname "path"], []), 143, [Optional "linuxxattrs"],
3388    [],
3389    "set extended attribute of a file or directory",
3390    "\
3391 This call sets the extended attribute named C<xattr>
3392 of the file C<path> to the value C<val> (of length C<vallen>).
3393 The value is arbitrary 8 bit data.
3394
3395 See also: C<guestfs_lsetxattr>, L<attr(5)>.");
3396
3397   ("lsetxattr", (RErr, [String "xattr";
3398                         String "val"; Int "vallen"; (* will be BufferIn *)
3399                         Pathname "path"], []), 144, [Optional "linuxxattrs"],
3400    [],
3401    "set extended attribute of a file or directory",
3402    "\
3403 This is the same as C<guestfs_setxattr>, but if C<path>
3404 is a symbolic link, then it sets an extended attribute
3405 of the link itself.");
3406
3407   ("removexattr", (RErr, [String "xattr"; Pathname "path"], []), 145, [Optional "linuxxattrs"],
3408    [],
3409    "remove extended attribute of a file or directory",
3410    "\
3411 This call removes the extended attribute named C<xattr>
3412 of the file C<path>.
3413
3414 See also: C<guestfs_lremovexattr>, L<attr(5)>.");
3415
3416   ("lremovexattr", (RErr, [String "xattr"; Pathname "path"], []), 146, [Optional "linuxxattrs"],
3417    [],
3418    "remove extended attribute of a file or directory",
3419    "\
3420 This is the same as C<guestfs_removexattr>, but if C<path>
3421 is a symbolic link, then it removes an extended attribute
3422 of the link itself.");
3423
3424   ("mountpoints", (RHashtable "mps", [], []), 147, [],
3425    [],
3426    "show mountpoints",
3427    "\
3428 This call is similar to C<guestfs_mounts>.  That call returns
3429 a list of devices.  This one returns a hash table (map) of
3430 device name to directory where the device is mounted.");
3431
3432   ("mkmountpoint", (RErr, [String "exemptpath"], []), 148, [],
3433    (* This is a special case: while you would expect a parameter
3434     * of type "Pathname", that doesn't work, because it implies
3435     * NEED_ROOT in the generated calling code in stubs.c, and
3436     * this function cannot use NEED_ROOT.
3437     *)
3438    [],
3439    "create a mountpoint",
3440    "\
3441 C<guestfs_mkmountpoint> and C<guestfs_rmmountpoint> are
3442 specialized calls that can be used to create extra mountpoints
3443 before mounting the first filesystem.
3444
3445 These calls are I<only> necessary in some very limited circumstances,
3446 mainly the case where you want to mount a mix of unrelated and/or
3447 read-only filesystems together.
3448
3449 For example, live CDs often contain a \"Russian doll\" nest of
3450 filesystems, an ISO outer layer, with a squashfs image inside, with
3451 an ext2/3 image inside that.  You can unpack this as follows
3452 in guestfish:
3453
3454  add-ro Fedora-11-i686-Live.iso
3455  run
3456  mkmountpoint /cd
3457  mkmountpoint /sqsh
3458  mkmountpoint /ext3fs
3459  mount /dev/sda /cd
3460  mount-loop /cd/LiveOS/squashfs.img /sqsh
3461  mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
3462
3463 The inner filesystem is now unpacked under the /ext3fs mountpoint.
3464
3465 C<guestfs_mkmountpoint> is not compatible with C<guestfs_umount_all>.
3466 You may get unexpected errors if you try to mix these calls.  It is
3467 safest to manually unmount filesystems and remove mountpoints after use.
3468
3469 C<guestfs_umount_all> unmounts filesystems by sorting the paths
3470 longest first, so for this to work for manual mountpoints, you
3471 must ensure that the innermost mountpoints have the longest
3472 pathnames, as in the example code above.
3473
3474 For more details see L<https://bugzilla.redhat.com/show_bug.cgi?id=599503>
3475
3476 Autosync [see C<guestfs_set_autosync>, this is set by default on
3477 handles] means that C<guestfs_umount_all> is called when the handle
3478 is closed which can also trigger these issues.");
3479
3480   ("rmmountpoint", (RErr, [String "exemptpath"], []), 149, [],
3481    [],
3482    "remove a mountpoint",
3483    "\
3484 This calls removes a mountpoint that was previously created
3485 with C<guestfs_mkmountpoint>.  See C<guestfs_mkmountpoint>
3486 for full details.");
3487
3488   ("read_file", (RBufferOut "content", [Pathname "path"], []), 150, [ProtocolLimitWarning],
3489    [InitISOFS, Always, TestOutputBuffer (
3490       [["read_file"; "/known-4"]], "abc\ndef\nghi");
3491     (* Test various near large, large and too large files (RHBZ#589039). *)
3492     InitBasicFS, Always, TestLastFail (
3493       [["touch"; "/a"];
3494        ["truncate_size"; "/a"; "4194303"]; (* GUESTFS_MESSAGE_MAX - 1 *)
3495        ["read_file"; "/a"]]);
3496     InitBasicFS, Always, TestLastFail (
3497       [["touch"; "/a"];
3498        ["truncate_size"; "/a"; "4194304"]; (* GUESTFS_MESSAGE_MAX *)
3499        ["read_file"; "/a"]]);
3500     InitBasicFS, Always, TestLastFail (
3501       [["touch"; "/a"];
3502        ["truncate_size"; "/a"; "41943040"]; (* GUESTFS_MESSAGE_MAX * 10 *)
3503        ["read_file"; "/a"]])],
3504    "read a file",
3505    "\
3506 This calls returns the contents of the file C<path> as a
3507 buffer.
3508
3509 Unlike C<guestfs_cat>, this function can correctly
3510 handle files that contain embedded ASCII NUL characters.
3511 However unlike C<guestfs_download>, this function is limited
3512 in the total size of file that can be handled.");
3513
3514   ("grep", (RStringList "lines", [String "regex"; Pathname "path"], []), 151, [ProtocolLimitWarning],
3515    [InitISOFS, Always, TestOutputList (
3516       [["grep"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"]);
3517     InitISOFS, Always, TestOutputList (
3518       [["grep"; "nomatch"; "/test-grep.txt"]], []);
3519     (* Test for RHBZ#579608, absolute symbolic links. *)
3520     InitISOFS, Always, TestOutputList (
3521       [["grep"; "nomatch"; "/abssymlink"]], [])],
3522    "return lines matching a pattern",
3523    "\
3524 This calls the external C<grep> program and returns the
3525 matching lines.");
3526
3527   ("egrep", (RStringList "lines", [String "regex"; Pathname "path"], []), 152, [ProtocolLimitWarning],
3528    [InitISOFS, Always, TestOutputList (
3529       [["egrep"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"])],
3530    "return lines matching a pattern",
3531    "\
3532 This calls the external C<egrep> program and returns the
3533 matching lines.");
3534
3535   ("fgrep", (RStringList "lines", [String "pattern"; Pathname "path"], []), 153, [ProtocolLimitWarning],
3536    [InitISOFS, Always, TestOutputList (
3537       [["fgrep"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"])],
3538    "return lines matching a pattern",
3539    "\
3540 This calls the external C<fgrep> program and returns the
3541 matching lines.");
3542
3543   ("grepi", (RStringList "lines", [String "regex"; Pathname "path"], []), 154, [ProtocolLimitWarning],
3544    [InitISOFS, Always, TestOutputList (
3545       [["grepi"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"; "ABC"])],
3546    "return lines matching a pattern",
3547    "\
3548 This calls the external C<grep -i> program and returns the
3549 matching lines.");
3550
3551   ("egrepi", (RStringList "lines", [String "regex"; Pathname "path"], []), 155, [ProtocolLimitWarning],
3552    [InitISOFS, Always, TestOutputList (
3553       [["egrepi"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"; "ABC"])],
3554    "return lines matching a pattern",
3555    "\
3556 This calls the external C<egrep -i> program and returns the
3557 matching lines.");
3558
3559   ("fgrepi", (RStringList "lines", [String "pattern"; Pathname "path"], []), 156, [ProtocolLimitWarning],
3560    [InitISOFS, Always, TestOutputList (
3561       [["fgrepi"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"; "ABC"])],
3562    "return lines matching a pattern",
3563    "\
3564 This calls the external C<fgrep -i> program and returns the
3565 matching lines.");
3566
3567   ("zgrep", (RStringList "lines", [String "regex"; Pathname "path"], []), 157, [ProtocolLimitWarning],
3568    [InitISOFS, Always, TestOutputList (
3569       [["zgrep"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"])],
3570    "return lines matching a pattern",
3571    "\
3572 This calls the external C<zgrep> program and returns the
3573 matching lines.");
3574
3575   ("zegrep", (RStringList "lines", [String "regex"; Pathname "path"], []), 158, [ProtocolLimitWarning],
3576    [InitISOFS, Always, TestOutputList (
3577       [["zegrep"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"])],
3578    "return lines matching a pattern",
3579    "\
3580 This calls the external C<zegrep> program and returns the
3581 matching lines.");
3582
3583   ("zfgrep", (RStringList "lines", [String "pattern"; Pathna