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