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