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