New API: add-domain
[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   ("inspect_get_roots", (RStringList "roots", [], []), -1, [],
1042    [],
1043    "return list of operating systems found by last inspection",
1044    "\
1045 This function is a convenient way to get the list of root
1046 devices, as returned from a previous call to C<guestfs_inspect_os>,
1047 but without redoing the whole inspection process.
1048
1049 This returns an empty list if either no root devices were
1050 found or the caller has not called C<guestfs_inspect_os>.
1051
1052 Please read L<guestfs(3)/INSPECTION> for more details.");
1053
1054   ("debug_cmdline", (RStringList "cmdline", [], []), -1, [NotInDocs],
1055    [],
1056    "debug the QEMU command line (internal use only)",
1057    "\
1058 This returns the internal QEMU command line.  'debug' commands are
1059 not part of the formal API and can be removed or changed at any time.");
1060
1061   ("add_domain", (RInt "nrdisks", [String "dom"], [String "libvirturi"; Bool "readonly"; String "iface"]), -1, [FishAlias "domain"],
1062    [],
1063    "add the disk(s) from a named libvirt domain",
1064    "\
1065 This function adds the disk(s) attached to the named libvirt
1066 domain C<dom>.  It works by connecting to libvirt, requesting
1067 the domain and domain XML from libvirt, parsing it for disks,
1068 and calling C<guestfs_add_drive_opts> on each one.
1069
1070 The number of disks added is returned.  This operation is atomic:
1071 if an error is returned, then no disks are added.
1072
1073 This function does some minimal checks to make sure the libvirt
1074 domain is not running (unless C<readonly> is true).  In a future
1075 version we will try to acquire the libvirt lock on each disk.
1076
1077 Disks must be accessible locally.  This often means that adding disks
1078 from a remote libvirt connection (see L<http://libvirt.org/remote.html>)
1079 will fail unless those disks are accessible via the same device path
1080 locally too.
1081
1082 The optional C<libvirturi> parameter sets the libvirt URI
1083 (see L<http://libvirt.org/uri.html>).  If this is not set then
1084 we connect to the default libvirt URI (or one set through an
1085 environment variable, see the libvirt documentation for full
1086 details).  If you are using the C API directly then it is more
1087 flexible to create the libvirt connection object yourself, get
1088 the domain object, and call C<guestfs_add_libvirt_dom>.
1089
1090 The other optional parameters are passed directly through to
1091 C<guestfs_add_drive_opts>.");
1092
1093 (*
1094 This interface is not quite baked yet. -- RWMJ 2010-11-11
1095   ("add_libvirt_dom", (RInt "nrdisks", [Pointer ("virDomainPtr", "dom")], [Bool "readonly"; String "iface"]), -1, [NotInFish],
1096    [],
1097    "add the disk(s) from a libvirt domain",
1098    "\
1099 This function adds the disk(s) attached to the libvirt domain C<dom>.
1100 It works by requesting the domain XML from libvirt, parsing it for
1101 disks, and calling C<guestfs_add_drive_opts> on each one.
1102
1103 In the C API we declare C<void *dom>, but really it has type
1104 C<virDomainPtr dom>.  This is so we don't need E<lt>libvirt.hE<gt>.
1105
1106 The number of disks added is returned.  This operation is atomic:
1107 if an error is returned, then no disks are added.
1108
1109 This function does some minimal checks to make sure the libvirt
1110 domain is not running (unless C<readonly> is true).  In a future
1111 version we will try to acquire the libvirt lock on each disk.
1112
1113 Disks must be accessible locally.  This often means that adding disks
1114 from a remote libvirt connection (see L<http://libvirt.org/remote.html>)
1115 will fail unless those disks are accessible via the same device path
1116 locally too.
1117
1118 The optional parameters are passed directly through to
1119 C<guestfs_add_drive_opts>.");
1120 *)
1121
1122 ]
1123
1124 (* daemon_functions are any functions which cause some action
1125  * to take place in the daemon.
1126  *)
1127
1128 let daemon_functions = [
1129   ("mount", (RErr, [Device "device"; String "mountpoint"], []), 1, [],
1130    [InitEmpty, Always, TestOutput (
1131       [["part_disk"; "/dev/sda"; "mbr"];
1132        ["mkfs"; "ext2"; "/dev/sda1"];
1133        ["mount"; "/dev/sda1"; "/"];
1134        ["write"; "/new"; "new file contents"];
1135        ["cat"; "/new"]], "new file contents")],
1136    "mount a guest disk at a position in the filesystem",
1137    "\
1138 Mount a guest disk at a position in the filesystem.  Block devices
1139 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
1140 the guest.  If those block devices contain partitions, they will have
1141 the usual names (eg. C</dev/sda1>).  Also LVM C</dev/VG/LV>-style
1142 names can be used.
1143
1144 The rules are the same as for L<mount(2)>:  A filesystem must
1145 first be mounted on C</> before others can be mounted.  Other
1146 filesystems can only be mounted on directories which already
1147 exist.
1148
1149 The mounted filesystem is writable, if we have sufficient permissions
1150 on the underlying device.
1151
1152 B<Important note:>
1153 When you use this call, the filesystem options C<sync> and C<noatime>
1154 are set implicitly.  This was originally done because we thought it
1155 would improve reliability, but it turns out that I<-o sync> has a
1156 very large negative performance impact and negligible effect on
1157 reliability.  Therefore we recommend that you avoid using
1158 C<guestfs_mount> in any code that needs performance, and instead
1159 use C<guestfs_mount_options> (use an empty string for the first
1160 parameter if you don't want any options).");
1161
1162   ("sync", (RErr, [], []), 2, [],
1163    [ InitEmpty, Always, TestRun [["sync"]]],
1164    "sync disks, writes are flushed through to the disk image",
1165    "\
1166 This syncs the disk, so that any writes are flushed through to the
1167 underlying disk image.
1168
1169 You should always call this if you have modified a disk image, before
1170 closing the handle.");
1171
1172   ("touch", (RErr, [Pathname "path"], []), 3, [],
1173    [InitBasicFS, Always, TestOutputTrue (
1174       [["touch"; "/new"];
1175        ["exists"; "/new"]])],
1176    "update file timestamps or create a new file",
1177    "\
1178 Touch acts like the L<touch(1)> command.  It can be used to
1179 update the timestamps on a file, or, if the file does not exist,
1180 to create a new zero-length file.
1181
1182 This command only works on regular files, and will fail on other
1183 file types such as directories, symbolic links, block special etc.");
1184
1185   ("cat", (RString "content", [Pathname "path"], []), 4, [ProtocolLimitWarning],
1186    [InitISOFS, Always, TestOutput (
1187       [["cat"; "/known-2"]], "abcdef\n")],
1188    "list the contents of a file",
1189    "\
1190 Return the contents of the file named C<path>.
1191
1192 Note that this function cannot correctly handle binary files
1193 (specifically, files containing C<\\0> character which is treated
1194 as end of string).  For those you need to use the C<guestfs_read_file>
1195 or C<guestfs_download> functions which have a more complex interface.");
1196
1197   ("ll", (RString "listing", [Pathname "directory"], []), 5, [],
1198    [], (* XXX Tricky to test because it depends on the exact format
1199         * of the 'ls -l' command, which changes between F10 and F11.
1200         *)
1201    "list the files in a directory (long format)",
1202    "\
1203 List the files in C<directory> (relative to the root directory,
1204 there is no cwd) in the format of 'ls -la'.
1205
1206 This command is mostly useful for interactive sessions.  It
1207 is I<not> intended that you try to parse the output string.");
1208
1209   ("ls", (RStringList "listing", [Pathname "directory"], []), 6, [],
1210    [InitBasicFS, Always, TestOutputList (
1211       [["touch"; "/new"];
1212        ["touch"; "/newer"];
1213        ["touch"; "/newest"];
1214        ["ls"; "/"]], ["lost+found"; "new"; "newer"; "newest"])],
1215    "list the files in a directory",
1216    "\
1217 List the files in C<directory> (relative to the root directory,
1218 there is no cwd).  The '.' and '..' entries are not returned, but
1219 hidden files are shown.
1220
1221 This command is mostly useful for interactive sessions.  Programs
1222 should probably use C<guestfs_readdir> instead.");
1223
1224   ("list_devices", (RStringList "devices", [], []), 7, [],
1225    [InitEmpty, Always, TestOutputListOfDevices (
1226       [["list_devices"]], ["/dev/sda"; "/dev/sdb"; "/dev/sdc"; "/dev/sdd"])],
1227    "list the block devices",
1228    "\
1229 List all the block devices.
1230
1231 The full block device names are returned, eg. C</dev/sda>.
1232
1233 See also C<guestfs_list_filesystems>.");
1234
1235   ("list_partitions", (RStringList "partitions", [], []), 8, [],
1236    [InitBasicFS, Always, TestOutputListOfDevices (
1237       [["list_partitions"]], ["/dev/sda1"]);
1238     InitEmpty, Always, TestOutputListOfDevices (
1239       [["part_init"; "/dev/sda"; "mbr"];
1240        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1241        ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1242        ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1243        ["list_partitions"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
1244    "list the partitions",
1245    "\
1246 List all the partitions detected on all block devices.
1247
1248 The full partition device names are returned, eg. C</dev/sda1>
1249
1250 This does not return logical volumes.  For that you will need to
1251 call C<guestfs_lvs>.
1252
1253 See also C<guestfs_list_filesystems>.");
1254
1255   ("pvs", (RStringList "physvols", [], []), 9, [Optional "lvm2"],
1256    [InitBasicFSonLVM, Always, TestOutputListOfDevices (
1257       [["pvs"]], ["/dev/sda1"]);
1258     InitEmpty, Always, TestOutputListOfDevices (
1259       [["part_init"; "/dev/sda"; "mbr"];
1260        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1261        ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1262        ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1263        ["pvcreate"; "/dev/sda1"];
1264        ["pvcreate"; "/dev/sda2"];
1265        ["pvcreate"; "/dev/sda3"];
1266        ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
1267    "list the LVM physical volumes (PVs)",
1268    "\
1269 List all the physical volumes detected.  This is the equivalent
1270 of the L<pvs(8)> command.
1271
1272 This returns a list of just the device names that contain
1273 PVs (eg. C</dev/sda2>).
1274
1275 See also C<guestfs_pvs_full>.");
1276
1277   ("vgs", (RStringList "volgroups", [], []), 10, [Optional "lvm2"],
1278    [InitBasicFSonLVM, Always, TestOutputList (
1279       [["vgs"]], ["VG"]);
1280     InitEmpty, Always, TestOutputList (
1281       [["part_init"; "/dev/sda"; "mbr"];
1282        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1283        ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1284        ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1285        ["pvcreate"; "/dev/sda1"];
1286        ["pvcreate"; "/dev/sda2"];
1287        ["pvcreate"; "/dev/sda3"];
1288        ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1289        ["vgcreate"; "VG2"; "/dev/sda3"];
1290        ["vgs"]], ["VG1"; "VG2"])],
1291    "list the LVM volume groups (VGs)",
1292    "\
1293 List all the volumes groups detected.  This is the equivalent
1294 of the L<vgs(8)> command.
1295
1296 This returns a list of just the volume group names that were
1297 detected (eg. C<VolGroup00>).
1298
1299 See also C<guestfs_vgs_full>.");
1300
1301   ("lvs", (RStringList "logvols", [], []), 11, [Optional "lvm2"],
1302    [InitBasicFSonLVM, Always, TestOutputList (
1303       [["lvs"]], ["/dev/VG/LV"]);
1304     InitEmpty, Always, TestOutputList (
1305       [["part_init"; "/dev/sda"; "mbr"];
1306        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1307        ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1308        ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1309        ["pvcreate"; "/dev/sda1"];
1310        ["pvcreate"; "/dev/sda2"];
1311        ["pvcreate"; "/dev/sda3"];
1312        ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1313        ["vgcreate"; "VG2"; "/dev/sda3"];
1314        ["lvcreate"; "LV1"; "VG1"; "50"];
1315        ["lvcreate"; "LV2"; "VG1"; "50"];
1316        ["lvcreate"; "LV3"; "VG2"; "50"];
1317        ["lvs"]], ["/dev/VG1/LV1"; "/dev/VG1/LV2"; "/dev/VG2/LV3"])],
1318    "list the LVM logical volumes (LVs)",
1319    "\
1320 List all the logical volumes detected.  This is the equivalent
1321 of the L<lvs(8)> command.
1322
1323 This returns a list of the logical volume device names
1324 (eg. C</dev/VolGroup00/LogVol00>).
1325
1326 See also C<guestfs_lvs_full>, C<guestfs_list_filesystems>.");
1327
1328   ("pvs_full", (RStructList ("physvols", "lvm_pv"), [], []), 12, [Optional "lvm2"],
1329    [], (* XXX how to test? *)
1330    "list the LVM physical volumes (PVs)",
1331    "\
1332 List all the physical volumes detected.  This is the equivalent
1333 of the L<pvs(8)> command.  The \"full\" version includes all fields.");
1334
1335   ("vgs_full", (RStructList ("volgroups", "lvm_vg"), [], []), 13, [Optional "lvm2"],
1336    [], (* XXX how to test? *)
1337    "list the LVM volume groups (VGs)",
1338    "\
1339 List all the volumes groups detected.  This is the equivalent
1340 of the L<vgs(8)> command.  The \"full\" version includes all fields.");
1341
1342   ("lvs_full", (RStructList ("logvols", "lvm_lv"), [], []), 14, [Optional "lvm2"],
1343    [], (* XXX how to test? *)
1344    "list the LVM logical volumes (LVs)",
1345    "\
1346 List all the logical volumes detected.  This is the equivalent
1347 of the L<lvs(8)> command.  The \"full\" version includes all fields.");
1348
1349   ("read_lines", (RStringList "lines", [Pathname "path"], []), 15, [],
1350    [InitISOFS, Always, TestOutputList (
1351       [["read_lines"; "/known-4"]], ["abc"; "def"; "ghi"]);
1352     InitISOFS, Always, TestOutputList (
1353       [["read_lines"; "/empty"]], [])],
1354    "read file as lines",
1355    "\
1356 Return the contents of the file named C<path>.
1357
1358 The file contents are returned as a list of lines.  Trailing
1359 C<LF> and C<CRLF> character sequences are I<not> returned.
1360
1361 Note that this function cannot correctly handle binary files
1362 (specifically, files containing C<\\0> character which is treated
1363 as end of line).  For those you need to use the C<guestfs_read_file>
1364 function which has a more complex interface.");
1365
1366   ("aug_init", (RErr, [Pathname "root"; Int "flags"], []), 16, [Optional "augeas"],
1367    [], (* XXX Augeas code needs tests. *)
1368    "create a new Augeas handle",
1369    "\
1370 Create a new Augeas handle for editing configuration files.
1371 If there was any previous Augeas handle associated with this
1372 guestfs session, then it is closed.
1373
1374 You must call this before using any other C<guestfs_aug_*>
1375 commands.
1376
1377 C<root> is the filesystem root.  C<root> must not be NULL,
1378 use C</> instead.
1379
1380 The flags are the same as the flags defined in
1381 E<lt>augeas.hE<gt>, the logical I<or> of the following
1382 integers:
1383
1384 =over 4
1385
1386 =item C<AUG_SAVE_BACKUP> = 1
1387
1388 Keep the original file with a C<.augsave> extension.
1389
1390 =item C<AUG_SAVE_NEWFILE> = 2
1391
1392 Save changes into a file with extension C<.augnew>, and
1393 do not overwrite original.  Overrides C<AUG_SAVE_BACKUP>.
1394
1395 =item C<AUG_TYPE_CHECK> = 4
1396
1397 Typecheck lenses (can be expensive).
1398
1399 =item C<AUG_NO_STDINC> = 8
1400
1401 Do not use standard load path for modules.
1402
1403 =item C<AUG_SAVE_NOOP> = 16
1404
1405 Make save a no-op, just record what would have been changed.
1406
1407 =item C<AUG_NO_LOAD> = 32
1408
1409 Do not load the tree in C<guestfs_aug_init>.
1410
1411 =back
1412
1413 To close the handle, you can call C<guestfs_aug_close>.
1414
1415 To find out more about Augeas, see L<http://augeas.net/>.");
1416
1417   ("aug_close", (RErr, [], []), 26, [Optional "augeas"],
1418    [], (* XXX Augeas code needs tests. *)
1419    "close the current Augeas handle",
1420    "\
1421 Close the current Augeas handle and free up any resources
1422 used by it.  After calling this, you have to call
1423 C<guestfs_aug_init> again before you can use any other
1424 Augeas functions.");
1425
1426   ("aug_defvar", (RInt "nrnodes", [String "name"; OptString "expr"], []), 17, [Optional "augeas"],
1427    [], (* XXX Augeas code needs tests. *)
1428    "define an Augeas variable",
1429    "\
1430 Defines an Augeas variable C<name> whose value is the result
1431 of evaluating C<expr>.  If C<expr> is NULL, then C<name> is
1432 undefined.
1433
1434 On success this returns the number of nodes in C<expr>, or
1435 C<0> if C<expr> evaluates to something which is not a nodeset.");
1436
1437   ("aug_defnode", (RStruct ("nrnodescreated", "int_bool"), [String "name"; String "expr"; String "val"], []), 18, [Optional "augeas"],
1438    [], (* XXX Augeas code needs tests. *)
1439    "define an Augeas node",
1440    "\
1441 Defines a variable C<name> whose value is the result of
1442 evaluating C<expr>.
1443
1444 If C<expr> evaluates to an empty nodeset, a node is created,
1445 equivalent to calling C<guestfs_aug_set> C<expr>, C<value>.
1446 C<name> will be the nodeset containing that single node.
1447
1448 On success this returns a pair containing the
1449 number of nodes in the nodeset, and a boolean flag
1450 if a node was created.");
1451
1452   ("aug_get", (RString "val", [String "augpath"], []), 19, [Optional "augeas"],
1453    [], (* XXX Augeas code needs tests. *)
1454    "look up the value of an Augeas path",
1455    "\
1456 Look up the value associated with C<path>.  If C<path>
1457 matches exactly one node, the C<value> is returned.");
1458
1459   ("aug_set", (RErr, [String "augpath"; String "val"], []), 20, [Optional "augeas"],
1460    [], (* XXX Augeas code needs tests. *)
1461    "set Augeas path to value",
1462    "\
1463 Set the value associated with C<path> to C<val>.
1464
1465 In the Augeas API, it is possible to clear a node by setting
1466 the value to NULL.  Due to an oversight in the libguestfs API
1467 you cannot do that with this call.  Instead you must use the
1468 C<guestfs_aug_clear> call.");
1469
1470   ("aug_insert", (RErr, [String "augpath"; String "label"; Bool "before"], []), 21, [Optional "augeas"],
1471    [], (* XXX Augeas code needs tests. *)
1472    "insert a sibling Augeas node",
1473    "\
1474 Create a new sibling C<label> for C<path>, inserting it into
1475 the tree before or after C<path> (depending on the boolean
1476 flag C<before>).
1477
1478 C<path> must match exactly one existing node in the tree, and
1479 C<label> must be a label, ie. not contain C</>, C<*> or end
1480 with a bracketed index C<[N]>.");
1481
1482   ("aug_rm", (RInt "nrnodes", [String "augpath"], []), 22, [Optional "augeas"],
1483    [], (* XXX Augeas code needs tests. *)
1484    "remove an Augeas path",
1485    "\
1486 Remove C<path> and all of its children.
1487
1488 On success this returns the number of entries which were removed.");
1489
1490   ("aug_mv", (RErr, [String "src"; String "dest"], []), 23, [Optional "augeas"],
1491    [], (* XXX Augeas code needs tests. *)
1492    "move Augeas node",
1493    "\
1494 Move the node C<src> to C<dest>.  C<src> must match exactly
1495 one node.  C<dest> is overwritten if it exists.");
1496
1497   ("aug_match", (RStringList "matches", [String "augpath"], []), 24, [Optional "augeas"],
1498    [], (* XXX Augeas code needs tests. *)
1499    "return Augeas nodes which match augpath",
1500    "\
1501 Returns a list of paths which match the path expression C<path>.
1502 The returned paths are sufficiently qualified so that they match
1503 exactly one node in the current tree.");
1504
1505   ("aug_save", (RErr, [], []), 25, [Optional "augeas"],
1506    [], (* XXX Augeas code needs tests. *)
1507    "write all pending Augeas changes to disk",
1508    "\
1509 This writes all pending changes to disk.
1510
1511 The flags which were passed to C<guestfs_aug_init> affect exactly
1512 how files are saved.");
1513
1514   ("aug_load", (RErr, [], []), 27, [Optional "augeas"],
1515    [], (* XXX Augeas code needs tests. *)
1516    "load files into the tree",
1517    "\
1518 Load files into the tree.
1519
1520 See C<aug_load> in the Augeas documentation for the full gory
1521 details.");
1522
1523   ("aug_ls", (RStringList "matches", [String "augpath"], []), 28, [Optional "augeas"],
1524    [], (* XXX Augeas code needs tests. *)
1525    "list Augeas nodes under augpath",
1526    "\
1527 This is just a shortcut for listing C<guestfs_aug_match>
1528 C<path/*> and sorting the resulting nodes into alphabetical order.");
1529
1530   ("rm", (RErr, [Pathname "path"], []), 29, [],
1531    [InitBasicFS, Always, TestRun
1532       [["touch"; "/new"];
1533        ["rm"; "/new"]];
1534     InitBasicFS, Always, TestLastFail
1535       [["rm"; "/new"]];
1536     InitBasicFS, Always, TestLastFail
1537       [["mkdir"; "/new"];
1538        ["rm"; "/new"]]],
1539    "remove a file",
1540    "\
1541 Remove the single file C<path>.");
1542
1543   ("rmdir", (RErr, [Pathname "path"], []), 30, [],
1544    [InitBasicFS, Always, TestRun
1545       [["mkdir"; "/new"];
1546        ["rmdir"; "/new"]];
1547     InitBasicFS, Always, TestLastFail
1548       [["rmdir"; "/new"]];
1549     InitBasicFS, Always, TestLastFail
1550       [["touch"; "/new"];
1551        ["rmdir"; "/new"]]],
1552    "remove a directory",
1553    "\
1554 Remove the single directory C<path>.");
1555
1556   ("rm_rf", (RErr, [Pathname "path"], []), 31, [],
1557    [InitBasicFS, Always, TestOutputFalse
1558       [["mkdir"; "/new"];
1559        ["mkdir"; "/new/foo"];
1560        ["touch"; "/new/foo/bar"];
1561        ["rm_rf"; "/new"];
1562        ["exists"; "/new"]]],
1563    "remove a file or directory recursively",
1564    "\
1565 Remove the file or directory C<path>, recursively removing the
1566 contents if its a directory.  This is like the C<rm -rf> shell
1567 command.");
1568
1569   ("mkdir", (RErr, [Pathname "path"], []), 32, [],
1570    [InitBasicFS, Always, TestOutputTrue
1571       [["mkdir"; "/new"];
1572        ["is_dir"; "/new"]];
1573     InitBasicFS, Always, TestLastFail
1574       [["mkdir"; "/new/foo/bar"]]],
1575    "create a directory",
1576    "\
1577 Create a directory named C<path>.");
1578
1579   ("mkdir_p", (RErr, [Pathname "path"], []), 33, [],
1580    [InitBasicFS, Always, TestOutputTrue
1581       [["mkdir_p"; "/new/foo/bar"];
1582        ["is_dir"; "/new/foo/bar"]];
1583     InitBasicFS, Always, TestOutputTrue
1584       [["mkdir_p"; "/new/foo/bar"];
1585        ["is_dir"; "/new/foo"]];
1586     InitBasicFS, Always, TestOutputTrue
1587       [["mkdir_p"; "/new/foo/bar"];
1588        ["is_dir"; "/new"]];
1589     (* Regression tests for RHBZ#503133: *)
1590     InitBasicFS, Always, TestRun
1591       [["mkdir"; "/new"];
1592        ["mkdir_p"; "/new"]];
1593     InitBasicFS, Always, TestLastFail
1594       [["touch"; "/new"];
1595        ["mkdir_p"; "/new"]]],
1596    "create a directory and parents",
1597    "\
1598 Create a directory named C<path>, creating any parent directories
1599 as necessary.  This is like the C<mkdir -p> shell command.");
1600
1601   ("chmod", (RErr, [Int "mode"; Pathname "path"], []), 34, [],
1602    [], (* XXX Need stat command to test *)
1603    "change file mode",
1604    "\
1605 Change the mode (permissions) of C<path> to C<mode>.  Only
1606 numeric modes are supported.
1607
1608 I<Note>: When using this command from guestfish, C<mode>
1609 by default would be decimal, unless you prefix it with
1610 C<0> to get octal, ie. use C<0700> not C<700>.
1611
1612 The mode actually set is affected by the umask.");
1613
1614   ("chown", (RErr, [Int "owner"; Int "group"; Pathname "path"], []), 35, [],
1615    [], (* XXX Need stat command to test *)
1616    "change file owner and group",
1617    "\
1618 Change the file owner to C<owner> and group to C<group>.
1619
1620 Only numeric uid and gid are supported.  If you want to use
1621 names, you will need to locate and parse the password file
1622 yourself (Augeas support makes this relatively easy).");
1623
1624   ("exists", (RBool "existsflag", [Pathname "path"], []), 36, [],
1625    [InitISOFS, Always, TestOutputTrue (
1626       [["exists"; "/empty"]]);
1627     InitISOFS, Always, TestOutputTrue (
1628       [["exists"; "/directory"]])],
1629    "test if file or directory exists",
1630    "\
1631 This returns C<true> if and only if there is a file, directory
1632 (or anything) with the given C<path> name.
1633
1634 See also C<guestfs_is_file>, C<guestfs_is_dir>, C<guestfs_stat>.");
1635
1636   ("is_file", (RBool "fileflag", [Pathname "path"], []), 37, [],
1637    [InitISOFS, Always, TestOutputTrue (
1638       [["is_file"; "/known-1"]]);
1639     InitISOFS, Always, TestOutputFalse (
1640       [["is_file"; "/directory"]])],
1641    "test if a regular file",
1642    "\
1643 This returns C<true> if and only if there is a regular file
1644 with the given C<path> name.  Note that it returns false for
1645 other objects like directories.
1646
1647 See also C<guestfs_stat>.");
1648
1649   ("is_dir", (RBool "dirflag", [Pathname "path"], []), 38, [],
1650    [InitISOFS, Always, TestOutputFalse (
1651       [["is_dir"; "/known-3"]]);
1652     InitISOFS, Always, TestOutputTrue (
1653       [["is_dir"; "/directory"]])],
1654    "test if a directory",
1655    "\
1656 This returns C<true> if and only if there is a directory
1657 with the given C<path> name.  Note that it returns false for
1658 other objects like files.
1659
1660 See also C<guestfs_stat>.");
1661
1662   ("pvcreate", (RErr, [Device "device"], []), 39, [Optional "lvm2"],
1663    [InitEmpty, Always, TestOutputListOfDevices (
1664       [["part_init"; "/dev/sda"; "mbr"];
1665        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1666        ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1667        ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1668        ["pvcreate"; "/dev/sda1"];
1669        ["pvcreate"; "/dev/sda2"];
1670        ["pvcreate"; "/dev/sda3"];
1671        ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
1672    "create an LVM physical volume",
1673    "\
1674 This creates an LVM physical volume on the named C<device>,
1675 where C<device> should usually be a partition name such
1676 as C</dev/sda1>.");
1677
1678   ("vgcreate", (RErr, [String "volgroup"; DeviceList "physvols"], []), 40, [Optional "lvm2"],
1679    [InitEmpty, Always, TestOutputList (
1680       [["part_init"; "/dev/sda"; "mbr"];
1681        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1682        ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1683        ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1684        ["pvcreate"; "/dev/sda1"];
1685        ["pvcreate"; "/dev/sda2"];
1686        ["pvcreate"; "/dev/sda3"];
1687        ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1688        ["vgcreate"; "VG2"; "/dev/sda3"];
1689        ["vgs"]], ["VG1"; "VG2"])],
1690    "create an LVM volume group",
1691    "\
1692 This creates an LVM volume group called C<volgroup>
1693 from the non-empty list of physical volumes C<physvols>.");
1694
1695   ("lvcreate", (RErr, [String "logvol"; String "volgroup"; Int "mbytes"], []), 41, [Optional "lvm2"],
1696    [InitEmpty, Always, TestOutputList (
1697       [["part_init"; "/dev/sda"; "mbr"];
1698        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1699        ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1700        ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1701        ["pvcreate"; "/dev/sda1"];
1702        ["pvcreate"; "/dev/sda2"];
1703        ["pvcreate"; "/dev/sda3"];
1704        ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1705        ["vgcreate"; "VG2"; "/dev/sda3"];
1706        ["lvcreate"; "LV1"; "VG1"; "50"];
1707        ["lvcreate"; "LV2"; "VG1"; "50"];
1708        ["lvcreate"; "LV3"; "VG2"; "50"];
1709        ["lvcreate"; "LV4"; "VG2"; "50"];
1710        ["lvcreate"; "LV5"; "VG2"; "50"];
1711        ["lvs"]],
1712       ["/dev/VG1/LV1"; "/dev/VG1/LV2";
1713        "/dev/VG2/LV3"; "/dev/VG2/LV4"; "/dev/VG2/LV5"])],
1714    "create an LVM logical volume",
1715    "\
1716 This creates an LVM logical volume called C<logvol>
1717 on the volume group C<volgroup>, with C<size> megabytes.");
1718
1719   ("mkfs", (RErr, [String "fstype"; Device "device"], []), 42, [],
1720    [InitEmpty, Always, TestOutput (
1721       [["part_disk"; "/dev/sda"; "mbr"];
1722        ["mkfs"; "ext2"; "/dev/sda1"];
1723        ["mount_options"; ""; "/dev/sda1"; "/"];
1724        ["write"; "/new"; "new file contents"];
1725        ["cat"; "/new"]], "new file contents")],
1726    "make a filesystem",
1727    "\
1728 This creates a filesystem on C<device> (usually a partition
1729 or LVM logical volume).  The filesystem type is C<fstype>, for
1730 example C<ext3>.");
1731
1732   ("sfdisk", (RErr, [Device "device";
1733                      Int "cyls"; Int "heads"; Int "sectors";
1734                      StringList "lines"], []), 43, [DangerWillRobinson],
1735    [],
1736    "create partitions on a block device",
1737    "\
1738 This is a direct interface to the L<sfdisk(8)> program for creating
1739 partitions on block devices.
1740
1741 C<device> should be a block device, for example C</dev/sda>.
1742
1743 C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads
1744 and sectors on the device, which are passed directly to sfdisk as
1745 the I<-C>, I<-H> and I<-S> parameters.  If you pass C<0> for any
1746 of these, then the corresponding parameter is omitted.  Usually for
1747 'large' disks, you can just pass C<0> for these, but for small
1748 (floppy-sized) disks, sfdisk (or rather, the kernel) cannot work
1749 out the right geometry and you will need to tell it.
1750
1751 C<lines> is a list of lines that we feed to C<sfdisk>.  For more
1752 information refer to the L<sfdisk(8)> manpage.
1753
1754 To create a single partition occupying the whole disk, you would
1755 pass C<lines> as a single element list, when the single element being
1756 the string C<,> (comma).
1757
1758 See also: C<guestfs_sfdisk_l>, C<guestfs_sfdisk_N>,
1759 C<guestfs_part_init>");
1760
1761   ("write_file", (RErr, [Pathname "path"; String "content"; Int "size"], []), 44, [ProtocolLimitWarning; DeprecatedBy "write"],
1762    (* Regression test for RHBZ#597135. *)
1763    [InitBasicFS, Always, TestLastFail
1764       [["write_file"; "/new"; "abc"; "10000"]]],
1765    "create a file",
1766    "\
1767 This call creates a file called C<path>.  The contents of the
1768 file is the string C<content> (which can contain any 8 bit data),
1769 with length C<size>.
1770
1771 As a special case, if C<size> is C<0>
1772 then the length is calculated using C<strlen> (so in this case
1773 the content cannot contain embedded ASCII NULs).
1774
1775 I<NB.> Owing to a bug, writing content containing ASCII NUL
1776 characters does I<not> work, even if the length is specified.");
1777
1778   ("umount", (RErr, [String "pathordevice"], []), 45, [FishAlias "unmount"],
1779    [InitEmpty, Always, TestOutputListOfDevices (
1780       [["part_disk"; "/dev/sda"; "mbr"];
1781        ["mkfs"; "ext2"; "/dev/sda1"];
1782        ["mount_options"; ""; "/dev/sda1"; "/"];
1783        ["mounts"]], ["/dev/sda1"]);
1784     InitEmpty, Always, TestOutputList (
1785       [["part_disk"; "/dev/sda"; "mbr"];
1786        ["mkfs"; "ext2"; "/dev/sda1"];
1787        ["mount_options"; ""; "/dev/sda1"; "/"];
1788        ["umount"; "/"];
1789        ["mounts"]], [])],
1790    "unmount a filesystem",
1791    "\
1792 This unmounts the given filesystem.  The filesystem may be
1793 specified either by its mountpoint (path) or the device which
1794 contains the filesystem.");
1795
1796   ("mounts", (RStringList "devices", [], []), 46, [],
1797    [InitBasicFS, Always, TestOutputListOfDevices (
1798       [["mounts"]], ["/dev/sda1"])],
1799    "show mounted filesystems",
1800    "\
1801 This returns the list of currently mounted filesystems.  It returns
1802 the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
1803
1804 Some internal mounts are not shown.
1805
1806 See also: C<guestfs_mountpoints>");
1807
1808   ("umount_all", (RErr, [], []), 47, [FishAlias "unmount-all"],
1809    [InitBasicFS, Always, TestOutputList (
1810       [["umount_all"];
1811        ["mounts"]], []);
1812     (* check that umount_all can unmount nested mounts correctly: *)
1813     InitEmpty, Always, TestOutputList (
1814       [["part_init"; "/dev/sda"; "mbr"];
1815        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1816        ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1817        ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1818        ["mkfs"; "ext2"; "/dev/sda1"];
1819        ["mkfs"; "ext2"; "/dev/sda2"];
1820        ["mkfs"; "ext2"; "/dev/sda3"];
1821        ["mount_options"; ""; "/dev/sda1"; "/"];
1822        ["mkdir"; "/mp1"];
1823        ["mount_options"; ""; "/dev/sda2"; "/mp1"];
1824        ["mkdir"; "/mp1/mp2"];
1825        ["mount_options"; ""; "/dev/sda3"; "/mp1/mp2"];
1826        ["mkdir"; "/mp1/mp2/mp3"];
1827        ["umount_all"];
1828        ["mounts"]], [])],
1829    "unmount all filesystems",
1830    "\
1831 This unmounts all mounted filesystems.
1832
1833 Some internal mounts are not unmounted by this call.");
1834
1835   ("lvm_remove_all", (RErr, [], []), 48, [DangerWillRobinson; Optional "lvm2"],
1836    [],
1837    "remove all LVM LVs, VGs and PVs",
1838    "\
1839 This command removes all LVM logical volumes, volume groups
1840 and physical volumes.");
1841
1842   ("file", (RString "description", [Dev_or_Path "path"], []), 49, [],
1843    [InitISOFS, Always, TestOutput (
1844       [["file"; "/empty"]], "empty");
1845     InitISOFS, Always, TestOutput (
1846       [["file"; "/known-1"]], "ASCII text");
1847     InitISOFS, Always, TestLastFail (
1848       [["file"; "/notexists"]]);
1849     InitISOFS, Always, TestOutput (
1850       [["file"; "/abssymlink"]], "symbolic link");
1851     InitISOFS, Always, TestOutput (
1852       [["file"; "/directory"]], "directory")],
1853    "determine file type",
1854    "\
1855 This call uses the standard L<file(1)> command to determine
1856 the type or contents of the file.
1857
1858 This call will also transparently look inside various types
1859 of compressed file.
1860
1861 The exact command which runs is C<file -zb path>.  Note in
1862 particular that the filename is not prepended to the output
1863 (the C<-b> option).
1864
1865 This command can also be used on C</dev/> devices
1866 (and partitions, LV names).  You can for example use this
1867 to determine if a device contains a filesystem, although
1868 it's usually better to use C<guestfs_vfs_type>.
1869
1870 If the C<path> does not begin with C</dev/> then
1871 this command only works for the content of regular files.
1872 For other file types (directory, symbolic link etc) it
1873 will just return the string C<directory> etc.");
1874
1875   ("command", (RString "output", [StringList "arguments"], []), 50, [ProtocolLimitWarning],
1876    [InitBasicFS, Always, TestOutput (
1877       [["upload"; "test-command"; "/test-command"];
1878        ["chmod"; "0o755"; "/test-command"];
1879        ["command"; "/test-command 1"]], "Result1");
1880     InitBasicFS, Always, TestOutput (
1881       [["upload"; "test-command"; "/test-command"];
1882        ["chmod"; "0o755"; "/test-command"];
1883        ["command"; "/test-command 2"]], "Result2\n");
1884     InitBasicFS, Always, TestOutput (
1885       [["upload"; "test-command"; "/test-command"];
1886        ["chmod"; "0o755"; "/test-command"];
1887        ["command"; "/test-command 3"]], "\nResult3");
1888     InitBasicFS, Always, TestOutput (
1889       [["upload"; "test-command"; "/test-command"];
1890        ["chmod"; "0o755"; "/test-command"];
1891        ["command"; "/test-command 4"]], "\nResult4\n");
1892     InitBasicFS, Always, TestOutput (
1893       [["upload"; "test-command"; "/test-command"];
1894        ["chmod"; "0o755"; "/test-command"];
1895        ["command"; "/test-command 5"]], "\nResult5\n\n");
1896     InitBasicFS, Always, TestOutput (
1897       [["upload"; "test-command"; "/test-command"];
1898        ["chmod"; "0o755"; "/test-command"];
1899        ["command"; "/test-command 6"]], "\n\nResult6\n\n");
1900     InitBasicFS, Always, TestOutput (
1901       [["upload"; "test-command"; "/test-command"];
1902        ["chmod"; "0o755"; "/test-command"];
1903        ["command"; "/test-command 7"]], "");
1904     InitBasicFS, Always, TestOutput (
1905       [["upload"; "test-command"; "/test-command"];
1906        ["chmod"; "0o755"; "/test-command"];
1907        ["command"; "/test-command 8"]], "\n");
1908     InitBasicFS, Always, TestOutput (
1909       [["upload"; "test-command"; "/test-command"];
1910        ["chmod"; "0o755"; "/test-command"];
1911        ["command"; "/test-command 9"]], "\n\n");
1912     InitBasicFS, Always, TestOutput (
1913       [["upload"; "test-command"; "/test-command"];
1914        ["chmod"; "0o755"; "/test-command"];
1915        ["command"; "/test-command 10"]], "Result10-1\nResult10-2\n");
1916     InitBasicFS, Always, TestOutput (
1917       [["upload"; "test-command"; "/test-command"];
1918        ["chmod"; "0o755"; "/test-command"];
1919        ["command"; "/test-command 11"]], "Result11-1\nResult11-2");
1920     InitBasicFS, Always, TestLastFail (
1921       [["upload"; "test-command"; "/test-command"];
1922        ["chmod"; "0o755"; "/test-command"];
1923        ["command"; "/test-command"]])],
1924    "run a command from the guest filesystem",
1925    "\
1926 This call runs a command from the guest filesystem.  The
1927 filesystem must be mounted, and must contain a compatible
1928 operating system (ie. something Linux, with the same
1929 or compatible processor architecture).
1930
1931 The single parameter is an argv-style list of arguments.
1932 The first element is the name of the program to run.
1933 Subsequent elements are parameters.  The list must be
1934 non-empty (ie. must contain a program name).  Note that
1935 the command runs directly, and is I<not> invoked via
1936 the shell (see C<guestfs_sh>).
1937
1938 The return value is anything printed to I<stdout> by
1939 the command.
1940
1941 If the command returns a non-zero exit status, then
1942 this function returns an error message.  The error message
1943 string is the content of I<stderr> from the command.
1944
1945 The C<$PATH> environment variable will contain at least
1946 C</usr/bin> and C</bin>.  If you require a program from
1947 another location, you should provide the full path in the
1948 first parameter.
1949
1950 Shared libraries and data files required by the program
1951 must be available on filesystems which are mounted in the
1952 correct places.  It is the caller's responsibility to ensure
1953 all filesystems that are needed are mounted at the right
1954 locations.");
1955
1956   ("command_lines", (RStringList "lines", [StringList "arguments"], []), 51, [ProtocolLimitWarning],
1957    [InitBasicFS, Always, TestOutputList (
1958       [["upload"; "test-command"; "/test-command"];
1959        ["chmod"; "0o755"; "/test-command"];
1960        ["command_lines"; "/test-command 1"]], ["Result1"]);
1961     InitBasicFS, Always, TestOutputList (
1962       [["upload"; "test-command"; "/test-command"];
1963        ["chmod"; "0o755"; "/test-command"];
1964        ["command_lines"; "/test-command 2"]], ["Result2"]);
1965     InitBasicFS, Always, TestOutputList (
1966       [["upload"; "test-command"; "/test-command"];
1967        ["chmod"; "0o755"; "/test-command"];
1968        ["command_lines"; "/test-command 3"]], ["";"Result3"]);
1969     InitBasicFS, Always, TestOutputList (
1970       [["upload"; "test-command"; "/test-command"];
1971        ["chmod"; "0o755"; "/test-command"];
1972        ["command_lines"; "/test-command 4"]], ["";"Result4"]);
1973     InitBasicFS, Always, TestOutputList (
1974       [["upload"; "test-command"; "/test-command"];
1975        ["chmod"; "0o755"; "/test-command"];
1976        ["command_lines"; "/test-command 5"]], ["";"Result5";""]);
1977     InitBasicFS, Always, TestOutputList (
1978       [["upload"; "test-command"; "/test-command"];
1979        ["chmod"; "0o755"; "/test-command"];
1980        ["command_lines"; "/test-command 6"]], ["";"";"Result6";""]);
1981     InitBasicFS, Always, TestOutputList (
1982       [["upload"; "test-command"; "/test-command"];
1983        ["chmod"; "0o755"; "/test-command"];
1984        ["command_lines"; "/test-command 7"]], []);
1985     InitBasicFS, Always, TestOutputList (
1986       [["upload"; "test-command"; "/test-command"];
1987        ["chmod"; "0o755"; "/test-command"];
1988        ["command_lines"; "/test-command 8"]], [""]);
1989     InitBasicFS, Always, TestOutputList (
1990       [["upload"; "test-command"; "/test-command"];
1991        ["chmod"; "0o755"; "/test-command"];
1992        ["command_lines"; "/test-command 9"]], ["";""]);
1993     InitBasicFS, Always, TestOutputList (
1994       [["upload"; "test-command"; "/test-command"];
1995        ["chmod"; "0o755"; "/test-command"];
1996        ["command_lines"; "/test-command 10"]], ["Result10-1";"Result10-2"]);
1997     InitBasicFS, Always, TestOutputList (
1998       [["upload"; "test-command"; "/test-command"];
1999        ["chmod"; "0o755"; "/test-command"];
2000        ["command_lines"; "/test-command 11"]], ["Result11-1";"Result11-2"])],
2001    "run a command, returning lines",
2002    "\
2003 This is the same as C<guestfs_command>, but splits the
2004 result into a list of lines.
2005
2006 See also: C<guestfs_sh_lines>");
2007
2008   ("stat", (RStruct ("statbuf", "stat"), [Pathname "path"], []), 52, [],
2009    [InitISOFS, Always, TestOutputStruct (
2010       [["stat"; "/empty"]], [CompareWithInt ("size", 0)])],
2011    "get file information",
2012    "\
2013 Returns file information for the given C<path>.
2014
2015 This is the same as the C<stat(2)> system call.");
2016
2017   ("lstat", (RStruct ("statbuf", "stat"), [Pathname "path"], []), 53, [],
2018    [InitISOFS, Always, TestOutputStruct (
2019       [["lstat"; "/empty"]], [CompareWithInt ("size", 0)])],
2020    "get file information for a symbolic link",
2021    "\
2022 Returns file information for the given C<path>.
2023
2024 This is the same as C<guestfs_stat> except that if C<path>
2025 is a symbolic link, then the link is stat-ed, not the file it
2026 refers to.
2027
2028 This is the same as the C<lstat(2)> system call.");
2029
2030   ("statvfs", (RStruct ("statbuf", "statvfs"), [Pathname "path"], []), 54, [],
2031    [InitISOFS, Always, TestOutputStruct (
2032       [["statvfs"; "/"]], [CompareWithInt ("namemax", 255)])],
2033    "get file system statistics",
2034    "\
2035 Returns file system statistics for any mounted file system.
2036 C<path> should be a file or directory in the mounted file system
2037 (typically it is the mount point itself, but it doesn't need to be).
2038
2039 This is the same as the C<statvfs(2)> system call.");
2040
2041   ("tune2fs_l", (RHashtable "superblock", [Device "device"], []), 55, [],
2042    [], (* XXX test *)
2043    "get ext2/ext3/ext4 superblock details",
2044    "\
2045 This returns the contents of the ext2, ext3 or ext4 filesystem
2046 superblock on C<device>.
2047
2048 It is the same as running C<tune2fs -l device>.  See L<tune2fs(8)>
2049 manpage for more details.  The list of fields returned isn't
2050 clearly defined, and depends on both the version of C<tune2fs>
2051 that libguestfs was built against, and the filesystem itself.");
2052
2053   ("blockdev_setro", (RErr, [Device "device"], []), 56, [],
2054    [InitEmpty, Always, TestOutputTrue (
2055       [["blockdev_setro"; "/dev/sda"];
2056        ["blockdev_getro"; "/dev/sda"]])],
2057    "set block device to read-only",
2058    "\
2059 Sets the block device named C<device> to read-only.
2060
2061 This uses the L<blockdev(8)> command.");
2062
2063   ("blockdev_setrw", (RErr, [Device "device"], []), 57, [],
2064    [InitEmpty, Always, TestOutputFalse (
2065       [["blockdev_setrw"; "/dev/sda"];
2066        ["blockdev_getro"; "/dev/sda"]])],
2067    "set block device to read-write",
2068    "\
2069 Sets the block device named C<device> to read-write.
2070
2071 This uses the L<blockdev(8)> command.");
2072
2073   ("blockdev_getro", (RBool "ro", [Device "device"], []), 58, [],
2074    [InitEmpty, Always, TestOutputTrue (
2075       [["blockdev_setro"; "/dev/sda"];
2076        ["blockdev_getro"; "/dev/sda"]])],
2077    "is block device set to read-only",
2078    "\
2079 Returns a boolean indicating if the block device is read-only
2080 (true if read-only, false if not).
2081
2082 This uses the L<blockdev(8)> command.");
2083
2084   ("blockdev_getss", (RInt "sectorsize", [Device "device"], []), 59, [],
2085    [InitEmpty, Always, TestOutputInt (
2086       [["blockdev_getss"; "/dev/sda"]], 512)],
2087    "get sectorsize of block device",
2088    "\
2089 This returns the size of sectors on a block device.
2090 Usually 512, but can be larger for modern devices.
2091
2092 (Note, this is not the size in sectors, use C<guestfs_blockdev_getsz>
2093 for that).
2094
2095 This uses the L<blockdev(8)> command.");
2096
2097   ("blockdev_getbsz", (RInt "blocksize", [Device "device"], []), 60, [],
2098    [InitEmpty, Always, TestOutputInt (
2099       [["blockdev_getbsz"; "/dev/sda"]], 4096)],
2100    "get blocksize of block device",
2101    "\
2102 This returns the block size of a device.
2103
2104 (Note this is different from both I<size in blocks> and
2105 I<filesystem block size>).
2106
2107 This uses the L<blockdev(8)> command.");
2108
2109   ("blockdev_setbsz", (RErr, [Device "device"; Int "blocksize"], []), 61, [],
2110    [], (* XXX test *)
2111    "set blocksize of block device",
2112    "\
2113 This sets the block size of a device.
2114
2115 (Note this is different from both I<size in blocks> and
2116 I<filesystem block size>).
2117
2118 This uses the L<blockdev(8)> command.");
2119
2120   ("blockdev_getsz", (RInt64 "sizeinsectors", [Device "device"], []), 62, [],
2121    [InitEmpty, Always, TestOutputInt (
2122       [["blockdev_getsz"; "/dev/sda"]], 1024000)],
2123    "get total size of device in 512-byte sectors",
2124    "\
2125 This returns the size of the device in units of 512-byte sectors
2126 (even if the sectorsize isn't 512 bytes ... weird).
2127
2128 See also C<guestfs_blockdev_getss> for the real sector size of
2129 the device, and C<guestfs_blockdev_getsize64> for the more
2130 useful I<size in bytes>.
2131
2132 This uses the L<blockdev(8)> command.");
2133
2134   ("blockdev_getsize64", (RInt64 "sizeinbytes", [Device "device"], []), 63, [],
2135    [InitEmpty, Always, TestOutputInt (
2136       [["blockdev_getsize64"; "/dev/sda"]], 524288000)],
2137    "get total size of device in bytes",
2138    "\
2139 This returns the size of the device in bytes.
2140
2141 See also C<guestfs_blockdev_getsz>.
2142
2143 This uses the L<blockdev(8)> command.");
2144
2145   ("blockdev_flushbufs", (RErr, [Device "device"], []), 64, [],
2146    [InitEmpty, Always, TestRun
2147       [["blockdev_flushbufs"; "/dev/sda"]]],
2148    "flush device buffers",
2149    "\
2150 This tells the kernel to flush internal buffers associated
2151 with C<device>.
2152
2153 This uses the L<blockdev(8)> command.");
2154
2155   ("blockdev_rereadpt", (RErr, [Device "device"], []), 65, [],
2156    [InitEmpty, Always, TestRun
2157       [["blockdev_rereadpt"; "/dev/sda"]]],
2158    "reread partition table",
2159    "\
2160 Reread the partition table on C<device>.
2161
2162 This uses the L<blockdev(8)> command.");
2163
2164   ("upload", (RErr, [FileIn "filename"; Dev_or_Path "remotefilename"], []), 66, [],
2165    [InitBasicFS, Always, TestOutput (
2166       (* Pick a file from cwd which isn't likely to change. *)
2167       [["upload"; "../COPYING.LIB"; "/COPYING.LIB"];
2168        ["checksum"; "md5"; "/COPYING.LIB"]],
2169       Digest.to_hex (Digest.file "COPYING.LIB"))],
2170    "upload a file from the local machine",
2171    "\
2172 Upload local file C<filename> to C<remotefilename> on the
2173 filesystem.
2174
2175 C<filename> can also be a named pipe.
2176
2177 See also C<guestfs_download>.");
2178
2179   ("download", (RErr, [Dev_or_Path "remotefilename"; FileOut "filename"], []), 67, [Progress],
2180    [InitBasicFS, Always, TestOutput (
2181       (* Pick a file from cwd which isn't likely to change. *)
2182       [["upload"; "../COPYING.LIB"; "/COPYING.LIB"];
2183        ["download"; "/COPYING.LIB"; "testdownload.tmp"];
2184        ["upload"; "testdownload.tmp"; "/upload"];
2185        ["checksum"; "md5"; "/upload"]],
2186       Digest.to_hex (Digest.file "COPYING.LIB"))],
2187    "download a file to the local machine",
2188    "\
2189 Download file C<remotefilename> and save it as C<filename>
2190 on the local machine.
2191
2192 C<filename> can also be a named pipe.
2193
2194 See also C<guestfs_upload>, C<guestfs_cat>.");
2195
2196   ("checksum", (RString "checksum", [String "csumtype"; Pathname "path"], []), 68, [],
2197    [InitISOFS, Always, TestOutput (
2198       [["checksum"; "crc"; "/known-3"]], "2891671662");
2199     InitISOFS, Always, TestLastFail (
2200       [["checksum"; "crc"; "/notexists"]]);
2201     InitISOFS, Always, TestOutput (
2202       [["checksum"; "md5"; "/known-3"]], "46d6ca27ee07cdc6fa99c2e138cc522c");
2203     InitISOFS, Always, TestOutput (
2204       [["checksum"; "sha1"; "/known-3"]], "b7ebccc3ee418311091c3eda0a45b83c0a770f15");
2205     InitISOFS, Always, TestOutput (
2206       [["checksum"; "sha224"; "/known-3"]], "d2cd1774b28f3659c14116be0a6dc2bb5c4b350ce9cd5defac707741");
2207     InitISOFS, Always, TestOutput (
2208       [["checksum"; "sha256"; "/known-3"]], "75bb71b90cd20cb13f86d2bea8dad63ac7194e7517c3b52b8d06ff52d3487d30");
2209     InitISOFS, Always, TestOutput (
2210       [["checksum"; "sha384"; "/known-3"]], "5fa7883430f357b5d7b7271d3a1d2872b51d73cba72731de6863d3dea55f30646af2799bef44d5ea776a5ec7941ac640");
2211     InitISOFS, Always, TestOutput (
2212       [["checksum"; "sha512"; "/known-3"]], "2794062c328c6b216dca90443b7f7134c5f40e56bd0ed7853123275a09982a6f992e6ca682f9d2fba34a4c5e870d8fe077694ff831e3032a004ee077e00603f6");
2213     (* Test for RHBZ#579608, absolute symbolic links. *)
2214     InitISOFS, Always, TestOutput (
2215       [["checksum"; "sha512"; "/abssymlink"]], "5f57d0639bc95081c53afc63a449403883818edc64da48930ad6b1a4fb49be90404686877743fbcd7c99811f3def7df7bc22635c885c6a8cf79c806b43451c1a")],
2216    "compute MD5, SHAx or CRC checksum of file",
2217    "\
2218 This call computes the MD5, SHAx or CRC checksum of the
2219 file named C<path>.
2220
2221 The type of checksum to compute is given by the C<csumtype>
2222 parameter which must have one of the following values:
2223
2224 =over 4
2225
2226 =item C<crc>
2227
2228 Compute the cyclic redundancy check (CRC) specified by POSIX
2229 for the C<cksum> command.
2230
2231 =item C<md5>
2232
2233 Compute the MD5 hash (using the C<md5sum> program).
2234
2235 =item C<sha1>
2236
2237 Compute the SHA1 hash (using the C<sha1sum> program).
2238
2239 =item C<sha224>
2240
2241 Compute the SHA224 hash (using the C<sha224sum> program).
2242
2243 =item C<sha256>
2244
2245 Compute the SHA256 hash (using the C<sha256sum> program).
2246
2247 =item C<sha384>
2248
2249 Compute the SHA384 hash (using the C<sha384sum> program).
2250
2251 =item C<sha512>
2252
2253 Compute the SHA512 hash (using the C<sha512sum> program).
2254
2255 =back
2256
2257 The checksum is returned as a printable string.
2258
2259 To get the checksum for a device, use C<guestfs_checksum_device>.
2260
2261 To get the checksums for many files, use C<guestfs_checksums_out>.");
2262
2263   ("tar_in", (RErr, [FileIn "tarfile"; Pathname "directory"], []), 69, [],
2264    [InitBasicFS, Always, TestOutput (
2265       [["tar_in"; "../images/helloworld.tar"; "/"];
2266        ["cat"; "/hello"]], "hello\n")],
2267    "unpack tarfile to directory",
2268    "\
2269 This command uploads and unpacks local file C<tarfile> (an
2270 I<uncompressed> tar file) into C<directory>.
2271
2272 To upload a compressed tarball, use C<guestfs_tgz_in>
2273 or C<guestfs_txz_in>.");
2274
2275   ("tar_out", (RErr, [String "directory"; FileOut "tarfile"], []), 70, [],
2276    [],
2277    "pack directory into tarfile",
2278    "\
2279 This command packs the contents of C<directory> and downloads
2280 it to local file C<tarfile>.
2281
2282 To download a compressed tarball, use C<guestfs_tgz_out>
2283 or C<guestfs_txz_out>.");
2284
2285   ("tgz_in", (RErr, [FileIn "tarball"; Pathname "directory"], []), 71, [],
2286    [InitBasicFS, Always, TestOutput (
2287       [["tgz_in"; "../images/helloworld.tar.gz"; "/"];
2288        ["cat"; "/hello"]], "hello\n")],
2289    "unpack compressed tarball to directory",
2290    "\
2291 This command uploads and unpacks local file C<tarball> (a
2292 I<gzip compressed> tar file) into C<directory>.
2293
2294 To upload an uncompressed tarball, use C<guestfs_tar_in>.");
2295
2296   ("tgz_out", (RErr, [Pathname "directory"; FileOut "tarball"], []), 72, [],
2297    [],
2298    "pack directory into compressed tarball",
2299    "\
2300 This command packs the contents of C<directory> and downloads
2301 it to local file C<tarball>.
2302
2303 To download an uncompressed tarball, use C<guestfs_tar_out>.");
2304
2305   ("mount_ro", (RErr, [Device "device"; String "mountpoint"], []), 73, [],
2306    [InitBasicFS, Always, TestLastFail (
2307       [["umount"; "/"];
2308        ["mount_ro"; "/dev/sda1"; "/"];
2309        ["touch"; "/new"]]);
2310     InitBasicFS, Always, TestOutput (
2311       [["write"; "/new"; "data"];
2312        ["umount"; "/"];
2313        ["mount_ro"; "/dev/sda1"; "/"];
2314        ["cat"; "/new"]], "data")],
2315    "mount a guest disk, read-only",
2316    "\
2317 This is the same as the C<guestfs_mount> command, but it
2318 mounts the filesystem with the read-only (I<-o ro>) flag.");
2319
2320   ("mount_options", (RErr, [String "options"; Device "device"; String "mountpoint"], []), 74, [],
2321    [],
2322    "mount a guest disk with mount options",
2323    "\
2324 This is the same as the C<guestfs_mount> command, but it
2325 allows you to set the mount options as for the
2326 L<mount(8)> I<-o> flag.
2327
2328 If the C<options> parameter is an empty string, then
2329 no options are passed (all options default to whatever
2330 the filesystem uses).");
2331
2332   ("mount_vfs", (RErr, [String "options"; String "vfstype"; Device "device"; String "mountpoint"], []), 75, [],
2333    [],
2334    "mount a guest disk with mount options and vfstype",
2335    "\
2336 This is the same as the C<guestfs_mount> command, but it
2337 allows you to set both the mount options and the vfstype
2338 as for the L<mount(8)> I<-o> and I<-t> flags.");
2339
2340   ("debug", (RString "result", [String "subcmd"; StringList "extraargs"], []), 76, [NotInDocs],
2341    [],
2342    "debugging and internals",
2343    "\
2344 The C<guestfs_debug> command exposes some internals of
2345 C<guestfsd> (the guestfs daemon) that runs inside the
2346 qemu subprocess.
2347
2348 There is no comprehensive help for this command.  You have
2349 to look at the file C<daemon/debug.c> in the libguestfs source
2350 to find out what you can do.");
2351
2352   ("lvremove", (RErr, [Device "device"], []), 77, [Optional "lvm2"],
2353    [InitEmpty, Always, TestOutputList (
2354       [["part_disk"; "/dev/sda"; "mbr"];
2355        ["pvcreate"; "/dev/sda1"];
2356        ["vgcreate"; "VG"; "/dev/sda1"];
2357        ["lvcreate"; "LV1"; "VG"; "50"];
2358        ["lvcreate"; "LV2"; "VG"; "50"];
2359        ["lvremove"; "/dev/VG/LV1"];
2360        ["lvs"]], ["/dev/VG/LV2"]);
2361     InitEmpty, Always, TestOutputList (
2362       [["part_disk"; "/dev/sda"; "mbr"];
2363        ["pvcreate"; "/dev/sda1"];
2364        ["vgcreate"; "VG"; "/dev/sda1"];
2365        ["lvcreate"; "LV1"; "VG"; "50"];
2366        ["lvcreate"; "LV2"; "VG"; "50"];
2367        ["lvremove"; "/dev/VG"];
2368        ["lvs"]], []);
2369     InitEmpty, Always, TestOutputList (
2370       [["part_disk"; "/dev/sda"; "mbr"];
2371        ["pvcreate"; "/dev/sda1"];
2372        ["vgcreate"; "VG"; "/dev/sda1"];
2373        ["lvcreate"; "LV1"; "VG"; "50"];
2374        ["lvcreate"; "LV2"; "VG"; "50"];
2375        ["lvremove"; "/dev/VG"];
2376        ["vgs"]], ["VG"])],
2377    "remove an LVM logical volume",
2378    "\
2379 Remove an LVM logical volume C<device>, where C<device> is
2380 the path to the LV, such as C</dev/VG/LV>.
2381
2382 You can also remove all LVs in a volume group by specifying
2383 the VG name, C</dev/VG>.");
2384
2385   ("vgremove", (RErr, [String "vgname"], []), 78, [Optional "lvm2"],
2386    [InitEmpty, Always, TestOutputList (
2387       [["part_disk"; "/dev/sda"; "mbr"];
2388        ["pvcreate"; "/dev/sda1"];
2389        ["vgcreate"; "VG"; "/dev/sda1"];
2390        ["lvcreate"; "LV1"; "VG"; "50"];
2391        ["lvcreate"; "LV2"; "VG"; "50"];
2392        ["vgremove"; "VG"];
2393        ["lvs"]], []);
2394     InitEmpty, Always, TestOutputList (
2395       [["part_disk"; "/dev/sda"; "mbr"];
2396        ["pvcreate"; "/dev/sda1"];
2397        ["vgcreate"; "VG"; "/dev/sda1"];
2398        ["lvcreate"; "LV1"; "VG"; "50"];
2399        ["lvcreate"; "LV2"; "VG"; "50"];
2400        ["vgremove"; "VG"];
2401        ["vgs"]], [])],
2402    "remove an LVM volume group",
2403    "\
2404 Remove an LVM volume group C<vgname>, (for example C<VG>).
2405
2406 This also forcibly removes all logical volumes in the volume
2407 group (if any).");
2408
2409   ("pvremove", (RErr, [Device "device"], []), 79, [Optional "lvm2"],
2410    [InitEmpty, Always, TestOutputListOfDevices (
2411       [["part_disk"; "/dev/sda"; "mbr"];
2412        ["pvcreate"; "/dev/sda1"];
2413        ["vgcreate"; "VG"; "/dev/sda1"];
2414        ["lvcreate"; "LV1"; "VG"; "50"];
2415        ["lvcreate"; "LV2"; "VG"; "50"];
2416        ["vgremove"; "VG"];
2417        ["pvremove"; "/dev/sda1"];
2418        ["lvs"]], []);
2419     InitEmpty, Always, TestOutputListOfDevices (
2420       [["part_disk"; "/dev/sda"; "mbr"];
2421        ["pvcreate"; "/dev/sda1"];
2422        ["vgcreate"; "VG"; "/dev/sda1"];
2423        ["lvcreate"; "LV1"; "VG"; "50"];
2424        ["lvcreate"; "LV2"; "VG"; "50"];
2425        ["vgremove"; "VG"];
2426        ["pvremove"; "/dev/sda1"];
2427        ["vgs"]], []);
2428     InitEmpty, Always, TestOutputListOfDevices (
2429       [["part_disk"; "/dev/sda"; "mbr"];
2430        ["pvcreate"; "/dev/sda1"];
2431        ["vgcreate"; "VG"; "/dev/sda1"];
2432        ["lvcreate"; "LV1"; "VG"; "50"];
2433        ["lvcreate"; "LV2"; "VG"; "50"];
2434        ["vgremove"; "VG"];
2435        ["pvremove"; "/dev/sda1"];
2436        ["pvs"]], [])],
2437    "remove an LVM physical volume",
2438    "\
2439 This wipes a physical volume C<device> so that LVM will no longer
2440 recognise it.
2441
2442 The implementation uses the C<pvremove> command which refuses to
2443 wipe physical volumes that contain any volume groups, so you have
2444 to remove those first.");
2445
2446   ("set_e2label", (RErr, [Device "device"; String "label"], []), 80, [],
2447    [InitBasicFS, Always, TestOutput (
2448       [["set_e2label"; "/dev/sda1"; "testlabel"];
2449        ["get_e2label"; "/dev/sda1"]], "testlabel")],
2450    "set the ext2/3/4 filesystem label",
2451    "\
2452 This sets the ext2/3/4 filesystem label of the filesystem on
2453 C<device> to C<label>.  Filesystem labels are limited to
2454 16 characters.
2455
2456 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2label>
2457 to return the existing label on a filesystem.");
2458
2459   ("get_e2label", (RString "label", [Device "device"], []), 81, [DeprecatedBy "vfs_label"],
2460    [],
2461    "get the ext2/3/4 filesystem label",
2462    "\
2463 This returns the ext2/3/4 filesystem label of the filesystem on
2464 C<device>.");
2465
2466   ("set_e2uuid", (RErr, [Device "device"; String "uuid"], []), 82, [],
2467    (let uuid = uuidgen () in
2468     [InitBasicFS, Always, TestOutput (
2469        [["set_e2uuid"; "/dev/sda1"; uuid];
2470         ["get_e2uuid"; "/dev/sda1"]], uuid);
2471      InitBasicFS, Always, TestOutput (
2472        [["set_e2uuid"; "/dev/sda1"; "clear"];
2473         ["get_e2uuid"; "/dev/sda1"]], "");
2474      (* We can't predict what UUIDs will be, so just check the commands run. *)
2475      InitBasicFS, Always, TestRun (
2476        [["set_e2uuid"; "/dev/sda1"; "random"]]);
2477      InitBasicFS, Always, TestRun (
2478        [["set_e2uuid"; "/dev/sda1"; "time"]])]),
2479    "set the ext2/3/4 filesystem UUID",
2480    "\
2481 This sets the ext2/3/4 filesystem UUID of the filesystem on
2482 C<device> to C<uuid>.  The format of the UUID and alternatives
2483 such as C<clear>, C<random> and C<time> are described in the
2484 L<tune2fs(8)> manpage.
2485
2486 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2uuid>
2487 to return the existing UUID of a filesystem.");
2488
2489   ("get_e2uuid", (RString "uuid", [Device "device"], []), 83, [DeprecatedBy "vfs_uuid"],
2490    (* Regression test for RHBZ#597112. *)
2491    (let uuid = uuidgen () in
2492     [InitBasicFS, Always, TestOutput (
2493        [["mke2journal"; "1024"; "/dev/sdb"];
2494         ["set_e2uuid"; "/dev/sdb"; uuid];
2495         ["get_e2uuid"; "/dev/sdb"]], uuid)]),
2496    "get the ext2/3/4 filesystem UUID",
2497    "\
2498 This returns the ext2/3/4 filesystem UUID of the filesystem on
2499 C<device>.");
2500
2501   ("fsck", (RInt "status", [String "fstype"; Device "device"], []), 84, [FishOutput FishOutputHexadecimal],
2502    [InitBasicFS, Always, TestOutputInt (
2503       [["umount"; "/dev/sda1"];
2504        ["fsck"; "ext2"; "/dev/sda1"]], 0);
2505     InitBasicFS, Always, TestOutputInt (
2506       [["umount"; "/dev/sda1"];
2507        ["zero"; "/dev/sda1"];
2508        ["fsck"; "ext2"; "/dev/sda1"]], 8)],
2509    "run the filesystem checker",
2510    "\
2511 This runs the filesystem checker (fsck) on C<device> which
2512 should have filesystem type C<fstype>.
2513
2514 The returned integer is the status.  See L<fsck(8)> for the
2515 list of status codes from C<fsck>.
2516
2517 Notes:
2518
2519 =over 4
2520
2521 =item *
2522
2523 Multiple status codes can be summed together.
2524
2525 =item *
2526
2527 A non-zero return code can mean \"success\", for example if
2528 errors have been corrected on the filesystem.
2529
2530 =item *
2531
2532 Checking or repairing NTFS volumes is not supported
2533 (by linux-ntfs).
2534
2535 =back
2536
2537 This command is entirely equivalent to running C<fsck -a -t fstype device>.");
2538
2539   ("zero", (RErr, [Device "device"], []), 85, [Progress],
2540    [InitBasicFS, Always, TestOutput (
2541       [["umount"; "/dev/sda1"];
2542        ["zero"; "/dev/sda1"];
2543        ["file"; "/dev/sda1"]], "data")],
2544    "write zeroes to the device",
2545    "\
2546 This command writes zeroes over the first few blocks of C<device>.
2547
2548 How many blocks are zeroed isn't specified (but it's I<not> enough
2549 to securely wipe the device).  It should be sufficient to remove
2550 any partition tables, filesystem superblocks and so on.
2551
2552 See also: C<guestfs_zero_device>, C<guestfs_scrub_device>.");
2553
2554   ("grub_install", (RErr, [Pathname "root"; Device "device"], []), 86, [],
2555    (* See:
2556     * https://bugzilla.redhat.com/show_bug.cgi?id=484986
2557     * https://bugzilla.redhat.com/show_bug.cgi?id=479760
2558     *)
2559    [InitBasicFS, Always, TestOutputTrue (
2560       [["mkdir_p"; "/boot/grub"];
2561        ["write"; "/boot/grub/device.map"; "(hd0) /dev/vda"];
2562        ["grub_install"; "/"; "/dev/vda"];
2563        ["is_dir"; "/boot"]])],
2564    "install GRUB",
2565    "\
2566 This command installs GRUB (the Grand Unified Bootloader) on
2567 C<device>, with the root directory being C<root>.
2568
2569 Note: If grub-install reports the error
2570 \"No suitable drive was found in the generated device map.\"
2571 it may be that you need to create a C</boot/grub/device.map>
2572 file first that contains the mapping between grub device names
2573 and Linux device names.  It is usually sufficient to create
2574 a file containing:
2575
2576  (hd0) /dev/vda
2577
2578 replacing C</dev/vda> with the name of the installation device.");
2579
2580   ("cp", (RErr, [Pathname "src"; Pathname "dest"], []), 87, [],
2581    [InitBasicFS, Always, TestOutput (
2582       [["write"; "/old"; "file content"];
2583        ["cp"; "/old"; "/new"];
2584        ["cat"; "/new"]], "file content");
2585     InitBasicFS, Always, TestOutputTrue (
2586       [["write"; "/old"; "file content"];
2587        ["cp"; "/old"; "/new"];
2588        ["is_file"; "/old"]]);
2589     InitBasicFS, Always, TestOutput (
2590       [["write"; "/old"; "file content"];
2591        ["mkdir"; "/dir"];
2592        ["cp"; "/old"; "/dir/new"];
2593        ["cat"; "/dir/new"]], "file content")],
2594    "copy a file",
2595    "\
2596 This copies a file from C<src> to C<dest> where C<dest> is
2597 either a destination filename or destination directory.");
2598
2599   ("cp_a", (RErr, [Pathname "src"; Pathname "dest"], []), 88, [],
2600    [InitBasicFS, Always, TestOutput (
2601       [["mkdir"; "/olddir"];
2602        ["mkdir"; "/newdir"];
2603        ["write"; "/olddir/file"; "file content"];
2604        ["cp_a"; "/olddir"; "/newdir"];
2605        ["cat"; "/newdir/olddir/file"]], "file content")],
2606    "copy a file or directory recursively",
2607    "\
2608 This copies a file or directory from C<src> to C<dest>
2609 recursively using the C<cp -a> command.");
2610
2611   ("mv", (RErr, [Pathname "src"; Pathname "dest"], []), 89, [],
2612    [InitBasicFS, Always, TestOutput (
2613       [["write"; "/old"; "file content"];
2614        ["mv"; "/old"; "/new"];
2615        ["cat"; "/new"]], "file content");
2616     InitBasicFS, Always, TestOutputFalse (
2617       [["write"; "/old"; "file content"];
2618        ["mv"; "/old"; "/new"];
2619        ["is_file"; "/old"]])],
2620    "move a file",
2621    "\
2622 This moves a file from C<src> to C<dest> where C<dest> is
2623 either a destination filename or destination directory.");
2624
2625   ("drop_caches", (RErr, [Int "whattodrop"], []), 90, [],
2626    [InitEmpty, Always, TestRun (
2627       [["drop_caches"; "3"]])],
2628    "drop kernel page cache, dentries and inodes",
2629    "\
2630 This instructs the guest kernel to drop its page cache,
2631 and/or dentries and inode caches.  The parameter C<whattodrop>
2632 tells the kernel what precisely to drop, see
2633 L<http://linux-mm.org/Drop_Caches>
2634
2635 Setting C<whattodrop> to 3 should drop everything.
2636
2637 This automatically calls L<sync(2)> before the operation,
2638 so that the maximum guest memory is freed.");
2639
2640   ("dmesg", (RString "kmsgs", [], []), 91, [],
2641    [InitEmpty, Always, TestRun (
2642       [["dmesg"]])],
2643    "return kernel messages",
2644    "\
2645 This returns the kernel messages (C<dmesg> output) from
2646 the guest kernel.  This is sometimes useful for extended
2647 debugging of problems.
2648
2649 Another way to get the same information is to enable
2650 verbose messages with C<guestfs_set_verbose> or by setting
2651 the environment variable C<LIBGUESTFS_DEBUG=1> before
2652 running the program.");
2653
2654   ("ping_daemon", (RErr, [], []), 92, [],
2655    [InitEmpty, Always, TestRun (
2656       [["ping_daemon"]])],
2657    "ping the guest daemon",
2658    "\
2659 This is a test probe into the guestfs daemon running inside
2660 the qemu subprocess.  Calling this function checks that the
2661 daemon responds to the ping message, without affecting the daemon
2662 or attached block device(s) in any other way.");
2663
2664   ("equal", (RBool "equality", [Pathname "file1"; Pathname "file2"], []), 93, [],
2665    [InitBasicFS, Always, TestOutputTrue (
2666       [["write"; "/file1"; "contents of a file"];
2667        ["cp"; "/file1"; "/file2"];
2668        ["equal"; "/file1"; "/file2"]]);
2669     InitBasicFS, Always, TestOutputFalse (
2670       [["write"; "/file1"; "contents of a file"];
2671        ["write"; "/file2"; "contents of another file"];
2672        ["equal"; "/file1"; "/file2"]]);
2673     InitBasicFS, Always, TestLastFail (
2674       [["equal"; "/file1"; "/file2"]])],
2675    "test if two files have equal contents",
2676    "\
2677 This compares the two files C<file1> and C<file2> and returns
2678 true if their content is exactly equal, or false otherwise.
2679
2680 The external L<cmp(1)> program is used for the comparison.");
2681
2682   ("strings", (RStringList "stringsout", [Pathname "path"], []), 94, [ProtocolLimitWarning],
2683    [InitISOFS, Always, TestOutputList (
2684       [["strings"; "/known-5"]], ["abcdefghi"; "jklmnopqr"]);
2685     InitISOFS, Always, TestOutputList (
2686       [["strings"; "/empty"]], []);
2687     (* Test for RHBZ#579608, absolute symbolic links. *)
2688     InitISOFS, Always, TestRun (
2689       [["strings"; "/abssymlink"]])],
2690    "print the printable strings in a file",
2691    "\
2692 This runs the L<strings(1)> command on a file and returns
2693 the list of printable strings found.");
2694
2695   ("strings_e", (RStringList "stringsout", [String "encoding"; Pathname "path"], []), 95, [ProtocolLimitWarning],
2696    [InitISOFS, Always, TestOutputList (
2697       [["strings_e"; "b"; "/known-5"]], []);
2698     InitBasicFS, Always, TestOutputList (
2699       [["write"; "/new"; "\000h\000e\000l\000l\000o\000\n\000w\000o\000r\000l\000d\000\n"];
2700        ["strings_e"; "b"; "/new"]], ["hello"; "world"])],
2701    "print the printable strings in a file",
2702    "\
2703 This is like the C<guestfs_strings> command, but allows you to
2704 specify the encoding of strings that are looked for in
2705 the source file C<path>.
2706
2707 Allowed encodings are:
2708
2709 =over 4
2710
2711 =item s
2712
2713 Single 7-bit-byte characters like ASCII and the ASCII-compatible
2714 parts of ISO-8859-X (this is what C<guestfs_strings> uses).
2715
2716 =item S
2717
2718 Single 8-bit-byte characters.
2719
2720 =item b
2721
2722 16-bit big endian strings such as those encoded in
2723 UTF-16BE or UCS-2BE.
2724
2725 =item l (lower case letter L)
2726
2727 16-bit little endian such as UTF-16LE and UCS-2LE.
2728 This is useful for examining binaries in Windows guests.
2729
2730 =item B
2731
2732 32-bit big endian such as UCS-4BE.
2733
2734 =item L
2735
2736 32-bit little endian such as UCS-4LE.
2737
2738 =back
2739
2740 The returned strings are transcoded to UTF-8.");
2741
2742   ("hexdump", (RString "dump", [Pathname "path"], []), 96, [ProtocolLimitWarning],
2743    [InitISOFS, Always, TestOutput (
2744       [["hexdump"; "/known-4"]], "00000000  61 62 63 0a 64 65 66 0a  67 68 69                 |abc.def.ghi|\n0000000b\n");
2745     (* Test for RHBZ#501888c2 regression which caused large hexdump
2746      * commands to segfault.
2747      *)
2748     InitISOFS, Always, TestRun (
2749       [["hexdump"; "/100krandom"]]);
2750     (* Test for RHBZ#579608, absolute symbolic links. *)
2751     InitISOFS, Always, TestRun (
2752       [["hexdump"; "/abssymlink"]])],
2753    "dump a file in hexadecimal",
2754    "\
2755 This runs C<hexdump -C> on the given C<path>.  The result is
2756 the human-readable, canonical hex dump of the file.");
2757
2758   ("zerofree", (RErr, [Device "device"], []), 97, [Optional "zerofree"],
2759    [InitNone, Always, TestOutput (
2760       [["part_disk"; "/dev/sda"; "mbr"];
2761        ["mkfs"; "ext3"; "/dev/sda1"];
2762        ["mount_options"; ""; "/dev/sda1"; "/"];
2763        ["write"; "/new"; "test file"];
2764        ["umount"; "/dev/sda1"];
2765        ["zerofree"; "/dev/sda1"];
2766        ["mount_options"; ""; "/dev/sda1"; "/"];
2767        ["cat"; "/new"]], "test file")],
2768    "zero unused inodes and disk blocks on ext2/3 filesystem",
2769    "\
2770 This runs the I<zerofree> program on C<device>.  This program
2771 claims to zero unused inodes and disk blocks on an ext2/3
2772 filesystem, thus making it possible to compress the filesystem
2773 more effectively.
2774
2775 You should B<not> run this program if the filesystem is
2776 mounted.
2777
2778 It is possible that using this program can damage the filesystem
2779 or data on the filesystem.");
2780
2781   ("pvresize", (RErr, [Device "device"], []), 98, [Optional "lvm2"],
2782    [],
2783    "resize an LVM physical volume",
2784    "\
2785 This resizes (expands or shrinks) an existing LVM physical
2786 volume to match the new size of the underlying device.");
2787
2788   ("sfdisk_N", (RErr, [Device "device"; Int "partnum";
2789                        Int "cyls"; Int "heads"; Int "sectors";
2790                        String "line"], []), 99, [DangerWillRobinson],
2791    [],
2792    "modify a single partition on a block device",
2793    "\
2794 This runs L<sfdisk(8)> option to modify just the single
2795 partition C<n> (note: C<n> counts from 1).
2796
2797 For other parameters, see C<guestfs_sfdisk>.  You should usually
2798 pass C<0> for the cyls/heads/sectors parameters.
2799
2800 See also: C<guestfs_part_add>");
2801
2802   ("sfdisk_l", (RString "partitions", [Device "device"], []), 100, [],
2803    [],
2804    "display the partition table",
2805    "\
2806 This displays the partition table on C<device>, in the
2807 human-readable output of the L<sfdisk(8)> command.  It is
2808 not intended to be parsed.
2809
2810 See also: C<guestfs_part_list>");
2811
2812   ("sfdisk_kernel_geometry", (RString "partitions", [Device "device"], []), 101, [],
2813    [],
2814    "display the kernel geometry",
2815    "\
2816 This displays the kernel's idea of the geometry of C<device>.
2817
2818 The result is in human-readable format, and not designed to
2819 be parsed.");
2820
2821   ("sfdisk_disk_geometry", (RString "partitions", [Device "device"], []), 102, [],
2822    [],
2823    "display the disk geometry from the partition table",
2824    "\
2825 This displays the disk geometry of C<device> read from the
2826 partition table.  Especially in the case where the underlying
2827 block device has been resized, this can be different from the
2828 kernel's idea of the geometry (see C<guestfs_sfdisk_kernel_geometry>).
2829
2830 The result is in human-readable format, and not designed to
2831 be parsed.");
2832
2833   ("vg_activate_all", (RErr, [Bool "activate"], []), 103, [Optional "lvm2"],
2834    [],
2835    "activate or deactivate all volume groups",
2836    "\
2837 This command activates or (if C<activate> is false) deactivates
2838 all logical volumes in all volume groups.
2839 If activated, then they are made known to the
2840 kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
2841 then those devices disappear.
2842
2843 This command is the same as running C<vgchange -a y|n>");
2844
2845   ("vg_activate", (RErr, [Bool "activate"; StringList "volgroups"], []), 104, [Optional "lvm2"],
2846    [],
2847    "activate or deactivate some volume groups",
2848    "\
2849 This command activates or (if C<activate> is false) deactivates
2850 all logical volumes in the listed volume groups C<volgroups>.
2851 If activated, then they are made known to the
2852 kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
2853 then those devices disappear.
2854
2855 This command is the same as running C<vgchange -a y|n volgroups...>
2856
2857 Note that if C<volgroups> is an empty list then B<all> volume groups
2858 are activated or deactivated.");
2859
2860   ("lvresize", (RErr, [Device "device"; Int "mbytes"], []), 105, [Optional "lvm2"],
2861    [InitNone, Always, TestOutput (
2862       [["part_disk"; "/dev/sda"; "mbr"];
2863        ["pvcreate"; "/dev/sda1"];
2864        ["vgcreate"; "VG"; "/dev/sda1"];
2865        ["lvcreate"; "LV"; "VG"; "10"];
2866        ["mkfs"; "ext2"; "/dev/VG/LV"];
2867        ["mount_options"; ""; "/dev/VG/LV"; "/"];
2868        ["write"; "/new"; "test content"];
2869        ["umount"; "/"];
2870        ["lvresize"; "/dev/VG/LV"; "20"];
2871        ["e2fsck_f"; "/dev/VG/LV"];
2872        ["resize2fs"; "/dev/VG/LV"];
2873        ["mount_options"; ""; "/dev/VG/LV"; "/"];
2874        ["cat"; "/new"]], "test content");
2875     InitNone, Always, TestRun (
2876       (* Make an LV smaller to test RHBZ#587484. *)
2877       [["part_disk"; "/dev/sda"; "mbr"];
2878        ["pvcreate"; "/dev/sda1"];
2879        ["vgcreate"; "VG"; "/dev/sda1"];
2880        ["lvcreate"; "LV"; "VG"; "20"];
2881        ["lvresize"; "/dev/VG/LV"; "10"]])],
2882    "resize an LVM logical volume",
2883    "\
2884 This resizes (expands or shrinks) an existing LVM logical
2885 volume to C<mbytes>.  When reducing, data in the reduced part
2886 is lost.");
2887
2888   ("resize2fs", (RErr, [Device "device"], []), 106, [],
2889    [], (* lvresize tests this *)
2890    "resize an ext2, ext3 or ext4 filesystem",
2891    "\
2892 This resizes an ext2, ext3 or ext4 filesystem to match the size of
2893 the underlying device.
2894
2895 I<Note:> It is sometimes required that you run C<guestfs_e2fsck_f>
2896 on the C<device> before calling this command.  For unknown reasons
2897 C<resize2fs> sometimes gives an error about this and sometimes not.
2898 In any case, it is always safe to call C<guestfs_e2fsck_f> before
2899 calling this function.");
2900
2901   ("find", (RStringList "names", [Pathname "directory"], []), 107, [ProtocolLimitWarning],
2902    [InitBasicFS, Always, TestOutputList (
2903       [["find"; "/"]], ["lost+found"]);
2904     InitBasicFS, Always, TestOutputList (
2905       [["touch"; "/a"];
2906        ["mkdir"; "/b"];
2907        ["touch"; "/b/c"];
2908        ["find"; "/"]], ["a"; "b"; "b/c"; "lost+found"]);
2909     InitBasicFS, Always, TestOutputList (
2910       [["mkdir_p"; "/a/b/c"];
2911        ["touch"; "/a/b/c/d"];
2912        ["find"; "/a/b/"]], ["c"; "c/d"])],
2913    "find all files and directories",
2914    "\
2915 This command lists out all files and directories, recursively,
2916 starting at C<directory>.  It is essentially equivalent to
2917 running the shell command C<find directory -print> but some
2918 post-processing happens on the output, described below.
2919
2920 This returns a list of strings I<without any prefix>.  Thus
2921 if the directory structure was:
2922
2923  /tmp/a
2924  /tmp/b
2925  /tmp/c/d
2926
2927 then the returned list from C<guestfs_find> C</tmp> would be
2928 4 elements:
2929
2930  a
2931  b
2932  c
2933  c/d
2934
2935 If C<directory> is not a directory, then this command returns
2936 an error.
2937
2938 The returned list is sorted.
2939
2940 See also C<guestfs_find0>.");
2941
2942   ("e2fsck_f", (RErr, [Device "device"], []), 108, [],
2943    [], (* lvresize tests this *)
2944    "check an ext2/ext3 filesystem",
2945    "\
2946 This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3
2947 filesystem checker on C<device>, noninteractively (C<-p>),
2948 even if the filesystem appears to be clean (C<-f>).
2949
2950 This command is only needed because of C<guestfs_resize2fs>
2951 (q.v.).  Normally you should use C<guestfs_fsck>.");
2952
2953   ("sleep", (RErr, [Int "secs"], []), 109, [],
2954    [InitNone, Always, TestRun (
2955       [["sleep"; "1"]])],
2956    "sleep for some seconds",
2957    "\
2958 Sleep for C<secs> seconds.");
2959
2960   ("ntfs_3g_probe", (RInt "status", [Bool "rw"; Device "device"], []), 110, [Optional "ntfs3g"],
2961    [InitNone, Always, TestOutputInt (
2962       [["part_disk"; "/dev/sda"; "mbr"];
2963        ["mkfs"; "ntfs"; "/dev/sda1"];
2964        ["ntfs_3g_probe"; "true"; "/dev/sda1"]], 0);
2965     InitNone, Always, TestOutputInt (
2966       [["part_disk"; "/dev/sda"; "mbr"];
2967        ["mkfs"; "ext2"; "/dev/sda1"];
2968        ["ntfs_3g_probe"; "true"; "/dev/sda1"]], 12)],
2969    "probe NTFS volume",
2970    "\
2971 This command runs the L<ntfs-3g.probe(8)> command which probes
2972 an NTFS C<device> for mountability.  (Not all NTFS volumes can
2973 be mounted read-write, and some cannot be mounted at all).
2974
2975 C<rw> is a boolean flag.  Set it to true if you want to test
2976 if the volume can be mounted read-write.  Set it to false if
2977 you want to test if the volume can be mounted read-only.
2978
2979 The return value is an integer which C<0> if the operation
2980 would succeed, or some non-zero value documented in the
2981 L<ntfs-3g.probe(8)> manual page.");
2982
2983   ("sh", (RString "output", [String "command"], []), 111, [],
2984    [], (* XXX needs tests *)
2985    "run a command via the shell",
2986    "\
2987 This call runs a command from the guest filesystem via the
2988 guest's C</bin/sh>.
2989
2990 This is like C<guestfs_command>, but passes the command to:
2991
2992  /bin/sh -c \"command\"
2993
2994 Depending on the guest's shell, this usually results in
2995 wildcards being expanded, shell expressions being interpolated
2996 and so on.
2997
2998 All the provisos about C<guestfs_command> apply to this call.");
2999
3000   ("sh_lines", (RStringList "lines", [String "command"], []), 112, [],
3001    [], (* XXX needs tests *)
3002    "run a command via the shell returning lines",
3003    "\
3004 This is the same as C<guestfs_sh>, but splits the result
3005 into a list of lines.
3006
3007 See also: C<guestfs_command_lines>");
3008
3009   ("glob_expand", (RStringList "paths", [Pathname "pattern"], []), 113, [],
3010    (* Use Pathname here, and hence ABS_PATH (pattern,... in generated
3011     * code in stubs.c, since all valid glob patterns must start with "/".
3012     * There is no concept of "cwd" in libguestfs, hence no "."-relative names.
3013     *)
3014    [InitBasicFS, Always, TestOutputList (
3015       [["mkdir_p"; "/a/b/c"];
3016        ["touch"; "/a/b/c/d"];
3017        ["touch"; "/a/b/c/e"];
3018        ["glob_expand"; "/a/b/c/*"]], ["/a/b/c/d"; "/a/b/c/e"]);
3019     InitBasicFS, Always, TestOutputList (
3020       [["mkdir_p"; "/a/b/c"];
3021        ["touch"; "/a/b/c/d"];
3022        ["touch"; "/a/b/c/e"];
3023        ["glob_expand"; "/a/*/c/*"]], ["/a/b/c/d"; "/a/b/c/e"]);
3024     InitBasicFS, Always, TestOutputList (
3025       [["mkdir_p"; "/a/b/c"];
3026        ["touch"; "/a/b/c/d"];
3027        ["touch"; "/a/b/c/e"];
3028        ["glob_expand"; "/a/*/x/*"]], [])],
3029    "expand a wildcard path",
3030    "\
3031 This command searches for all the pathnames matching
3032 C<pattern> according to the wildcard expansion rules
3033 used by the shell.
3034
3035 If no paths match, then this returns an empty list
3036 (note: not an error).
3037
3038 It is just a wrapper around the C L<glob(3)> function
3039 with flags C<GLOB_MARK|GLOB_BRACE>.
3040 See that manual page for more details.");
3041
3042   ("scrub_device", (RErr, [Device "device"], []), 114, [DangerWillRobinson; Optional "scrub"],
3043    [InitNone, Always, TestRun ( (* use /dev/sdc because it's smaller *)
3044       [["scrub_device"; "/dev/sdc"]])],
3045    "scrub (securely wipe) a device",
3046    "\
3047 This command writes patterns over C<device> to make data retrieval
3048 more difficult.
3049
3050 It is an interface to the L<scrub(1)> program.  See that
3051 manual page for more details.");
3052
3053   ("scrub_file", (RErr, [Pathname "file"], []), 115, [Optional "scrub"],
3054    [InitBasicFS, Always, TestRun (
3055       [["write"; "/file"; "content"];
3056        ["scrub_file"; "/file"]])],
3057    "scrub (securely wipe) a file",
3058    "\
3059 This command writes patterns over a file to make data retrieval
3060 more difficult.
3061
3062 The file is I<removed> after scrubbing.
3063
3064 It is an interface to the L<scrub(1)> program.  See that
3065 manual page for more details.");
3066
3067   ("scrub_freespace", (RErr, [Pathname "dir"], []), 116, [Optional "scrub"],
3068    [], (* XXX needs testing *)
3069    "scrub (securely wipe) free space",
3070    "\
3071 This command creates the directory C<dir> and then fills it
3072 with files until the filesystem is full, and scrubs the files
3073 as for C<guestfs_scrub_file>, and deletes them.
3074 The intention is to scrub any free space on the partition
3075 containing C<dir>.
3076
3077 It is an interface to the L<scrub(1)> program.  See that
3078 manual page for more details.");
3079
3080   ("mkdtemp", (RString "dir", [Pathname "template"], []), 117, [],
3081    [InitBasicFS, Always, TestRun (
3082       [["mkdir"; "/tmp"];
3083        ["mkdtemp"; "/tmp/tmpXXXXXX"]])],
3084    "create a temporary directory",
3085    "\
3086 This command creates a temporary directory.  The
3087 C<template> parameter should be a full pathname for the
3088 temporary directory name with the final six characters being
3089 \"XXXXXX\".
3090
3091 For example: \"/tmp/myprogXXXXXX\" or \"/Temp/myprogXXXXXX\",
3092 the second one being suitable for Windows filesystems.
3093
3094 The name of the temporary directory that was created
3095 is returned.
3096
3097 The temporary directory is created with mode 0700
3098 and is owned by root.
3099
3100 The caller is responsible for deleting the temporary
3101 directory and its contents after use.
3102
3103 See also: L<mkdtemp(3)>");
3104
3105   ("wc_l", (RInt "lines", [Pathname "path"], []), 118, [],
3106    [InitISOFS, Always, TestOutputInt (
3107       [["wc_l"; "/10klines"]], 10000);
3108     (* Test for RHBZ#579608, absolute symbolic links. *)
3109     InitISOFS, Always, TestOutputInt (
3110       [["wc_l"; "/abssymlink"]], 10000)],
3111    "count lines in a file",
3112    "\
3113 This command counts the lines in a file, using the
3114 C<wc -l> external command.");
3115
3116   ("wc_w", (RInt "words", [Pathname "path"], []), 119, [],
3117    [InitISOFS, Always, TestOutputInt (
3118       [["wc_w"; "/10klines"]], 10000)],
3119    "count words in a file",
3120    "\
3121 This command counts the words in a file, using the
3122 C<wc -w> external command.");
3123
3124   ("wc_c", (RInt "chars", [Pathname "path"], []), 120, [],
3125    [InitISOFS, Always, TestOutputInt (
3126       [["wc_c"; "/100kallspaces"]], 102400)],
3127    "count characters in a file",
3128    "\
3129 This command counts the characters in a file, using the
3130 C<wc -c> external command.");
3131
3132   ("head", (RStringList "lines", [Pathname "path"], []), 121, [ProtocolLimitWarning],
3133    [InitISOFS, Always, TestOutputList (
3134       [["head"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz";"3abcdefghijklmnopqrstuvwxyz";"4abcdefghijklmnopqrstuvwxyz";"5abcdefghijklmnopqrstuvwxyz";"6abcdefghijklmnopqrstuvwxyz";"7abcdefghijklmnopqrstuvwxyz";"8abcdefghijklmnopqrstuvwxyz";"9abcdefghijklmnopqrstuvwxyz"]);
3135     (* Test for RHBZ#579608, absolute symbolic links. *)
3136     InitISOFS, Always, TestOutputList (
3137       [["head"; "/abssymlink"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz";"3abcdefghijklmnopqrstuvwxyz";"4abcdefghijklmnopqrstuvwxyz";"5abcdefghijklmnopqrstuvwxyz";"6abcdefghijklmnopqrstuvwxyz";"7abcdefghijklmnopqrstuvwxyz";"8abcdefghijklmnopqrstuvwxyz";"9abcdefghijklmnopqrstuvwxyz"])],
3138    "return first 10 lines of a file",
3139    "\
3140 This command returns up to the first 10 lines of a file as
3141 a list of strings.");
3142
3143   ("head_n", (RStringList "lines", [Int "nrlines"; Pathname "path"], []), 122, [ProtocolLimitWarning],
3144    [InitISOFS, Always, TestOutputList (
3145       [["head_n"; "3"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz"]);
3146     InitISOFS, Always, TestOutputList (
3147       [["head_n"; "-9997"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz"]);
3148     InitISOFS, Always, TestOutputList (
3149       [["head_n"; "0"; "/10klines"]], [])],
3150    "return first N lines of a file",
3151    "\
3152 If the parameter C<nrlines> is a positive number, this returns the first
3153 C<nrlines> lines of the file C<path>.
3154
3155 If the parameter C<nrlines> is a negative number, this returns lines
3156 from the file C<path>, excluding the last C<nrlines> lines.
3157
3158 If the parameter C<nrlines> is zero, this returns an empty list.");
3159
3160   ("tail", (RStringList "lines", [Pathname "path"], []), 123, [ProtocolLimitWarning],
3161    [InitISOFS, Always, TestOutputList (
3162       [["tail"; "/10klines"]], ["9990abcdefghijklmnopqrstuvwxyz";"9991abcdefghijklmnopqrstuvwxyz";"9992abcdefghijklmnopqrstuvwxyz";"9993abcdefghijklmnopqrstuvwxyz";"9994abcdefghijklmnopqrstuvwxyz";"9995abcdefghijklmnopqrstuvwxyz";"9996abcdefghijklmnopqrstuvwxyz";"9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"])],
3163    "return last 10 lines of a file",
3164    "\
3165 This command returns up to the last 10 lines of a file as
3166 a list of strings.");
3167
3168   ("tail_n", (RStringList "lines", [Int "nrlines"; Pathname "path"], []), 124, [ProtocolLimitWarning],
3169    [InitISOFS, Always, TestOutputList (
3170       [["tail_n"; "3"; "/10klines"]], ["9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"]);
3171     InitISOFS, Always, TestOutputList (
3172       [["tail_n"; "-9998"; "/10klines"]], ["9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"]);
3173     InitISOFS, Always, TestOutputList (
3174       [["tail_n"; "0"; "/10klines"]], [])],
3175    "return last N lines of a file",
3176    "\
3177 If the parameter C<nrlines> is a positive number, this returns the last
3178 C<nrlines> lines of the file C<path>.
3179
3180 If the parameter C<nrlines> is a negative number, this returns lines
3181 from the file C<path>, starting with the C<-nrlines>th line.
3182
3183 If the parameter C<nrlines> is zero, this returns an empty list.");
3184
3185   ("df", (RString "output", [], []), 125, [],
3186    [], (* XXX Tricky to test because it depends on the exact format
3187         * of the 'df' command and other imponderables.
3188         *)
3189    "report file system disk space usage",
3190    "\
3191 This command runs the C<df> command to report disk space used.
3192
3193 This command is mostly useful for interactive sessions.  It
3194 is I<not> intended that you try to parse the output string.
3195 Use C<statvfs> from programs.");
3196
3197   ("df_h", (RString "output", [], []), 126, [],
3198    [], (* XXX Tricky to test because it depends on the exact format
3199         * of the 'df' command and other imponderables.
3200         *)
3201    "report file system disk space usage (human readable)",
3202    "\
3203 This command runs the C<df -h> command to report disk space used
3204 in human-readable format.
3205
3206 This command is mostly useful for interactive sessions.  It
3207 is I<not> intended that you try to parse the output string.
3208 Use C<statvfs> from programs.");
3209
3210   ("du", (RInt64 "sizekb", [Pathname "path"], []), 127, [],
3211    [InitISOFS, Always, TestOutputInt (
3212       [["du"; "/directory"]], 2 (* ISO fs blocksize is 2K *))],
3213    "estimate file space usage",
3214    "\
3215 This command runs the C<du -s> command to estimate file space
3216 usage for C<path>.
3217
3218 C<path> can be a file or a directory.  If C<path> is a directory
3219 then the estimate includes the contents of the directory and all
3220 subdirectories (recursively).
3221
3222 The result is the estimated size in I<kilobytes>
3223 (ie. units of 1024 bytes).");
3224
3225   ("initrd_list", (RStringList "filenames", [Pathname "path"], []), 128, [],
3226    [InitISOFS, Always, TestOutputList (
3227       [["initrd_list"; "/initrd"]], ["empty";"known-1";"known-2";"known-3";"known-4"; "known-5"])],
3228    "list files in an initrd",
3229    "\
3230 This command lists out files contained in an initrd.
3231
3232 The files are listed without any initial C</> character.  The
3233 files are listed in the order they appear (not necessarily
3234 alphabetical).  Directory names are listed as separate items.
3235
3236 Old Linux kernels (2.4 and earlier) used a compressed ext2
3237 filesystem as initrd.  We I<only> support the newer initramfs
3238 format (compressed cpio files).");
3239
3240   ("mount_loop", (RErr, [Pathname "file"; Pathname "mountpoint"], []), 129, [],
3241    [],
3242    "mount a file using the loop device",
3243    "\
3244 This command lets you mount C<file> (a filesystem image
3245 in a file) on a mount point.  It is entirely equivalent to
3246 the command C<mount -o loop file mountpoint>.");
3247
3248   ("mkswap", (RErr, [Device "device"], []), 130, [],
3249    [InitEmpty, Always, TestRun (
3250       [["part_disk"; "/dev/sda"; "mbr"];
3251        ["mkswap"; "/dev/sda1"]])],
3252    "create a swap partition",
3253    "\
3254 Create a swap partition on C<device>.");
3255
3256   ("mkswap_L", (RErr, [String "label"; Device "device"], []), 131, [],
3257    [InitEmpty, Always, TestRun (
3258       [["part_disk"; "/dev/sda"; "mbr"];
3259        ["mkswap_L"; "hello"; "/dev/sda1"]])],
3260    "create a swap partition with a label",
3261    "\
3262 Create a swap partition on C<device> with label C<label>.
3263
3264 Note that you cannot attach a swap label to a block device
3265 (eg. C</dev/sda>), just to a partition.  This appears to be
3266 a limitation of the kernel or swap tools.");
3267
3268   ("mkswap_U", (RErr, [String "uuid"; Device "device"], []), 132, [Optional "linuxfsuuid"],
3269    (let uuid = uuidgen () in
3270     [InitEmpty, Always, TestRun (
3271        [["part_disk"; "/dev/sda"; "mbr"];
3272         ["mkswap_U"; uuid; "/dev/sda1"]])]),
3273    "create a swap partition with an explicit UUID",
3274    "\
3275 Create a swap partition on C<device> with UUID C<uuid>.");
3276
3277   ("mknod", (RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"], []), 133, [Optional "mknod"],
3278    [InitBasicFS, Always, TestOutputStruct (
3279       [["mknod"; "0o10777"; "0"; "0"; "/node"];
3280        (* NB: default umask 022 means 0777 -> 0755 in these tests *)
3281        ["stat"; "/node"]], [CompareWithInt ("mode", 0o10755)]);
3282     InitBasicFS, Always, TestOutputStruct (
3283       [["mknod"; "0o60777"; "66"; "99"; "/node"];
3284        ["stat"; "/node"]], [CompareWithInt ("mode", 0o60755)])],
3285    "make block, character or FIFO devices",
3286    "\
3287 This call creates block or character special devices, or
3288 named pipes (FIFOs).
3289
3290 The C<mode> parameter should be the mode, using the standard
3291 constants.  C<devmajor> and C<devminor> are the
3292 device major and minor numbers, only used when creating block
3293 and character special devices.
3294
3295 Note that, just like L<mknod(2)>, the mode must be bitwise
3296 OR'd with S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call
3297 just creates a regular file).  These constants are
3298 available in the standard Linux header files, or you can use
3299 C<guestfs_mknod_b>, C<guestfs_mknod_c> or C<guestfs_mkfifo>
3300 which are wrappers around this command which bitwise OR
3301 in the appropriate constant for you.
3302
3303 The mode actually set is affected by the umask.");
3304
3305   ("mkfifo", (RErr, [Int "mode"; Pathname "path"], []), 134, [Optional "mknod"],
3306    [InitBasicFS, Always, TestOutputStruct (
3307       [["mkfifo"; "0o777"; "/node"];
3308        ["stat"; "/node"]], [CompareWithInt ("mode", 0o10755)])],
3309    "make FIFO (named pipe)",
3310    "\
3311 This call creates a FIFO (named pipe) called C<path> with
3312 mode C<mode>.  It is just a convenient wrapper around
3313 C<guestfs_mknod>.
3314
3315 The mode actually set is affected by the umask.");
3316
3317   ("mknod_b", (RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"], []), 135, [Optional "mknod"],
3318    [InitBasicFS, Always, TestOutputStruct (
3319       [["mknod_b"; "0o777"; "99"; "66"; "/node"];
3320        ["stat"; "/node"]], [CompareWithInt ("mode", 0o60755)])],
3321    "make block device node",
3322    "\
3323 This call creates a block device node called C<path> with
3324 mode C<mode> and device major/minor C<devmajor> and C<devminor>.
3325 It is just a convenient wrapper around C<guestfs_mknod>.
3326
3327 The mode actually set is affected by the umask.");
3328
3329   ("mknod_c", (RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"], []), 136, [Optional "mknod"],
3330    [InitBasicFS, Always, TestOutputStruct (
3331       [["mknod_c"; "0o777"; "99"; "66"; "/node"];
3332        ["stat"; "/node"]], [CompareWithInt ("mode", 0o20755)])],
3333    "make char device node",
3334    "\
3335 This call creates a char device node called C<path> with
3336 mode C<mode> and device major/minor C<devmajor> and C<devminor>.
3337 It is just a convenient wrapper around C<guestfs_mknod>.
3338
3339 The mode actually set is affected by the umask.");
3340
3341   ("umask", (RInt "oldmask", [Int "mask"], []), 137, [FishOutput FishOutputOctal],
3342    [InitEmpty, Always, TestOutputInt (
3343       [["umask"; "0o22"]], 0o22)],
3344    "set file mode creation mask (umask)",
3345    "\
3346 This function sets the mask used for creating new files and
3347 device nodes to C<mask & 0777>.
3348
3349 Typical umask values would be C<022> which creates new files
3350 with permissions like \"-rw-r--r--\" or \"-rwxr-xr-x\", and
3351 C<002> which creates new files with permissions like
3352 \"-rw-rw-r--\" or \"-rwxrwxr-x\".
3353
3354 The default umask is C<022>.  This is important because it
3355 means that directories and device nodes will be created with
3356 C<0644> or C<0755> mode even if you specify C<0777>.
3357
3358 See also C<guestfs_get_umask>,
3359 L<umask(2)>, C<guestfs_mknod>, C<guestfs_mkdir>.
3360
3361 This call returns the previous umask.");
3362
3363   ("readdir", (RStructList ("entries", "dirent"), [Pathname "dir"], []), 138, [],
3364    [],
3365    "read directories entries",
3366    "\
3367 This returns the list of directory entries in directory C<dir>.
3368
3369 All entries in the directory are returned, including C<.> and
3370 C<..>.  The entries are I<not> sorted, but returned in the same
3371 order as the underlying filesystem.
3372
3373 Also this call returns basic file type information about each
3374 file.  The C<ftyp> field will contain one of the following characters:
3375
3376 =over 4
3377
3378 =item 'b'
3379
3380 Block special
3381
3382 =item 'c'
3383
3384 Char special
3385
3386 =item 'd'
3387
3388 Directory
3389
3390 =item 'f'
3391
3392 FIFO (named pipe)
3393
3394 =item 'l'
3395
3396 Symbolic link
3397
3398 =item 'r'
3399
3400 Regular file
3401
3402 =item 's'
3403
3404 Socket
3405
3406 =item 'u'
3407
3408 Unknown file type
3409
3410 =item '?'
3411
3412 The L<readdir(3)> call returned a C<d_type> field with an
3413 unexpected value
3414
3415 =back
3416
3417 This function is primarily intended for use by programs.  To
3418 get a simple list of names, use C<guestfs_ls>.  To get a printable
3419 directory for human consumption, use C<guestfs_ll>.");
3420
3421   ("sfdiskM", (RErr, [Device "device"; StringList "lines"], []), 139, [DangerWillRobinson],
3422    [],
3423    "create partitions on a block device",
3424    "\
3425 This is a simplified interface to the C<guestfs_sfdisk>
3426 command, where partition sizes are specified in megabytes
3427 only (rounded to the nearest cylinder) and you don't need
3428 to specify the cyls, heads and sectors parameters which
3429 were rarely if ever used anyway.
3430
3431 See also: C<guestfs_sfdisk>, the L<sfdisk(8)> manpage
3432 and C<guestfs_part_disk>");
3433
3434   ("zfile", (RString "description", [String "meth"; Pathname "path"], []), 140, [DeprecatedBy "file"],
3435    [],
3436    "determine file type inside a compressed file",
3437    "\
3438 This command runs C<file> after first decompressing C<path>
3439 using C<method>.
3440
3441 C<method> must be one of C<gzip>, C<compress> or C<bzip2>.
3442
3443 Since 1.0.63, use C<guestfs_file> instead which can now
3444 process compressed files.");
3445
3446   ("getxattrs", (RStructList ("xattrs", "xattr"), [Pathname "path"], []), 141, [Optional "linuxxattrs"],
3447    [],
3448    "list extended attributes of a file or directory",
3449    "\
3450 This call lists the extended attributes of the file or directory
3451 C<path>.
3452
3453 At the system call level, this is a combination of the
3454 L<listxattr(2)> and L<getxattr(2)> calls.
3455
3456 See also: C<guestfs_lgetxattrs>, L<attr(5)>.");
3457
3458   ("lgetxattrs", (RStructList ("xattrs", "xattr"), [Pathname "path"], []), 142, [Optional "linuxxattrs"],
3459    [],
3460    "list extended attributes of a file or directory",
3461    "\
3462 This is the same as C<guestfs_getxattrs>, but if C<path>
3463 is a symbolic link, then it returns the extended attributes
3464 of the link itself.");
3465
3466   ("setxattr", (RErr, [String "xattr";
3467                        String "val"; Int "vallen"; (* will be BufferIn *)
3468                        Pathname "path"], []), 143, [Optional "linuxxattrs"],
3469    [],
3470    "set extended attribute of a file or directory",
3471    "\
3472 This call sets the extended attribute named C<xattr>
3473 of the file C<path> to the value C<val> (of length C<vallen>).
3474 The value is arbitrary 8 bit data.
3475
3476 See also: C<guestfs_lsetxattr>, L<attr(5)>.");
3477
3478   ("lsetxattr", (RErr, [String "xattr";
3479                         String "val"; Int "vallen"; (* will be BufferIn *)
3480                         Pathname "path"], []), 144, [Optional "linuxxattrs"],
3481    [],
3482    "set extended attribute of a file or directory",
3483    "\
3484 This is the same as C<guestfs_setxattr>, but if C<path>
3485 is a symbolic link, then it sets an extended attribute
3486 of the link itself.");
3487
3488   ("removexattr", (RErr, [String "xattr"; Pathname "path"], []), 145, [Optional "linuxxattrs"],
3489    [],
3490    "remove extended attribute of a file or directory",
3491    "\
3492 This call removes the extended attribute named C<xattr>
3493 of the file C<path>.
3494
3495 See also: C<guestfs_lremovexattr>, L<attr(5)>.");
3496
3497   ("lremovexattr", (RErr, [String "xattr"; Pathname "path"], []), 146, [Optional "linuxxattrs"],
3498    [],
3499    "remove extended attribute of a file or directory",
3500    "\
3501 This is the same as C<guestfs_removexattr>, but if C<path>
3502 is a symbolic link, then it removes an extended attribute
3503 of the link itself.");
3504
3505   ("mountpoints", (RHashtable "mps", [], []), 147, [],
3506    [],
3507    "show mountpoints",
3508    "\
3509 This call is similar to C<guestfs_mounts>.  That call returns
3510 a list of devices.  This one returns a hash table (map) of
3511 device name to directory where the device is mounted.");
3512
3513   ("mkmountpoint", (RErr, [String "exemptpath"], []), 148, [],
3514    (* This is a special case: while you would expect a parameter
3515     * of type "Pathname", that doesn't work, because it implies
3516     * NEED_ROOT in the generated calling code in stubs.c, and
3517     * this function cannot use NEED_ROOT.
3518     *)
3519    [],
3520    "create a mountpoint",
3521    "\
3522 C<guestfs_mkmountpoint> and C<guestfs_rmmountpoint> are
3523 specialized calls that can be used to create extra mountpoints
3524 before mounting the first filesystem.
3525
3526 These calls are I<only> necessary in some very limited circumstances,
3527 mainly the case where you want to mount a mix of unrelated and/or
3528 read-only filesystems together.
3529
3530 For example, live CDs often contain a \"Russian doll\" nest of
3531 filesystems, an ISO outer layer, with a squashfs image inside, with
3532 an ext2/3 image inside that.  You can unpack this as follows
3533 in guestfish:
3534
3535  add-ro Fedora-11-i686-Live.iso
3536  run
3537  mkmountpoint /cd
3538  mkmountpoint /sqsh
3539  mkmountpoint /ext3fs
3540  mount /dev/sda /cd
3541  mount-loop /cd/LiveOS/squashfs.img /sqsh
3542  mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
3543
3544 The inner filesystem is now unpacked under the /ext3fs mountpoint.
3545
3546 C<guestfs_mkmountpoint> is not compatible with C<guestfs_umount_all>.
3547 You may get unexpected errors if you try to mix these calls.  It is
3548 safest to manually unmount filesystems and remove mountpoints after use.
3549
3550 C<guestfs_umount_all> unmounts filesystems by sorting the paths
3551 longest first, so for this to work for manual mountpoints, you
3552 must ensure that the innermost mountpoints have the longest
3553 pathnames, as in the example code above.
3554
3555 For more details see L<https://bugzilla.redhat.com/show_bug.cgi?id=599503>
3556
3557 Autosync [see C<guestfs_set_autosync>, this is set by default on
3558 handles] means that C<guestfs_umount_all> is called when the handle
3559 is closed which can also trigger these issues.");
3560
3561   ("rmmountpoint", (RErr, [String "exemptpath"], []), 149, [],
3562    [],
3563    "remove a mountpoint",
3564    "\
3565 This calls removes a mountpoint that was previously created
3566 with C<guestfs_mkmountpoint>.  See C<guestfs_mkmountpoint>
3567 for full details.");
3568
3569   ("read_file", (RBufferOut "content", [Pathname "path"], []), 150, [ProtocolLimitWarning],
3570    [InitISOFS, Always, TestOutputBuffer (
3571       [["read_file"; "/known-4"]], "abc\ndef\nghi");
3572     (* Test various near large, large and too large files (RHBZ#589039). *)
3573     InitBasicFS, Always, TestLastFail (
3574       [["touch"; "/a"];
3575        ["truncate_size"; "/a"; "4194303"]; (* GUESTFS_MESSAGE_MAX - 1 *)
3576        ["read_file"; "/a"]]);
3577     InitBasicFS, Always, TestLastFail (
3578       [["touch"; "/a"];
3579        ["truncate_size"; "/a"; "4194304"]; (* GUESTFS_MESSAGE_MAX *)
3580        ["read_file"; "/a"]]);
3581     InitBasicFS, Always, TestLastFail (
3582       [["touch"; "/a"];
3583        ["truncate_size"; "/a"; "41943040"]; (* GUESTFS_MESSAGE_MAX * 10 *)
3584        ["read_file"; "/a"]])],
3585    "read a file",
3586    "\
3587 This calls returns the contents of the file C<path> as a
3588 buffer.
3589
3590 Unlike C<guestfs_cat>, this function can correctly
3591 handle files that contain embedded ASCII NUL characters.
3592 However unlike C<guestfs_download>, this function is limited
3593 in the total size of file that can be handled.");
3594
3595   ("grep", (RStringList "lines", [String "regex"; Pathname "path"], []), 151, [ProtocolLimitWarning],
3596    [InitISOFS, Always, TestOutputList (
3597       [["grep"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"]);
3598     InitISOFS, Always, TestOutputList (
3599       [["grep"; "nomatch"; "/test-grep.txt"]], []);
3600     (* Test for RHBZ#579608, absolute symbolic links. *)
3601     InitISOFS, Always, TestOutputList (
3602       [["grep"; "nomatch"; "/abssymlink"]], [])],
3603    "return lines matching a pattern",
3604    "\
3605 This calls the external C<grep> program and returns the
3606 matching lines.");
3607
3608   ("egrep", (RStringList "lines", [String "regex"; Pathname "path"], []), 152, [ProtocolLimitWarning],
3609    [InitISOFS, Always, TestOutputList (
3610       [["egrep"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"])],
3611    "return lines matching a pattern",
3612    "\
3613 This calls the external C<egrep> program and returns the
3614 matching lines.");
3615
3616   ("fgrep", (RStringList "lines", [String "pattern"; Pathname "path"], []), 153, [ProtocolLimitWarning],
3617    [InitISOFS, Always, TestOutputList (
3618       [["fgrep"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"])],
3619    "return lines matching a pattern",
3620    "\
3621 This calls the external C<fgrep> program and returns the
3622 matching lines.");
3623
3624   ("grepi", (RStringList "lines", [String "regex"; Pathname "path"], []), 154, [ProtocolLimitWarning],
3625    [InitISOFS, Always, TestOutputList (
3626       [["grepi"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"; "ABC"])],
3627    "return lines matching a pattern",
3628    "\
3629 This calls the external C<grep -i> program and returns the
3630 matching lines.");
3631
3632   ("egrepi", (RStringList "lines", [String "regex"; Pathname "path"], []), 155, [ProtocolLimitWarning],
3633    [InitISOFS, Always, TestOutputList (
3634       [["egrepi"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"; "ABC"])],
3635    "return lines matching a pattern",
3636    "\
3637 This calls the external C<egrep -i> program and returns the
3638 matching lines.");
3639
3640   ("fgrepi", (RStringList "lines", [String "pattern"; Pathname "path"], []), 156, [ProtocolLimitWarning],
3641    [InitISOFS, Always, TestOutputList (
3642       [["fgrepi"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"; "ABC"])],
3643    "return lines matching a pattern",
3644    "\
3645 This calls the external C<fgrep -i> program and returns the
3646 matching lines.");
3647
3648   ("zgrep", (RStringList "lines", [String "regex"; Pathname "path"], []), 157, [ProtocolLimitWarning],
3649    [InitISOFS, Always, TestOutputList (
3650       [["zgrep"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"])],
3651    "return lines matching a pattern",
3652    "\
3653 This calls the external C<zgrep> program and returns the
3654 matching lines.");
3655
3656   ("zegrep", (RStringList "lines", [String "regex"; Pathname "path"], []), 158, [ProtocolLimitWarning],
3657    [InitISOFS, Always, TestOutputList (
3658       [["zegrep"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"])],
3659    "return lines matching a pattern",
3660    "\
3661 This calls the external C<zegrep> program and returns the
3662 matching lines.");
3663
3664   ("zfgrep", (RStringList "lines", [String "pattern"; Pathname "path"], []), 159, [ProtocolLimitWarning],
3665    [InitISOFS, Always, TestOutputList (
3666       [["zfgrep"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"])],
3667    "return lines matching a pattern",
3668    "\
3669 This calls the external C<zfgrep> program and returns the
3670 matching lines.");
3671
3672   ("zgrepi", (RStringList "lines", [String "regex"; Pathname "path"], []), 160, [ProtocolLimitWarning],
3673    [InitISOFS, Always, TestOutputList (
3674       [["zgrepi"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"; "ABC"])],
3675    "return lines matching a pattern",
3676    "\
3677 This calls the external C<zgrep -i> program and returns the
3678 matching lines.");
3679
3680   ("zegrepi", (RStringList "lines", [String "regex"; Pathname "path"], []), 161, [ProtocolLimitWarning],
3681    [InitISOFS, Always, TestOutputList (
3682       [["zegrepi"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"; "ABC"])],
3683    "return lines matching a pattern",
3684    "\
3685 This calls the external C<zegrep -i> program and returns the
3686 matching lines.");
3687
3688   ("zfgrepi", (RStringList "lines", [String "pattern"; Pathname "path"], []), 162, [ProtocolLimitWarning],
3689    [InitISOFS, Always, TestOutputList (
3690       [["zfgrepi"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"; "ABC"])],
3691    "return lines matching a pattern",
3692    "\
3693 This calls the external C<zfgrep -i> program and returns the
3694 matching lines.");
3695
3696   ("realpath", (RString "rpath", [Pathname "path"], []), 163, [Optional "realpath"],
3697    [InitISOFS, Always, TestOutput (
3698       [["realpath"; "/../directory"]], "/directory")],
3699    "canonicalized absolute pathname",
3700    "\
3701 Return the canonicalized absolute pathname of C<path>.  The
3702 returned path has no C<.>, C<..> or symbolic link path elements.");
3703
3704   ("ln", (RErr, [String "target"; Pathname "linkname"], []), 164, [],
3705    [InitBasicFS, Always, TestOutputStruct (
3706       [["touch"; "/a"];
3707        ["ln"; "/a"; "/b"];
3708        ["stat"; "/b"]], [CompareWithInt ("nlink", 2)])],
3709    "create a hard link",
3710    "\
3711 This command creates a hard link using the C<ln> command.");
3712
3713   ("ln_f", (RErr, [String "target"; Pathname "linkname"], []), 165, [],
3714    [InitBasicFS, Always, TestOutputStruct (
3715       [["touch"; "/a"];
3716        ["touch"; "/b"];
3717        ["ln_f"; "/a"; "/b"];
3718        ["stat"; "/b"]], [CompareWithInt ("nlink", 2)])],
3719    "create a hard link",
3720    "\
3721 This command creates a hard link using the C<ln -f> command.
3722 The C<-f> option removes the link (C<linkname>) if it exists already.");
3723
3724   ("ln_s", (RErr, [String "target"; Pathname "linkname"], []), 166, [],
3725    [InitBasicFS, Always, TestOutputStruct (
3726       [["touch"; "/a"];
3727        ["ln_s"; "a"; "/b"];
3728        ["lstat"; "/b"]], [CompareWithInt ("mode", 0o120777)])],
3729    "create a symbolic link",
3730    "\
3731 This command creates a symbolic link using the C<ln -s> command.");
3732
3733   ("ln_sf", (RErr, [String "target"; Pathname "linkname"], []), 167, [],
3734    [InitBasicFS, Always, TestOutput (
3735       [["mkdir_p"; "/a/b"];
3736        ["touch"; "/a/b/c"];
3737        ["ln_sf"; "../d"; "/a/b/c"];
3738        ["readlink"; "/a/b/c"]], "../d")],
3739    "create a symbolic link",
3740    "\
3741 This command creates a symbolic link using the C<ln -sf> command,
3742 The C<-f> option removes the link (C<linkname>) if it exists already.");
3743
3744   ("readlink", (RString "link", [Pathname "path"], []), 168, [],
3745    [] (* XXX tested above *),
3746    "read the target of a symbolic link",
3747    "\
3748 This command reads the target of a symbolic link.");
3749
3750   ("fallocate", (RErr, [Pathname "path"; Int "len"], []), 169, [DeprecatedBy "fallocate64"],
3751    [InitBasicFS, Always, TestOutputStruct (
3752       [["fallocate"; "/a"; "1000000"];
3753        ["stat"; "/a"]], [CompareWithInt ("size", 1_000_000)])],
3754    "preallocate a file in the guest filesystem",
3755    "\
3756 This command preallocates a file (containing zero bytes) named
3757 C<path> of size C<len> bytes.  If the file exists already, it
3758 is overwritten.
3759
3760 Do not confuse this with the guestfish-specific
3761 C<alloc> command which allocates a file in the host and
3762 attaches it as a device.");
3763
3764   ("swapon_device", (RErr, [Device "device"], []), 170, [],
3765    [InitPartition, Always, TestRun (
3766       [["mkswap"; "/dev/sda1"];
3767        ["swapon_device"; "/dev/sda1"];
3768        ["swapoff_device"; "/dev/sda1"]])],
3769    "enable swap on device",
3770    "\
3771 This command enables the libguestfs appliance to use the
3772 swap device or partition named C<device>.  The increased
3773 memory is made available for all commands, for example
3774 those run using C<guestfs_command> or C<guestfs_sh>.
3775
3776 Note that you should not swap to existing guest swap
3777 partitions unless you know what you are doing.  They may
3778 contain hibernation information, or other information that
3779 the guest doesn't want you to trash.  You also risk leaking
3780 information about the host to the guest this way.  Instead,
3781 attach a new host device to the guest and swap on that.");
3782
3783   ("swapoff_device", (RErr, [Device "device"], []), 171, [],
3784    [], (* XXX tested by swapon_device *)
3785    "disable swap on device",
3786    "\
3787 This command disables the libguestfs appliance swap
3788 device or partition named C<device>.
3789 See C<guestfs_swapon_device>.");
3790
3791   ("swapon_file", (RErr, [Pathname "file"], []), 172, [],
3792    [InitBasicFS, Always, TestRun (
3793       [["fallocate"; "/swap"; "8388608"];
3794        ["mkswap_file"; "/swap"];
3795        ["swapon_file"; "/swap"];
3796        ["swapoff_file"; "/swap"]])],
3797    "enable swap on file",
3798    "\
3799 This command enables swap to a file.
3800 See C<guestfs_swapon_device> for other notes.");
3801
3802   ("swapoff_file", (RErr, [Pathname "file"], []), 173, [],
3803    [], (* XXX tested by swapon_file *)
3804    "disable swap on file",
3805    "\
3806 This command disables the libguestfs appliance swap on file.");
3807
3808   ("swapon_label", (RErr, [String "label"], []), 174, [],
3809    [InitEmpty, Always, TestRun (
3810       [["part_disk"; "/dev/sdb"; "mbr"];
3811        ["mkswap_L"; "swapit"; "/dev/sdb1"];
3812        ["swapon_label"; "swapit"];
3813        ["swapoff_label"; "swapit"];
3814        ["zero"; "/dev/sdb"];
3815        ["blockdev_rereadpt"; "/dev/sdb"]])],
3816    "enable swap on labeled swap partition",
3817    "\
3818 This command enables swap to a labeled swap partition.
3819 See C<guestfs_swapon_device> for other notes.");
3820
3821   ("swapoff_label", (RErr, [String "label"], []), 175, [],
3822    [], (* XXX tested by swapon_label *)
3823    "disable swap on labeled swap partition",
3824    "\
3825 This command disables the libguestfs appliance swap on
3826 labeled swap partition.");
3827
3828   ("swapon_uuid", (RErr, [String "uuid"], []), 176, [Optional "linuxfsuuid"],
3829    (let uuid = uuidgen () in
3830     [InitEmpty, Always, TestRun (
3831        [["mkswap_U"; uuid; "/dev/sdb"];
3832         ["swapon_uuid"; uuid];
3833         ["swapoff_uuid"; uuid]])]),
3834    "enable swap on swap partition by UUID",
3835    "\
3836 This command enables swap to a swap partition with the given UUID.
3837 See C<guestfs_swapon_device> for other notes.");
3838
3839   ("swapoff_uuid", (RErr, [String "uuid"], []), 177, [Optional "linuxfsuuid"],
3840    [], (* XXX tested by swapon_uuid *)
3841    "disable swap on swap partition by UUID",
3842    "\
3843 This command disables the libguestfs appliance swap partition
3844 with the given UUID.");
3845
3846   ("mkswap_file", (RErr, [Pathname "path"], []), 178, [],
3847    [InitBasicFS, Always, TestRun (
3848       [["fallocate"; "/swap"; "8388608"];
3849        ["mkswap_file"; "/swap"]])],
3850    "create a swap file",
3851    "\
3852 Create a swap file.
3853
3854 This command just writes a swap file signature to an existing
3855 file.  To create the file itself, use something like C<guestfs_fallocate>.");
3856
3857   ("inotify_init", (RErr, [Int "maxevents"], []), 179, [Optional "inotify"],
3858    [InitISOFS, Always, TestRun (
3859       [["inotify_init"; "0"]])],
3860    "create an inotify handle",
3861    "\
3862 This command creates a new inotify handle.
3863 The inotify subsystem can be used to notify events which happen to
3864 objects in the guest filesystem.
3865
3866 C<maxevents> is the maximum number of events which will be
3867 queued up between calls to C<guestfs_inotify_read> or
3868 C<guestfs_inotify_files>.
3869 If this is passed as C<0>, then the kernel (or previously set)
3870 default is used.  For Linux 2.6.29 the default was 16384 events.
3871 Beyond this limit, the kernel throws away events, but records
3872 the fact that it threw them away by setting a flag
3873 C<IN_Q_OVERFLOW> in the returned structure list (see
3874 C<guestfs_inotify_read>).
3875
3876 Before any events are generated, you have to add some
3877 watches to the internal watch list.  See:
3878 C<guestfs_inotify_add_watch>,
3879 C<guestfs_inotify_rm_watch> and
3880 C<guestfs_inotify_watch_all>.
3881
3882 Queued up events should be read periodically by calling
3883 C<guestfs_inotify_read>
3884 (or C<guestfs_inotify_files> which is just a helpful
3885 wrapper around C<guestfs_inotify_read>).  If you don't
3886 read the events out often enough then you risk the internal
3887 queue overflowing.
3888
3889 The handle should be closed after use by calling
3890 C<guestfs_inotify_close>.  This also removes any
3891 watches automatically.
3892
3893 See also L<inotify(7)> for an overview of the inotify interface
3894 as exposed by the Linux kernel, which is roughly what we expose
3895 via libguestfs.  Note that there is one global inotify handle
3896 per libguestfs instance.");
3897
3898   ("inotify_add_watch", (RInt64 "wd", [Pathname "path"; Int "mask"], []), 180, [Optional "inotify"],
3899    [InitBasicFS, Always, TestOutputList (
3900       [["inotify_init"; "0"];
3901        ["inotify_add_watch"; "/"; "1073741823"];
3902        ["touch"; "/a"];
3903        ["touch"; "/b"];
3904        ["inotify_files"]], ["a"; "b"])],
3905    "add an inotify watch",
3906    "\
3907 Watch C<path> for the events listed in C<mask>.
3908
3909 Note that if C<path> is a directory then events within that
3910 directory are watched, but this does I<not> happen recursively
3911 (in subdirectories).
3912
3913 Note for non-C or non-Linux callers: the inotify events are
3914 defined by the Linux kernel ABI and are listed in
3915 C</usr/include/sys/inotify.h>.");
3916
3917   ("inotify_rm_watch", (RErr, [Int(*XXX64*) "wd"], []), 181, [Optional "inotify"],
3918    [],
3919    "remove an inotify watch",
3920    "\
3921 Remove a previously defined inotify watch.
3922 See C<guestfs_inotify_add_watch>.");
3923
3924   ("inotify_read", (RStructList ("events", "inotify_event"), [], []), 182, [Optional "inotify"],
3925    [],
3926    "return list of inotify events",
3927    "\
3928 Return the complete queue of events that have happened
3929 since the previous read call.
3930
3931 If no events have happened, this returns an empty list.
3932
3933 I<Note>: In order to make sure that all events have been
3934 read, you must call this function repeatedly until it
3935 returns an empty list.  The reason is that the call will
3936 read events up to the maximum appliance-to-host message
3937 size and leave remaining events in the queue.");
3938
3939   ("inotify_files", (RStringList "paths", [], []), 183, [Optional "inotify"],
3940    [],
3941    "return list of watched files that had events",
3942    "\
3943 This function is a helpful wrapper around C<guestfs_inotify_read>
3944 which just returns a list of pathnames of objects that were
3945 touched.  The returned pathnames are sorted and deduplicated.");
3946
3947   ("inotify_close", (RErr, [], []), 184, [Optional "inotify"],
3948    [],
3949    "close the inotify handle",
3950    "\
3951 This closes the inotify handle which was previously
3952 opened by inotify_init.  It removes all watches, throws
3953 away any pending events, and deallocates all resources.");
3954
3955   ("setcon", (RErr, [String "context"], []), 185, [Optional "selinux"],
3956    [],
3957    "set SELinux security context",
3958    "\
3959 This sets the SELinux security context of the daemon
3960 to the string C<context>.
3961
3962 See the documentation about SELINUX in L<guestfs(3)>.");
3963
3964   ("getcon", (RString "context", [], []), 186, [Optional "selinux"],
3965    [],
3966    "get SELinux security context",
3967    "\
3968 This gets the SELinux security context of the daemon.
3969
3970 See the documentation about SELINUX in L<guestfs(3)>,
3971 and C<guestfs_setcon>");
3972
3973   ("mkfs_b", (RErr, [String "fstype"; Int "blocksize"; Device "device"], []), 187, [],
3974    [InitEmpty, Always, TestOutput (
3975       [["part_disk"; "/dev/sda"; "mbr"];
3976        ["mkfs_b"; "ext2"; "4096"; "/dev/sda1"];
3977        ["mount_options"; ""; "/dev/sda1"; "/"];
3978        ["write"; "/new"; "new file contents"];
3979        ["cat"; "/new"]], "new file contents");
3980     InitEmpty, Always, TestRun (
3981       [["part_disk"; "/dev/sda"; "mbr"];
3982        ["mkfs_b"; "vfat"; "32768"; "/dev/sda1"]]);
3983     InitEmpty, Always, TestLastFail (
3984       [["part_disk"; "/dev/sda"; "mbr"];
3985        ["mkfs_b"; "vfat"; "32769"; "/dev/sda1"]]);
3986     InitEmpty, Always, TestLastFail (
3987       [["part_disk"; "/dev/sda"; "mbr"];
3988        ["mkfs_b"; "vfat"; "33280"; "/dev/sda1"]]);
3989     InitEmpty, IfAvailable "ntfsprogs", TestRun (
3990       [["part_disk"; "/dev/sda"; "mbr"];
3991        ["mkfs_b"; "ntfs"; "32768"; "/dev/sda1"]])],
3992    "make a filesystem with block size",
3993    "\
3994 This call is similar to C<guestfs_mkfs>, but it allows you to
3995 control the block size of the resulting filesystem.  Supported
3996 block sizes depend on the filesystem type, but typically they
3997 are C<1024>, C<2048> or C<4096> only.
3998
3999 For VFAT and NTFS the C<blocksize> parameter is treated as
4000 the requested cluster size.");
4001
4002   ("mke2journal", (RErr, [Int "blocksize"; Device "device"], []), 188, [],
4003    [InitEmpty, Always, TestOutput (
4004       [["part_init"; "/dev/sda"; "mbr"];
4005        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
4006        ["part_add"; "/dev/sda"; "p"; "204800"; "-64"];
4007        ["mke2journal"; "4096"; "/dev/sda1"];
4008        ["mke2fs_J"; "ext2"; "4096"; "/dev/sda2"; "/dev/sda1"];
4009        ["mount_options"; ""; "/dev/sda2"; "/"];
4010        ["write"; "/new"; "new file contents"];
4011        ["cat"; "/new"]], "new file contents")],
4012    "make ext2/3/4 external journal",
4013    "\
4014 This creates an ext2 external journal on C<device>.  It is equivalent
4015 to the command:
4016
4017  mke2fs -O journal_dev -b blocksize device");
4018
4019   ("mke2journal_L", (RErr, [Int "blocksize"; String "label"; Device "device"], []), 189, [],
4020    [InitEmpty, Always, TestOutput (
4021       [["part_init"; "/dev/sda"; "mbr"];
4022        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
4023        ["part_add"; "/dev/sda"; "p"; "204800"; "-64"];
4024        ["mke2journal_L"; "4096"; "JOURNAL"; "/dev/sda1"];
4025        ["mke2fs_JL"; "ext2"; "4096"; "/dev/sda2"; "JOURNAL"];
4026        ["mount_options"; ""; "/dev/sda2"; "/"];
4027        ["write"; "/new"; "new file contents"];
4028        ["cat"; "/new"]], "new file contents")],
4029    "make ext2/3/4 external journal with label",
4030    "\
4031 This creates an ext2 external journal on C<device> with label C<label>.");
4032
4033   ("mke2journal_U", (RErr, [Int "blocksize"; String "uuid"; Device "device"], []), 190, [Optional "linuxfsuuid"],
4034    (let uuid = uuidgen () in
4035     [InitEmpty, Always, TestOutput (
4036        [["part_init"; "/dev/sda"; "mbr"];
4037         ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
4038         ["part_add"; "/dev/sda"; "p"; "204800"; "-64"];
4039         ["mke2journal_U"; "4096"; uuid; "/dev/sda1"];
4040         ["mke2fs_JU"; "ext2"; "4096"; "/dev/sda2"; uuid];
4041         ["mount_options"; ""; "/dev/sda2"; "/"];
4042         ["write"; "/new"; "new file contents"];
4043         ["cat"; "/new"]], "new file contents")]),
4044    "make ext2/3/4 external journal with UUID",
4045    "\
4046 This creates an ext2 external journal on C<device> with UUID C<uuid>.");
4047
4048   ("mke2fs_J", (RErr, [String "fstype"; Int "blocksize"; Device "device"; Device "journal"], []), 191, [],
4049    [],
4050    "make ext2/3/4 filesystem with external journal",
4051    "\
4052 This creates an ext2/3/4 filesystem on C<device> with
4053 an external journal on C<journal>.  It is equivalent
4054 to the command:
4055
4056  mke2fs -t fstype -b blocksize -J device=<journal> <device>
4057
4058 See also C<guestfs_mke2journal>.");
4059
4060   ("mke2fs_JL", (RErr, [String "fstype"; Int "blocksize"; Device "device"; String "label"], []), 192, [],
4061    [],
4062    "make ext2/3/4 filesystem with external journal",
4063    "\
4064 This creates an ext2/3/4 filesystem on C<device> with
4065 an external journal on the journal labeled C<label>.
4066
4067 See also C<guestfs_mke2journal_L>.");
4068
4069   ("mke2fs_JU", (RErr, [String "fstype"; Int "blocksize"; Device "device"; String "uuid"], []), 193, [Optional "linuxfsuuid"],
4070    [],
4071    "make ext2/3/4 filesystem with external journal",
4072    "\
4073 This creates an ext2/3/4 filesystem on C<device> with
4074 an external journal on the journal with UUID C<uuid>.
4075
4076 See also C<guestfs_mke2journal_U>.");
4077
4078   ("modprobe", (RErr, [String "modulename"], []), 194, [Optional "linuxmodules"],
4079    [InitNone, Always, TestRun [["modprobe"; "fat"]]],
4080    "load a kernel module",
4081    "\
4082 This loads a kernel module in the appliance.
4083
4084 The kernel module must have been whitelisted when libguestfs
4085 was built (see C<appliance/kmod.whitelist.in> in the source).");
4086
4087   ("echo_daemon", (RString "output", [StringList "words"], []), 195, [],
4088    [InitNone, Always, TestOutput (
4089       [["echo_daemon"; "This is a test"]], "This is a test"
4090     )],
4091    "echo arguments back to the client",
4092    "\
4093 This command concatenates the list of C<words> passed with single spaces
4094 between them and returns the resulting string.
4095
4096 You can use this command to test the connection through to the daemon.
4097
4098 See also C<guestfs_ping_daemon>.");
4099
4100   ("find0", (RErr, [Pathname "directory"; FileOut "files"], []), 196, [],
4101    [], (* There is a regression test for this. *)
4102    "find all files and directories, returning NUL-separated list",
4103    "\
4104 This command lists out all files and directories, recursively,
4105 starting at C<directory>, placing the resulting list in the
4106 external file called C<files>.
4107
4108 This command works the same way as C<guestfs_find> with the
4109 following exceptions:
4110
4111 =over 4
4112
4113 =item *
4114
4115 The resulting list is written to an external file.
4116
4117 =item *
4118
4119 Items (filenames) in the result are separated
4120 by C<\\0> characters.  See L<find(1)> option I<-print0>.
4121
4122 =item *
4123
4124 This command is not limited in the number of names that it
4125 can return.
4126
4127 =item *
4128
4129 The result list is not sorted.
4130
4131 =back");
4132
4133   ("case_sensitive_path", (RString "rpath", [Pathname "path"], []), 197, [],
4134    [InitISOFS, Always, TestOutput (
4135       [["case_sensitive_path"; "/DIRECTORY"]], "/directory");
4136     InitISOFS, Always, TestOutput (
4137       [["case_sensitive_path"; "/DIRECTORY/"]], "/directory");
4138     InitISOFS, Always, TestOutput (
4139       [["case_sensitive_path"; "/Known-1"]], "/known-1");
4140     InitISOFS, Always, TestLastFail (
4141       [["case_sensitive_path"; "/Known-1/"]]);
4142     InitBasicFS, Always, TestOutput (
4143       [["mkdir"; "/a"];
4144        ["mkdir"; "/a/bbb"];
4145        ["touch"; "/a/bbb/c"];
4146        ["case_sensitive_path"; "/A/bbB/C"]], "/a/bbb/c");
4147     InitBasicFS, Always, TestOutput (
4148       [["mkdir"; "/a"];
4149        ["mkdir"; "/a/bbb"];
4150        ["touch"; "/a/bbb/c"];
4151        ["case_sensitive_path"; "/A////bbB/C"]], "/a/bbb/c");
4152     InitBasicFS, Always, TestLastFail (
4153       [["mkdir"; "/a"];
4154        ["mkdir"; "/a/bbb"];
4155        ["touch"; "/a/bbb/c"];
4156        ["case_sensitive_path"; "/A/bbb/../bbb/C"]])],
4157    "return true path on case-insensitive filesystem",
4158    "\
4159 This can be used to resolve case insensitive paths on
4160 a filesystem which is case sensitive.  The use case is
4161 to resolve paths which you have read from Windows configuration
4162 files or the Windows Registry, to the true path.
4163
4164 The command handles a peculiarity of the Linux ntfs-3g
4165 filesystem driver (and probably others), which is that although
4166 the underlying filesystem is case-insensitive, the driver
4167 exports the filesystem to Linux as case-sensitive.
4168
4169 One consequence of this is that special directories such
4170 as C<c:\\windows> may appear as C</WINDOWS> or C</windows>
4171 (or other things) depending on the precise details of how
4172 they were created.  In Windows itself this would not be
4173 a problem.
4174
4175 Bug or feature?  You decide:
4176 L<http://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1>
4177
4178 This function resolves the true case of each element in the
4179 path and returns the case-sensitive path.
4180
4181 Thus C<guestfs_case_sensitive_path> (\"/Windows/System32\")
4182 might return C<\"/WINDOWS/system32\"> (the exact return value
4183 would depend on details of how the directories were originally
4184 created under Windows).
4185
4186 I<Note>:
4187 This function does not handle drive names, backslashes etc.