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