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