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