inspect: "centos" and "scientificlinux" are now separate distros.
[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 \"centos\"
795
796 CentOS.
797
798 =item \"debian\"
799
800 Debian.
801
802 =item \"fedora\"
803
804 Fedora.
805
806 =item \"gentoo\"
807
808 Gentoo.
809
810 =item \"linuxmint\"
811
812 Linux Mint.
813
814 =item \"mandriva\"
815
816 Mandriva.
817
818 =item \"meego\"
819
820 MeeGo.
821
822 =item \"pardus\"
823
824 Pardus.
825
826 =item \"redhat-based\"
827
828 Some Red Hat-derived distro.
829
830 =item \"rhel\"
831
832 Red Hat Enterprise Linux.
833
834 =item \"scientificlinux\"
835
836 Scientific Linux.
837
838 =item \"slackware\"
839
840 Slackware.
841
842 =item \"ubuntu\"
843
844 Ubuntu.
845
846 =item \"unknown\"
847
848 The distro could not be determined.
849
850 =item \"windows\"
851
852 Windows does not have distributions.  This string is
853 returned if the OS type is Windows.
854
855 =back
856
857 Future versions of libguestfs may return other strings here.
858 The caller should be prepared to handle any string.
859
860 Please read L<guestfs(3)/INSPECTION> for more details.");
861
862   ("inspect_get_major_version", (RInt "major", [Device "root"], []), -1, [],
863    [],
864    "get major version of inspected operating system",
865    "\
866 This function should only be called with a root device string
867 as returned by C<guestfs_inspect_os>.
868
869 This returns the major version number of the inspected operating
870 system.
871
872 Windows uses a consistent versioning scheme which is I<not>
873 reflected in the popular public names used by the operating system.
874 Notably the operating system known as \"Windows 7\" is really
875 version 6.1 (ie. major = 6, minor = 1).  You can find out the
876 real versions corresponding to releases of Windows by consulting
877 Wikipedia or MSDN.
878
879 If the version could not be determined, then C<0> is returned.
880
881 Please read L<guestfs(3)/INSPECTION> for more details.");
882
883   ("inspect_get_minor_version", (RInt "minor", [Device "root"], []), -1, [],
884    [],
885    "get minor version of inspected operating system",
886    "\
887 This function should only be called with a root device string
888 as returned by C<guestfs_inspect_os>.
889
890 This returns the minor version number of the inspected operating
891 system.
892
893 If the version could not be determined, then C<0> is returned.
894
895 Please read L<guestfs(3)/INSPECTION> for more details.
896 See also C<guestfs_inspect_get_major_version>.");
897
898   ("inspect_get_product_name", (RString "product", [Device "root"], []), -1, [],
899    [],
900    "get product name of inspected operating system",
901    "\
902 This function should only be called with a root device string
903 as returned by C<guestfs_inspect_os>.
904
905 This returns the product name of the inspected operating
906 system.  The product name is generally some freeform string
907 which can be displayed to the user, but should not be
908 parsed by programs.
909
910 If the product name could not be determined, then the
911 string C<unknown> is returned.
912
913 Please read L<guestfs(3)/INSPECTION> for more details.");
914
915   ("inspect_get_mountpoints", (RHashtable "mountpoints", [Device "root"], []), -1, [],
916    [],
917    "get mountpoints of inspected operating system",
918    "\
919 This function should only be called with a root device string
920 as returned by C<guestfs_inspect_os>.
921
922 This returns a hash of where we think the filesystems
923 associated with this operating system should be mounted.
924 Callers should note that this is at best an educated guess
925 made by reading configuration files such as C</etc/fstab>.
926 I<In particular note> that this may return filesystems
927 which are non-existent or not mountable and callers should
928 be prepared to handle or ignore failures if they try to
929 mount them.
930
931 Each element in the returned hashtable has a key which
932 is the path of the mountpoint (eg. C</boot>) and a value
933 which is the filesystem that would be mounted there
934 (eg. C</dev/sda1>).
935
936 Non-mounted devices such as swap devices are I<not>
937 returned in this list.
938
939 For operating systems like Windows which still use drive
940 letters, this call will only return an entry for the first
941 drive \"mounted on\" C</>.  For information about the
942 mapping of drive letters to partitions, see
943 C<guestfs_inspect_get_drive_mappings>.
944
945 Please read L<guestfs(3)/INSPECTION> for more details.
946 See also C<guestfs_inspect_get_filesystems>.");
947
948   ("inspect_get_filesystems", (RStringList "filesystems", [Device "root"], []), -1, [],
949    [],
950    "get filesystems associated with inspected operating system",
951    "\
952 This function should only be called with a root device string
953 as returned by C<guestfs_inspect_os>.
954
955 This returns a list of all the filesystems that we think
956 are associated with this operating system.  This includes
957 the root filesystem, other ordinary filesystems, and
958 non-mounted devices like swap partitions.
959
960 In the case of a multi-boot virtual machine, it is possible
961 for a filesystem to be shared between operating systems.
962
963 Please read L<guestfs(3)/INSPECTION> for more details.
964 See also C<guestfs_inspect_get_mountpoints>.");
965
966   ("set_network", (RErr, [Bool "network"], []), -1, [FishAlias "network"],
967    [],
968    "set enable network flag",
969    "\
970 If C<network> is true, then the network is enabled in the
971 libguestfs appliance.  The default is false.
972
973 This affects whether commands are able to access the network
974 (see L<guestfs(3)/RUNNING COMMANDS>).
975
976 You must call this before calling C<guestfs_launch>, otherwise
977 it has no effect.");
978
979   ("get_network", (RBool "network", [], []), -1, [],
980    [],
981    "get enable network flag",
982    "\
983 This returns the enable network flag.");
984
985   ("list_filesystems", (RHashtable "fses", [], []), -1, [],
986    [],
987    "list filesystems",
988    "\
989 This inspection command looks for filesystems on partitions,
990 block devices and logical volumes, returning a list of devices
991 containing filesystems and their type.
992
993 The return value is a hash, where the keys are the devices
994 containing filesystems, and the values are the filesystem types.
995 For example:
996
997  \"/dev/sda1\" => \"ntfs\"
998  \"/dev/sda2\" => \"ext2\"
999  \"/dev/vg_guest/lv_root\" => \"ext4\"
1000  \"/dev/vg_guest/lv_swap\" => \"swap\"
1001
1002 The value can have the special value \"unknown\", meaning the
1003 content of the device is undetermined or empty.
1004 \"swap\" means a Linux swap partition.
1005
1006 This command runs other libguestfs commands, which might include
1007 C<guestfs_mount> and C<guestfs_umount>, and therefore you should
1008 use this soon after launch and only when nothing is mounted.
1009
1010 Not all of the filesystems returned will be mountable.  In
1011 particular, swap partitions are returned in the list.  Also
1012 this command does not check that each filesystem
1013 found is valid and mountable, and some filesystems might
1014 be mountable but require special options.  Filesystems may
1015 not all belong to a single logical operating system
1016 (use C<guestfs_inspect_os> to look for OSes).");
1017
1018   ("add_drive_opts", (RErr, [String "filename"], [Bool "readonly"; String "format"; String "iface"]), -1, [FishAlias "add"],
1019    [],
1020    "add an image to examine or modify",
1021    "\
1022 This function adds a virtual machine disk image C<filename> to
1023 libguestfs.  The first time you call this function, the disk
1024 appears as C</dev/sda>, the second time as C</dev/sdb>, and
1025 so on.
1026
1027 You don't necessarily need to be root when using libguestfs.  However
1028 you obviously do need sufficient permissions to access the filename
1029 for whatever operations you want to perform (ie. read access if you
1030 just want to read the image or write access if you want to modify the
1031 image).
1032
1033 This call checks that C<filename> exists.
1034
1035 The optional arguments are:
1036
1037 =over 4
1038
1039 =item C<readonly>
1040
1041 If true then the image is treated as read-only.  Writes are still
1042 allowed, but they are stored in a temporary snapshot overlay which
1043 is discarded at the end.  The disk that you add is not modified.
1044
1045 =item C<format>
1046
1047 This forces the image format.  If you omit this (or use C<guestfs_add_drive>
1048 or C<guestfs_add_drive_ro>) then the format is automatically detected.
1049 Possible formats include C<raw> and C<qcow2>.
1050
1051 Automatic detection of the format opens you up to a potential
1052 security hole when dealing with untrusted raw-format images.
1053 See CVE-2010-3851 and RHBZ#642934.  Specifying the format closes
1054 this security hole.
1055
1056 =item C<iface>
1057
1058 This rarely-used option lets you emulate the behaviour of the
1059 deprecated C<guestfs_add_drive_with_if> call (q.v.)
1060
1061 =back");
1062
1063   ("inspect_get_windows_systemroot", (RString "systemroot", [Device "root"], []), -1, [],
1064    [],
1065    "get Windows systemroot of inspected operating system",
1066    "\
1067 This function should only be called with a root device string
1068 as returned by C<guestfs_inspect_os>.
1069
1070 This returns the Windows systemroot of the inspected guest.
1071 The systemroot is a directory path such as C</WINDOWS>.
1072
1073 This call assumes that the guest is Windows and that the
1074 systemroot could be determined by inspection.  If this is not
1075 the case then an error is returned.
1076
1077 Please read L<guestfs(3)/INSPECTION> for more details.");
1078
1079   ("inspect_get_roots", (RStringList "roots", [], []), -1, [],
1080    [],
1081    "return list of operating systems found by last inspection",
1082    "\
1083 This function is a convenient way to get the list of root
1084 devices, as returned from a previous call to C<guestfs_inspect_os>,
1085 but without redoing the whole inspection process.
1086
1087 This returns an empty list if either no root devices were
1088 found or the caller has not called C<guestfs_inspect_os>.
1089
1090 Please read L<guestfs(3)/INSPECTION> for more details.");
1091
1092   ("debug_cmdline", (RStringList "cmdline", [], []), -1, [NotInDocs],
1093    [],
1094    "debug the QEMU command line (internal use only)",
1095    "\
1096 This returns the internal QEMU command line.  'debug' commands are
1097 not part of the formal API and can be removed or changed at any time.");
1098
1099   ("add_domain", (RInt "nrdisks", [String "dom"], [String "libvirturi"; Bool "readonly"; String "iface"; Bool "live"]), -1, [FishAlias "domain"],
1100    [],
1101    "add the disk(s) from a named libvirt domain",
1102    "\
1103 This function adds the disk(s) attached to the named libvirt
1104 domain C<dom>.  It works by connecting to libvirt, requesting
1105 the domain and domain XML from libvirt, parsing it for disks,
1106 and calling C<guestfs_add_drive_opts> on each one.
1107
1108 The number of disks added is returned.  This operation is atomic:
1109 if an error is returned, then no disks are added.
1110
1111 This function does some minimal checks to make sure the libvirt
1112 domain is not running (unless C<readonly> is true).  In a future
1113 version we will try to acquire the libvirt lock on each disk.
1114
1115 Disks must be accessible locally.  This often means that adding disks
1116 from a remote libvirt connection (see L<http://libvirt.org/remote.html>)
1117 will fail unless those disks are accessible via the same device path
1118 locally too.
1119
1120 The optional C<libvirturi> parameter sets the libvirt URI
1121 (see L<http://libvirt.org/uri.html>).  If this is not set then
1122 we connect to the default libvirt URI (or one set through an
1123 environment variable, see the libvirt documentation for full
1124 details).
1125
1126 The optional C<live> flag controls whether this call will try
1127 to connect to a running virtual machine C<guestfsd> process if
1128 it sees a suitable E<lt>channelE<gt> element in the libvirt
1129 XML definition.  The default (if the flag is omitted) is never
1130 to try.  See L<guestfs(3)/ATTACHING TO RUNNING DAEMONS> for more
1131 information.
1132
1133 The other optional parameters are passed directly through to
1134 C<guestfs_add_drive_opts>.");
1135
1136 (*
1137 This interface is not quite baked yet. -- RWMJ 2010-11-11
1138   ("add_libvirt_dom", (RInt "nrdisks", [Pointer ("virDomainPtr", "dom")], [Bool "readonly"; String "iface"; Bool "live"]), -1, [NotInFish],
1139    [],
1140    "add the disk(s) from a libvirt domain",
1141    "\
1142 This function adds the disk(s) attached to the libvirt domain C<dom>.
1143 It works by requesting the domain XML from libvirt, parsing it for
1144 disks, and calling C<guestfs_add_drive_opts> on each one.
1145
1146 In the C API we declare C<void *dom>, but really it has type
1147 C<virDomainPtr dom>.  This is so we don't need E<lt>libvirt.hE<gt>.
1148
1149 The number of disks added is returned.  This operation is atomic:
1150 if an error is returned, then no disks are added.
1151
1152 This function does some minimal checks to make sure the libvirt
1153 domain is not running (unless C<readonly> is true).  In a future
1154 version we will try to acquire the libvirt lock on each disk.
1155
1156 Disks must be accessible locally.  This often means that adding disks
1157 from a remote libvirt connection (see L<http://libvirt.org/remote.html>)
1158 will fail unless those disks are accessible via the same device path
1159 locally too.
1160
1161 The optional C<live> flag controls whether this call will try
1162 to connect to a running virtual machine C<guestfsd> process if
1163 it sees a suitable E<lt>channelE<gt> element in the libvirt
1164 XML definition.  The default (if the flag is omitted) is never
1165 to try.  See L<guestfs(3)/ATTACHING TO RUNNING DAEMONS> for more
1166 information.
1167
1168 The other optional parameters are passed directly through to
1169 C<guestfs_add_drive_opts>.");
1170 *)
1171
1172   ("inspect_get_package_format", (RString "packageformat", [Device "root"], []), -1, [],
1173    [],
1174    "get package format used by the operating system",
1175    "\
1176 This function should only be called with a root device string
1177 as returned by C<guestfs_inspect_os>.
1178
1179 This function and C<guestfs_inspect_get_package_management> return
1180 the package format and package management tool used by the
1181 inspected operating system.  For example for Fedora these
1182 functions would return C<rpm> (package format) and
1183 C<yum> (package management).
1184
1185 This returns the string C<unknown> if we could not determine the
1186 package format I<or> if the operating system does not have
1187 a real packaging system (eg. Windows).
1188
1189 Possible strings include: C<rpm>, C<deb>, C<ebuild>, C<pisi>, C<pacman>.
1190 Future versions of libguestfs may return other strings.
1191
1192 Please read L<guestfs(3)/INSPECTION> for more details.");
1193
1194   ("inspect_get_package_management", (RString "packagemanagement", [Device "root"], []), -1, [],
1195    [],
1196    "get package management tool used by the operating system",
1197    "\
1198 This function should only be called with a root device string
1199 as returned by C<guestfs_inspect_os>.
1200
1201 C<guestfs_inspect_get_package_format> and this function return
1202 the package format and package management tool used by the
1203 inspected operating system.  For example for Fedora these
1204 functions would return C<rpm> (package format) and
1205 C<yum> (package management).
1206
1207 This returns the string C<unknown> if we could not determine the
1208 package management tool I<or> if the operating system does not have
1209 a real packaging system (eg. Windows).
1210
1211 Possible strings include: C<yum>, C<up2date>,
1212 C<apt> (for all Debian derivatives),
1213 C<portage>, C<pisi>, C<pacman>, C<urpmi>.
1214 Future versions of libguestfs may return other strings.
1215
1216 Please read L<guestfs(3)/INSPECTION> for more details.");
1217
1218   ("inspect_list_applications", (RStructList ("applications", "application"), [Device "root"], []), -1, [],
1219    [],
1220    "get list of applications installed in the operating system",
1221    "\
1222 This function should only be called with a root device string
1223 as returned by C<guestfs_inspect_os>.
1224
1225 Return the list of applications installed in the operating system.
1226
1227 I<Note:> This call works differently from other parts of the
1228 inspection API.  You have to call C<guestfs_inspect_os>, then
1229 C<guestfs_inspect_get_mountpoints>, then mount up the disks,
1230 before calling this.  Listing applications is a significantly
1231 more difficult operation which requires access to the full
1232 filesystem.  Also note that unlike the other
1233 C<guestfs_inspect_get_*> calls which are just returning
1234 data cached in the libguestfs handle, this call actually reads
1235 parts of the mounted filesystems during the call.
1236
1237 This returns an empty list if the inspection code was not able
1238 to determine the list of applications.
1239
1240 The application structure contains the following fields:
1241
1242 =over 4
1243
1244 =item C<app_name>
1245
1246 The name of the application.  For Red Hat-derived and Debian-derived
1247 Linux guests, this is the package name.
1248
1249 =item C<app_display_name>
1250
1251 The display name of the application, sometimes localized to the
1252 install language of the guest operating system.
1253
1254 If unavailable this is returned as an empty string C<\"\">.
1255 Callers needing to display something can use C<app_name> instead.
1256
1257 =item C<app_epoch>
1258
1259 For package managers which use epochs, this contains the epoch of
1260 the package (an integer).  If unavailable, this is returned as C<0>.
1261
1262 =item C<app_version>
1263
1264 The version string of the application or package.  If unavailable
1265 this is returned as an empty string C<\"\">.
1266
1267 =item C<app_release>
1268
1269 The release string of the application or package, for package
1270 managers that use this.  If unavailable this is returned as an
1271 empty string C<\"\">.
1272
1273 =item C<app_install_path>
1274
1275 The installation path of the application (on operating systems
1276 such as Windows which use installation paths).  This path is
1277 in the format used by the guest operating system, it is not
1278 a libguestfs path.
1279
1280 If unavailable this is returned as an empty string C<\"\">.
1281
1282 =item C<app_trans_path>
1283
1284 The install path translated into a libguestfs path.
1285 If unavailable this is returned as an empty string C<\"\">.
1286
1287 =item C<app_publisher>
1288
1289 The name of the publisher of the application, for package
1290 managers that use this.  If unavailable this is returned
1291 as an empty string C<\"\">.
1292
1293 =item C<app_url>
1294
1295 The URL (eg. upstream URL) of the application.
1296 If unavailable this is returned as an empty string C<\"\">.
1297
1298 =item C<app_source_package>
1299
1300 For packaging systems which support this, the name of the source
1301 package.  If unavailable this is returned as an empty string C<\"\">.
1302
1303 =item C<app_summary>
1304
1305 A short (usually one line) description of the application or package.
1306 If unavailable this is returned as an empty string C<\"\">.
1307
1308 =item C<app_description>
1309
1310 A longer description of the application or package.
1311 If unavailable this is returned as an empty string C<\"\">.
1312
1313 =back
1314
1315 Please read L<guestfs(3)/INSPECTION> for more details.");
1316
1317   ("inspect_get_hostname", (RString "hostname", [Device "root"], []), -1, [],
1318    [],
1319    "get hostname of the operating system",
1320    "\
1321 This function should only be called with a root device string
1322 as returned by C<guestfs_inspect_os>.
1323
1324 This function returns the hostname of the operating system
1325 as found by inspection of the guest's configuration files.
1326
1327 If the hostname could not be determined, then the
1328 string C<unknown> is returned.
1329
1330 Please read L<guestfs(3)/INSPECTION> for more details.");
1331
1332   ("inspect_get_format", (RString "format", [Device "root"], []), -1, [],
1333    [],
1334    "get format of inspected operating system",
1335    "\
1336 This function should only be called with a root device string
1337 as returned by C<guestfs_inspect_os>.
1338
1339 This returns the format of the inspected operating system.  You
1340 can use it to detect install images, live CDs and similar.
1341
1342 Currently defined formats are:
1343
1344 =over 4
1345
1346 =item \"installed\"
1347
1348 This is an installed operating system.
1349
1350 =item \"installer\"
1351
1352 The disk image being inspected is not an installed operating system,
1353 but a I<bootable> install disk, live CD, or similar.
1354
1355 =item \"unknown\"
1356
1357 The format of this disk image is not known.
1358
1359 =back
1360
1361 Future versions of libguestfs may return other strings here.
1362 The caller should be prepared to handle any string.
1363
1364 Please read L<guestfs(3)/INSPECTION> for more details.");
1365
1366   ("inspect_is_live", (RBool "live", [Device "root"], []), -1, [],
1367    [],
1368    "get live flag for install disk",
1369    "\
1370 This function should only be called with a root device string
1371 as returned by C<guestfs_inspect_os>.
1372
1373 If C<guestfs_inspect_get_format> returns C<installer> (this
1374 is an install disk), then this returns true if a live image
1375 was detected on the disk.
1376
1377 Please read L<guestfs(3)/INSPECTION> for more details.");
1378
1379   ("inspect_is_netinst", (RBool "netinst", [Device "root"], []), -1, [],
1380    [],
1381    "get netinst (network installer) flag for install disk",
1382    "\
1383 This function should only be called with a root device string
1384 as returned by C<guestfs_inspect_os>.
1385
1386 If C<guestfs_inspect_get_format> returns C<installer> (this
1387 is an install disk), then this returns true if the disk is
1388 a network installer, ie. not a self-contained install CD but
1389 one which is likely to require network access to complete
1390 the install.
1391
1392 Please read L<guestfs(3)/INSPECTION> for more details.");
1393
1394   ("inspect_is_multipart", (RBool "multipart", [Device "root"], []), -1, [],
1395    [],
1396    "get multipart flag for install disk",
1397    "\
1398 This function should only be called with a root device string
1399 as returned by C<guestfs_inspect_os>.
1400
1401 If C<guestfs_inspect_get_format> returns C<installer> (this
1402 is an install disk), then this returns true if the disk is
1403 part of a set.
1404
1405 Please read L<guestfs(3)/INSPECTION> for more details.");
1406
1407   ("set_attach_method", (RErr, [String "attachmethod"], []), -1, [FishAlias "attach-method"],
1408    [],
1409    "set the attach method",
1410    "\
1411 Set the method that libguestfs uses to connect to the back end
1412 guestfsd daemon.  Possible methods are:
1413
1414 =over 4
1415
1416 =item C<appliance>
1417
1418 Launch an appliance and connect to it.  This is the ordinary method
1419 and the default.
1420
1421 =item C<unix:I<path>>
1422
1423 Connect to the Unix domain socket I<path>.
1424
1425 This method lets you connect to an existing daemon or (using
1426 virtio-serial) to a live guest.  For more information, see
1427 L<guestfs(3)/ATTACHING TO RUNNING DAEMONS>.
1428
1429 =back");
1430
1431   ("get_attach_method", (RString "attachmethod", [], []), -1, [],
1432    [InitNone, Always, TestOutput (
1433       [["get_attach_method"]], "appliance")],
1434    "get the attach method",
1435    "\
1436 Return the current attach method.  See C<guestfs_set_attach_method>.");
1437
1438   ("inspect_get_product_variant", (RString "variant", [Device "root"], []), -1, [],
1439    [],
1440    "get product variant of inspected operating system",
1441    "\
1442 This function should only be called with a root device string
1443 as returned by C<guestfs_inspect_os>.
1444
1445 This returns the product variant of the inspected operating
1446 system.
1447
1448 For Windows guests, this returns the contents of the Registry key
1449 C<HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion>
1450 C<InstallationType> which is usually a string such as
1451 C<Client> or C<Server> (other values are possible).  This
1452 can be used to distinguish consumer and enterprise versions
1453 of Windows that have the same version number (for example,
1454 Windows 7 and Windows 2008 Server are both version 6.1,
1455 but the former is C<Client> and the latter is C<Server>).
1456
1457 For enterprise Linux guests, in future we intend this to return
1458 the product variant such as C<Desktop>, C<Server> and so on.  But
1459 this is not implemented at present.
1460
1461 If the product variant could not be determined, then the
1462 string C<unknown> is returned.
1463
1464 Please read L<guestfs(3)/INSPECTION> for more details.
1465 See also C<guestfs_inspect_get_product_name>,
1466 C<guestfs_inspect_get_major_version>.");
1467
1468   ("inspect_get_windows_current_control_set", (RString "controlset", [Device "root"], []), -1, [],
1469    [],
1470    "get Windows CurrentControlSet of inspected operating system",
1471    "\
1472 This function should only be called with a root device string
1473 as returned by C<guestfs_inspect_os>.
1474
1475 This returns the Windows CurrentControlSet of the inspected guest.
1476 The CurrentControlSet is a registry key name such as C<ControlSet001>.
1477
1478 This call assumes that the guest is Windows and that the
1479 Registry could be examined by inspection.  If this is not
1480 the case then an error is returned.
1481
1482 Please read L<guestfs(3)/INSPECTION> for more details.");
1483
1484   ("inspect_get_drive_mappings", (RHashtable "drives", [Device "root"], []), -1, [],
1485    [],
1486    "get drive letter mappings",
1487    "\
1488 This function should only be called with a root device string
1489 as returned by C<guestfs_inspect_os>.
1490
1491 This call is useful for Windows which uses a primitive system
1492 of assigning drive letters (like \"C:\") to partitions.
1493 This inspection API examines the Windows Registry to find out
1494 how disks/partitions are mapped to drive letters, and returns
1495 a hash table as in the example below:
1496
1497  C      =>     /dev/vda2
1498  E      =>     /dev/vdb1
1499  F      =>     /dev/vdc1
1500
1501 Note that keys are drive letters.  For Windows, the key is
1502 case insensitive and just contains the drive letter, without
1503 the customary colon separator character.
1504
1505 In future we may support other operating systems that also used drive
1506 letters, but the keys for those might not be case insensitive
1507 and might be longer than 1 character.  For example in OS-9,
1508 hard drives were named C<h0>, C<h1> etc.
1509
1510 For Windows guests, currently only hard drive mappings are
1511 returned.  Removable disks (eg. DVD-ROMs) are ignored.
1512
1513 For guests that do not use drive mappings, or if the drive mappings
1514 could not be determined, this returns an empty hash table.
1515
1516 Please read L<guestfs(3)/INSPECTION> for more details.
1517 See also C<guestfs_inspect_get_mountpoints>,
1518 C<guestfs_inspect_get_filesystems>.");
1519
1520 ]
1521
1522 (* daemon_functions are any functions which cause some action
1523  * to take place in the daemon.
1524  *)
1525
1526 let daemon_functions = [
1527   ("mount", (RErr, [Device "device"; String "mountpoint"], []), 1, [],
1528    [InitEmpty, Always, TestOutput (
1529       [["part_disk"; "/dev/sda"; "mbr"];
1530        ["mkfs"; "ext2"; "/dev/sda1"];
1531        ["mount"; "/dev/sda1"; "/"];
1532        ["write"; "/new"; "new file contents"];
1533        ["cat"; "/new"]], "new file contents")],
1534    "mount a guest disk at a position in the filesystem",
1535    "\
1536 Mount a guest disk at a position in the filesystem.  Block devices
1537 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
1538 the guest.  If those block devices contain partitions, they will have
1539 the usual names (eg. C</dev/sda1>).  Also LVM C</dev/VG/LV>-style
1540 names can be used.
1541
1542 The rules are the same as for L<mount(2)>:  A filesystem must
1543 first be mounted on C</> before others can be mounted.  Other
1544 filesystems can only be mounted on directories which already
1545 exist.
1546
1547 The mounted filesystem is writable, if we have sufficient permissions
1548 on the underlying device.
1549
1550 B<Important note:>
1551 When you use this call, the filesystem options C<sync> and C<noatime>
1552 are set implicitly.  This was originally done because we thought it
1553 would improve reliability, but it turns out that I<-o sync> has a
1554 very large negative performance impact and negligible effect on
1555 reliability.  Therefore we recommend that you avoid using
1556 C<guestfs_mount> in any code that needs performance, and instead
1557 use C<guestfs_mount_options> (use an empty string for the first
1558 parameter if you don't want any options).");
1559
1560   ("sync", (RErr, [], []), 2, [],
1561    [ InitEmpty, Always, TestRun [["sync"]]],
1562    "sync disks, writes are flushed through to the disk image",
1563    "\
1564 This syncs the disk, so that any writes are flushed through to the
1565 underlying disk image.
1566
1567 You should always call this if you have modified a disk image, before
1568 closing the handle.");
1569
1570   ("touch", (RErr, [Pathname "path"], []), 3, [],
1571    [InitScratchFS, Always, TestOutputTrue (
1572       [["touch"; "/touch"];
1573        ["exists"; "/touch"]])],
1574    "update file timestamps or create a new file",
1575    "\
1576 Touch acts like the L<touch(1)> command.  It can be used to
1577 update the timestamps on a file, or, if the file does not exist,
1578 to create a new zero-length file.
1579
1580 This command only works on regular files, and will fail on other
1581 file types such as directories, symbolic links, block special etc.");
1582
1583   ("cat", (RString "content", [Pathname "path"], []), 4, [ProtocolLimitWarning],
1584    [InitISOFS, Always, TestOutput (
1585       [["cat"; "/known-2"]], "abcdef\n")],
1586    "list the contents of a file",
1587    "\
1588 Return the contents of the file named C<path>.
1589
1590 Note that this function cannot correctly handle binary files
1591 (specifically, files containing C<\\0> character which is treated
1592 as end of string).  For those you need to use the C<guestfs_read_file>
1593 or C<guestfs_download> functions which have a more complex interface.");
1594
1595   ("ll", (RString "listing", [Pathname "directory"], []), 5, [],
1596    [], (* XXX Tricky to test because it depends on the exact format
1597         * of the 'ls -l' command, which changes between F10 and F11.
1598         *)
1599    "list the files in a directory (long format)",
1600    "\
1601 List the files in C<directory> (relative to the root directory,
1602 there is no cwd) in the format of 'ls -la'.
1603
1604 This command is mostly useful for interactive sessions.  It
1605 is I<not> intended that you try to parse the output string.");
1606
1607   ("ls", (RStringList "listing", [Pathname "directory"], []), 6, [],
1608    [InitScratchFS, Always, TestOutputList (
1609       [["mkdir"; "/ls"];
1610        ["touch"; "/ls/new"];
1611        ["touch"; "/ls/newer"];
1612        ["touch"; "/ls/newest"];
1613        ["ls"; "/ls"]], ["new"; "newer"; "newest"])],
1614    "list the files in a directory",
1615    "\
1616 List the files in C<directory> (relative to the root directory,
1617 there is no cwd).  The '.' and '..' entries are not returned, but
1618 hidden files are shown.
1619
1620 This command is mostly useful for interactive sessions.  Programs
1621 should probably use C<guestfs_readdir> instead.");
1622
1623   ("list_devices", (RStringList "devices", [], []), 7, [],
1624    [InitEmpty, Always, TestOutputListOfDevices (
1625       [["list_devices"]], ["/dev/sda"; "/dev/sdb"; "/dev/sdc"; "/dev/sdd"])],
1626    "list the block devices",
1627    "\
1628 List all the block devices.
1629
1630 The full block device names are returned, eg. C</dev/sda>.
1631
1632 See also C<guestfs_list_filesystems>.");
1633
1634   ("list_partitions", (RStringList "partitions", [], []), 8, [],
1635    [InitBasicFS, Always, TestOutputListOfDevices (
1636       [["list_partitions"]], ["/dev/sda1"; "/dev/sdb1"]);
1637     InitEmpty, Always, TestOutputListOfDevices (
1638       [["part_init"; "/dev/sda"; "mbr"];
1639        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1640        ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1641        ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1642        ["list_partitions"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"; "/dev/sdb1"])],
1643    "list the partitions",
1644    "\
1645 List all the partitions detected on all block devices.
1646
1647 The full partition device names are returned, eg. C</dev/sda1>
1648
1649 This does not return logical volumes.  For that you will need to
1650 call C<guestfs_lvs>.
1651
1652 See also C<guestfs_list_filesystems>.");
1653
1654   ("pvs", (RStringList "physvols", [], []), 9, [Optional "lvm2"],
1655    [InitBasicFSonLVM, Always, TestOutputListOfDevices (
1656       [["pvs"]], ["/dev/sda1"]);
1657     InitEmpty, Always, TestOutputListOfDevices (
1658       [["part_init"; "/dev/sda"; "mbr"];
1659        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1660        ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1661        ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1662        ["pvcreate"; "/dev/sda1"];
1663        ["pvcreate"; "/dev/sda2"];
1664        ["pvcreate"; "/dev/sda3"];
1665        ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
1666    "list the LVM physical volumes (PVs)",
1667    "\
1668 List all the physical volumes detected.  This is the equivalent
1669 of the L<pvs(8)> command.
1670
1671 This returns a list of just the device names that contain
1672 PVs (eg. C</dev/sda2>).
1673
1674 See also C<guestfs_pvs_full>.");
1675
1676   ("vgs", (RStringList "volgroups", [], []), 10, [Optional "lvm2"],
1677    [InitBasicFSonLVM, Always, TestOutputList (
1678       [["vgs"]], ["VG"]);
1679     InitEmpty, Always, TestOutputList (
1680       [["part_init"; "/dev/sda"; "mbr"];
1681        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1682        ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1683        ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1684        ["pvcreate"; "/dev/sda1"];
1685        ["pvcreate"; "/dev/sda2"];
1686        ["pvcreate"; "/dev/sda3"];
1687        ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1688        ["vgcreate"; "VG2"; "/dev/sda3"];
1689        ["vgs"]], ["VG1"; "VG2"])],
1690    "list the LVM volume groups (VGs)",
1691    "\
1692 List all the volumes groups detected.  This is the equivalent
1693 of the L<vgs(8)> command.
1694
1695 This returns a list of just the volume group names that were
1696 detected (eg. C<VolGroup00>).
1697
1698 See also C<guestfs_vgs_full>.");
1699
1700   ("lvs", (RStringList "logvols", [], []), 11, [Optional "lvm2"],
1701    [InitBasicFSonLVM, Always, TestOutputList (
1702       [["lvs"]], ["/dev/VG/LV"]);
1703     InitEmpty, Always, TestOutputList (
1704       [["part_init"; "/dev/sda"; "mbr"];
1705        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
1706        ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
1707        ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
1708        ["pvcreate"; "/dev/sda1"];
1709        ["pvcreate"; "/dev/sda2"];
1710        ["pvcreate"; "/dev/sda3"];
1711        ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1712        ["vgcreate"; "VG2"; "/dev/sda3"];
1713        ["lvcreate"; "LV1"; "VG1"; "50"];
1714        ["lvcreate"; "LV2"; "VG1"; "50"];
1715        ["lvcreate"; "LV3"; "VG2"; "50"];
1716        ["lvs"]], ["/dev/VG1/LV1"; "/dev/VG1/LV2"; "/dev/VG2/LV3"])],
1717    "list the LVM logical volumes (LVs)",
1718    "\
1719 List all the logical volumes detected.  This is the equivalent
1720 of the L<lvs(8)> command.
1721
1722 This returns a list of the logical volume device names
1723 (eg. C</dev/VolGroup00/LogVol00>).
1724
1725 See also C<guestfs_lvs_full>, C<guestfs_list_filesystems>.");
1726
1727   ("pvs_full", (RStructList ("physvols", "lvm_pv"), [], []), 12, [Optional "lvm2"],
1728    [], (* XXX how to test? *)
1729    "list the LVM physical volumes (PVs)",
1730    "\
1731 List all the physical volumes detected.  This is the equivalent
1732 of the L<pvs(8)> command.  The \"full\" version includes all fields.");
1733
1734   ("vgs_full", (RStructList ("volgroups", "lvm_vg"), [], []), 13, [Optional "lvm2"],
1735    [], (* XXX how to test? *)
1736    "list the LVM volume groups (VGs)",
1737    "\
1738 List all the volumes groups detected.  This is the equivalent
1739 of the L<vgs(8)> command.  The \"full\" version includes all fields.");
1740
1741   ("lvs_full", (RStructList ("logvols", "lvm_lv"), [], []), 14, [Optional "lvm2"],
1742    [], (* XXX how to test? *)
1743    "list the LVM logical volumes (LVs)",
1744    "\
1745 List all the logical volumes detected.  This is the equivalent
1746 of the L<lvs(8)> command.  The \"full\" version includes all fields.");
1747
1748   ("read_lines", (RStringList "lines", [Pathname "path"], []), 15, [],
1749    [InitISOFS, Always, TestOutputList (
1750       [["read_lines"; "/known-4"]], ["abc"; "def"; "ghi"]);
1751     InitISOFS, Always, TestOutputList (
1752       [["read_lines"; "/empty"]], [])],
1753    "read file as lines",
1754    "\
1755 Return the contents of the file named C<path>.
1756
1757 The file contents are returned as a list of lines.  Trailing
1758 C<LF> and C<CRLF> character sequences are I<not> returned.
1759
1760 Note that this function cannot correctly handle binary files
1761 (specifically, files containing C<\\0> character which is treated
1762 as end of line).  For those you need to use the C<guestfs_read_file>
1763 function which has a more complex interface.");
1764
1765   ("aug_init", (RErr, [Pathname "root"; Int "flags"], []), 16, [Optional "augeas"],
1766    [], (* XXX Augeas code needs tests. *)
1767    "create a new Augeas handle",
1768    "\
1769 Create a new Augeas handle for editing configuration files.
1770 If there was any previous Augeas handle associated with this
1771 guestfs session, then it is closed.
1772
1773 You must call this before using any other C<guestfs_aug_*>
1774 commands.
1775
1776 C<root> is the filesystem root.  C<root> must not be NULL,
1777 use C</> instead.
1778
1779 The flags are the same as the flags defined in
1780 E<lt>augeas.hE<gt>, the logical I<or> of the following
1781 integers:
1782
1783 =over 4
1784
1785 =item C<AUG_SAVE_BACKUP> = 1
1786
1787 Keep the original file with a C<.augsave> extension.
1788
1789 =item C<AUG_SAVE_NEWFILE> = 2
1790
1791 Save changes into a file with extension C<.augnew>, and
1792 do not overwrite original.  Overrides C<AUG_SAVE_BACKUP>.
1793
1794 =item C<AUG_TYPE_CHECK> = 4
1795
1796 Typecheck lenses (can be expensive).
1797
1798 =item C<AUG_NO_STDINC> = 8
1799
1800 Do not use standard load path for modules.
1801
1802 =item C<AUG_SAVE_NOOP> = 16
1803
1804 Make save a no-op, just record what would have been changed.
1805
1806 =item C<AUG_NO_LOAD> = 32
1807
1808 Do not load the tree in C<guestfs_aug_init>.
1809
1810 =back
1811
1812 To close the handle, you can call C<guestfs_aug_close>.
1813
1814 To find out more about Augeas, see L<http://augeas.net/>.");
1815
1816   ("aug_close", (RErr, [], []), 26, [Optional "augeas"],
1817    [], (* XXX Augeas code needs tests. *)
1818    "close the current Augeas handle",
1819    "\
1820 Close the current Augeas handle and free up any resources
1821 used by it.  After calling this, you have to call
1822 C<guestfs_aug_init> again before you can use any other
1823 Augeas functions.");
1824
1825   ("aug_defvar", (RInt "nrnodes", [String "name"; OptString "expr"], []), 17, [Optional "augeas"],
1826    [], (* XXX Augeas code needs tests. *)
1827    "define an Augeas variable",
1828    "\
1829 Defines an Augeas variable C<name> whose value is the result
1830 of evaluating C<expr>.  If C<expr> is NULL, then C<name> is
1831 undefined.
1832
1833 On success this returns the number of nodes in C<expr>, or
1834 C<0> if C<expr> evaluates to something which is not a nodeset.");
1835
1836   ("aug_defnode", (RStruct ("nrnodescreated", "int_bool"), [String "name"; String "expr"; String "val"], []), 18, [Optional "augeas"],
1837    [], (* XXX Augeas code needs tests. *)
1838    "define an Augeas node",
1839    "\
1840 Defines a variable C<name> whose value is the result of
1841 evaluating C<expr>.
1842
1843 If C<expr> evaluates to an empty nodeset, a node is created,
1844 equivalent to calling C<guestfs_aug_set> C<expr>, C<value>.
1845 C<name> will be the nodeset containing that single node.
1846
1847 On success this returns a pair containing the
1848 number of nodes in the nodeset, and a boolean flag
1849 if a node was created.");
1850
1851   ("aug_get", (RString "val", [String "augpath"], []), 19, [Optional "augeas"],
1852    [], (* XXX Augeas code needs tests. *)
1853    "look up the value of an Augeas path",
1854    "\
1855 Look up the value associated with C<path>.  If C<path>
1856 matches exactly one node, the C<value> is returned.");
1857
1858   ("aug_set", (RErr, [String "augpath"; String "val"], []), 20, [Optional "augeas"],
1859    [], (* XXX Augeas code needs tests. *)
1860    "set Augeas path to value",
1861    "\
1862 Set the value associated with C<path> to C<val>.
1863
1864 In the Augeas API, it is possible to clear a node by setting
1865 the value to NULL.  Due to an oversight in the libguestfs API
1866 you cannot do that with this call.  Instead you must use the
1867 C<guestfs_aug_clear> call.");
1868
1869   ("aug_insert", (RErr, [String "augpath"; String "label"; Bool "before"], []), 21, [Optional "augeas"],
1870    [], (* XXX Augeas code needs tests. *)
1871    "insert a sibling Augeas node",
1872    "\
1873 Create a new sibling C<label> for C<path>, inserting it into
1874 the tree before or after C<path> (depending on the boolean
1875 flag C<before>).
1876
1877 C<path> must match exactly one existing node in the tree, and
1878 C<label> must be a label, ie. not contain C</>, C<*> or end
1879 with a bracketed index C<[N]>.");
1880
1881   ("aug_rm", (RInt "nrnodes", [String "augpath"], []), 22, [Optional "augeas"],
1882    [], (* XXX Augeas code needs tests. *)
1883    "remove an Augeas path",
1884    "\
1885 Remove C<path> and all of its children.
1886
1887 On success this returns the number of entries which were removed.");
1888
1889   ("aug_mv", (RErr, [String "src"; String "dest"], []), 23, [Optional "augeas"],
1890    [], (* XXX Augeas code needs tests. *)
1891    "move Augeas node",
1892    "\
1893 Move the node C<src> to C<dest>.  C<src> must match exactly
1894 one node.  C<dest> is overwritten if it exists.");
1895
1896   ("aug_match", (RStringList "matches", [String "augpath"], []), 24, [Optional "augeas"],
1897    [], (* XXX Augeas code needs tests. *)
1898    "return Augeas nodes which match augpath",
1899    "\
1900 Returns a list of paths which match the path expression C<path>.
1901 The returned paths are sufficiently qualified so that they match
1902 exactly one node in the current tree.");
1903
1904   ("aug_save", (RErr, [], []), 25, [Optional "augeas"],
1905    [], (* XXX Augeas code needs tests. *)
1906    "write all pending Augeas changes to disk",
1907    "\
1908 This writes all pending changes to disk.
1909
1910 The flags which were passed to C<guestfs_aug_init> affect exactly
1911 how files are saved.");
1912
1913   ("aug_load", (RErr, [], []), 27, [Optional "augeas"],
1914    [], (* XXX Augeas code needs tests. *)
1915    "load files into the tree",
1916    "\
1917 Load files into the tree.
1918
1919 See C<aug_load> in the Augeas documentation for the full gory
1920 details.");
1921
1922   ("aug_ls", (RStringList "matches", [String "augpath"], []), 28, [Optional "augeas"],
1923    [], (* XXX Augeas code needs tests. *)
1924    "list Augeas nodes under augpath",
1925    "\
1926 This is just a shortcut for listing C<guestfs_aug_match>
1927 C<path/*> and sorting the resulting nodes into alphabetical order.");
1928
1929   ("rm", (RErr, [Pathname "path"], []), 29, [],
1930    [InitScratchFS, Always, TestRun
1931       [["mkdir"; "/rm"];
1932        ["touch"; "/rm/new"];
1933        ["rm"; "/rm/new"]];
1934     InitScratchFS, Always, TestLastFail
1935       [["rm"; "/nosuchfile"]];
1936     InitScratchFS, Always, TestLastFail
1937       [["mkdir"; "/rm2"];
1938        ["rm"; "/rm2"]]],
1939    "remove a file",
1940    "\
1941 Remove the single file C<path>.");
1942
1943   ("rmdir", (RErr, [Pathname "path"], []), 30, [],
1944    [InitScratchFS, Always, TestRun
1945       [["mkdir"; "/rmdir"];
1946        ["rmdir"; "/rmdir"]];
1947     InitScratchFS, Always, TestLastFail
1948       [["rmdir"; "/rmdir2"]];
1949     InitScratchFS, Always, TestLastFail
1950       [["mkdir"; "/rmdir3"];
1951        ["touch"; "/rmdir3/new"];
1952        ["rmdir"; "/rmdir3/new"]]],
1953    "remove a directory",
1954    "\
1955 Remove the single directory C<path>.");
1956
1957   ("rm_rf", (RErr, [Pathname "path"], []), 31, [],
1958    [InitScratchFS, Always, TestOutputFalse
1959       [["mkdir"; "/rm_rf"];
1960        ["mkdir"; "/rm_rf/foo"];
1961        ["touch"; "/rm_rf/foo/bar"];
1962        ["rm_rf"; "/rm_rf"];
1963        ["exists"; "/rm_rf"]]],
1964    "remove a file or directory recursively",
1965    "\
1966 Remove the file or directory C<path>, recursively removing the
1967 contents if its a directory.  This is like the C<rm -rf> shell
1968 command.");
1969
1970   ("mkdir", (RErr, [Pathname "path"], []), 32, [],
1971    [InitScratchFS, Always, TestOutputTrue
1972       [["mkdir"; "/mkdir"];
1973        ["is_dir"; "/mkdir"]];
1974     InitScratchFS, Always, TestLastFail
1975       [["mkdir"; "/mkdir2/foo/bar"]]],
1976    "create a directory",
1977    "\
1978 Create a directory named C<path>.");
1979
1980   ("mkdir_p", (RErr, [Pathname "path"], []), 33, [],
1981    [InitScratchFS, Always, TestOutputTrue
1982       [["mkdir_p"; "/mkdir_p/foo/bar"];
1983        ["is_dir"; "/mkdir_p/foo/bar"]];
1984     InitScratchFS, Always, TestOutputTrue
1985       [["mkdir_p"; "/mkdir_p2/foo/bar"];
1986        ["is_dir"; "/mkdir_p2/foo"]];
1987     InitScratchFS, Always, TestOutputTrue
1988       [["mkdir_p"; "/mkdir_p3/foo/bar"];
1989        ["is_dir"; "/mkdir_p3"]];
1990     (* Regression tests for RHBZ#503133: *)
1991     InitScratchFS, Always, TestRun
1992       [["mkdir"; "/mkdir_p4"];
1993        ["mkdir_p"; "/mkdir_p4"]];
1994     InitScratchFS, Always, TestLastFail
1995       [["touch"; "/mkdir_p5"];
1996        ["mkdir_p"; "/mkdir_p5"]]],
1997    "create a directory and parents",
1998    "\
1999 Create a directory named C<path>, creating any parent directories
2000 as necessary.  This is like the C<mkdir -p> shell command.");
2001
2002   ("chmod", (RErr, [Int "mode"; Pathname "path"], []), 34, [],
2003    [], (* XXX Need stat command to test *)
2004    "change file mode",
2005    "\
2006 Change the mode (permissions) of C<path> to C<mode>.  Only
2007 numeric modes are supported.
2008
2009 I<Note>: When using this command from guestfish, C<mode>
2010 by default would be decimal, unless you prefix it with
2011 C<0> to get octal, ie. use C<0700> not C<700>.
2012
2013 The mode actually set is affected by the umask.");
2014
2015   ("chown", (RErr, [Int "owner"; Int "group"; Pathname "path"], []), 35, [],
2016    [], (* XXX Need stat command to test *)
2017    "change file owner and group",
2018    "\
2019 Change the file owner to C<owner> and group to C<group>.
2020
2021 Only numeric uid and gid are supported.  If you want to use
2022 names, you will need to locate and parse the password file
2023 yourself (Augeas support makes this relatively easy).");
2024
2025   ("exists", (RBool "existsflag", [Pathname "path"], []), 36, [],
2026    [InitISOFS, Always, TestOutputTrue (
2027       [["exists"; "/empty"]]);
2028     InitISOFS, Always, TestOutputTrue (
2029       [["exists"; "/directory"]])],
2030    "test if file or directory exists",
2031    "\
2032 This returns C<true> if and only if there is a file, directory
2033 (or anything) with the given C<path> name.
2034
2035 See also C<guestfs_is_file>, C<guestfs_is_dir>, C<guestfs_stat>.");
2036
2037   ("is_file", (RBool "fileflag", [Pathname "path"], []), 37, [],
2038    [InitISOFS, Always, TestOutputTrue (
2039       [["is_file"; "/known-1"]]);
2040     InitISOFS, Always, TestOutputFalse (
2041       [["is_file"; "/directory"]])],
2042    "test if a regular file",
2043    "\
2044 This returns C<true> if and only if there is a regular file
2045 with the given C<path> name.  Note that it returns false for
2046 other objects like directories.
2047
2048 See also C<guestfs_stat>.");
2049
2050   ("is_dir", (RBool "dirflag", [Pathname "path"], []), 38, [],
2051    [InitISOFS, Always, TestOutputFalse (
2052       [["is_dir"; "/known-3"]]);
2053     InitISOFS, Always, TestOutputTrue (
2054       [["is_dir"; "/directory"]])],
2055    "test if a directory",
2056    "\
2057 This returns C<true> if and only if there is a directory
2058 with the given C<path> name.  Note that it returns false for
2059 other objects like files.
2060
2061 See also C<guestfs_stat>.");
2062
2063   ("pvcreate", (RErr, [Device "device"], []), 39, [Optional "lvm2"],
2064    [InitEmpty, Always, TestOutputListOfDevices (
2065       [["part_init"; "/dev/sda"; "mbr"];
2066        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
2067        ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
2068        ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
2069        ["pvcreate"; "/dev/sda1"];
2070        ["pvcreate"; "/dev/sda2"];
2071        ["pvcreate"; "/dev/sda3"];
2072        ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
2073    "create an LVM physical volume",
2074    "\
2075 This creates an LVM physical volume on the named C<device>,
2076 where C<device> should usually be a partition name such
2077 as C</dev/sda1>.");
2078
2079   ("vgcreate", (RErr, [String "volgroup"; DeviceList "physvols"], []), 40, [Optional "lvm2"],
2080    [InitEmpty, Always, TestOutputList (
2081       [["part_init"; "/dev/sda"; "mbr"];
2082        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
2083        ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
2084        ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
2085        ["pvcreate"; "/dev/sda1"];
2086        ["pvcreate"; "/dev/sda2"];
2087        ["pvcreate"; "/dev/sda3"];
2088        ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
2089        ["vgcreate"; "VG2"; "/dev/sda3"];
2090        ["vgs"]], ["VG1"; "VG2"])],
2091    "create an LVM volume group",
2092    "\
2093 This creates an LVM volume group called C<volgroup>
2094 from the non-empty list of physical volumes C<physvols>.");
2095
2096   ("lvcreate", (RErr, [String "logvol"; String "volgroup"; Int "mbytes"], []), 41, [Optional "lvm2"],
2097    [InitEmpty, Always, TestOutputList (
2098       [["part_init"; "/dev/sda"; "mbr"];
2099        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
2100        ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
2101        ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
2102        ["pvcreate"; "/dev/sda1"];
2103        ["pvcreate"; "/dev/sda2"];
2104        ["pvcreate"; "/dev/sda3"];
2105        ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
2106        ["vgcreate"; "VG2"; "/dev/sda3"];
2107        ["lvcreate"; "LV1"; "VG1"; "50"];
2108        ["lvcreate"; "LV2"; "VG1"; "50"];
2109        ["lvcreate"; "LV3"; "VG2"; "50"];
2110        ["lvcreate"; "LV4"; "VG2"; "50"];
2111        ["lvcreate"; "LV5"; "VG2"; "50"];
2112        ["lvs"]],
2113       ["/dev/VG1/LV1"; "/dev/VG1/LV2";
2114        "/dev/VG2/LV3"; "/dev/VG2/LV4"; "/dev/VG2/LV5"])],
2115    "create an LVM logical volume",
2116    "\
2117 This creates an LVM logical volume called C<logvol>
2118 on the volume group C<volgroup>, with C<size> megabytes.");
2119
2120   ("mkfs", (RErr, [String "fstype"; Device "device"], []), 42, [],
2121    [InitEmpty, Always, TestOutput (
2122       [["part_disk"; "/dev/sda"; "mbr"];
2123        ["mkfs"; "ext2"; "/dev/sda1"];
2124        ["mount_options"; ""; "/dev/sda1"; "/"];
2125        ["write"; "/new"; "new file contents"];
2126        ["cat"; "/new"]], "new file contents")],
2127    "make a filesystem",
2128    "\
2129 This creates a filesystem on C<device> (usually a partition
2130 or LVM logical volume).  The filesystem type is C<fstype>, for
2131 example C<ext3>.");
2132
2133   ("sfdisk", (RErr, [Device "device";
2134                      Int "cyls"; Int "heads"; Int "sectors";
2135                      StringList "lines"], []), 43, [DangerWillRobinson],
2136    [],
2137    "create partitions on a block device",
2138    "\
2139 This is a direct interface to the L<sfdisk(8)> program for creating
2140 partitions on block devices.
2141
2142 C<device> should be a block device, for example C</dev/sda>.
2143
2144 C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads
2145 and sectors on the device, which are passed directly to sfdisk as
2146 the I<-C>, I<-H> and I<-S> parameters.  If you pass C<0> for any
2147 of these, then the corresponding parameter is omitted.  Usually for
2148 'large' disks, you can just pass C<0> for these, but for small
2149 (floppy-sized) disks, sfdisk (or rather, the kernel) cannot work
2150 out the right geometry and you will need to tell it.
2151
2152 C<lines> is a list of lines that we feed to C<sfdisk>.  For more
2153 information refer to the L<sfdisk(8)> manpage.
2154
2155 To create a single partition occupying the whole disk, you would
2156 pass C<lines> as a single element list, when the single element being
2157 the string C<,> (comma).
2158
2159 See also: C<guestfs_sfdisk_l>, C<guestfs_sfdisk_N>,
2160 C<guestfs_part_init>");
2161
2162   ("write_file", (RErr, [Pathname "path"; String "content"; Int "size"], []), 44, [ProtocolLimitWarning; DeprecatedBy "write"],
2163    (* Regression test for RHBZ#597135. *)
2164    [InitScratchFS, Always, TestLastFail
2165       [["write_file"; "/write_file"; "abc"; "10000"]]],
2166    "create a file",
2167    "\
2168 This call creates a file called C<path>.  The contents of the
2169 file is the string C<content> (which can contain any 8 bit data),
2170 with length C<size>.
2171
2172 As a special case, if C<size> is C<0>
2173 then the length is calculated using C<strlen> (so in this case
2174 the content cannot contain embedded ASCII NULs).
2175
2176 I<NB.> Owing to a bug, writing content containing ASCII NUL
2177 characters does I<not> work, even if the length is specified.");
2178
2179   ("umount", (RErr, [String "pathordevice"], []), 45, [FishAlias "unmount"],
2180    [InitEmpty, Always, TestOutputListOfDevices (
2181       [["part_disk"; "/dev/sda"; "mbr"];
2182        ["mkfs"; "ext2"; "/dev/sda1"];
2183        ["mount_options"; ""; "/dev/sda1"; "/"];
2184        ["mounts"]], ["/dev/sda1"]);
2185     InitEmpty, Always, TestOutputList (
2186       [["part_disk"; "/dev/sda"; "mbr"];
2187        ["mkfs"; "ext2"; "/dev/sda1"];
2188        ["mount_options"; ""; "/dev/sda1"; "/"];
2189        ["umount"; "/"];
2190        ["mounts"]], [])],
2191    "unmount a filesystem",
2192    "\
2193 This unmounts the given filesystem.  The filesystem may be
2194 specified either by its mountpoint (path) or the device which
2195 contains the filesystem.");
2196
2197   ("mounts", (RStringList "devices", [], []), 46, [],
2198    [InitScratchFS, Always, TestOutputListOfDevices (
2199       [["mounts"]], ["/dev/sdb1"])],
2200    "show mounted filesystems",
2201    "\
2202 This returns the list of currently mounted filesystems.  It returns
2203 the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
2204
2205 Some internal mounts are not shown.
2206
2207 See also: C<guestfs_mountpoints>");
2208
2209   ("umount_all", (RErr, [], []), 47, [FishAlias "unmount-all"],
2210    [InitScratchFS, Always, TestOutputList (
2211       [["umount_all"];
2212        ["mounts"]], []);
2213     (* check that umount_all can unmount nested mounts correctly: *)
2214     InitEmpty, Always, TestOutputList (
2215       [["part_init"; "/dev/sda"; "mbr"];
2216        ["part_add"; "/dev/sda"; "p"; "64"; "204799"];
2217        ["part_add"; "/dev/sda"; "p"; "204800"; "409599"];
2218        ["part_add"; "/dev/sda"; "p"; "409600"; "-64"];
2219        ["mkfs"; "ext2"; "/dev/sda1"];
2220        ["mkfs"; "ext2"; "/dev/sda2"];
2221        ["mkfs"; "ext2"; "/dev/sda3"];
2222        ["mount_options"; ""; "/dev/sda1"; "/"];
2223        ["mkdir"; "/mp1"];
2224        ["mount_options"; ""; "/dev/sda2"; "/mp1"];
2225        ["mkdir"; "/mp1/mp2"];
2226        ["mount_options"; ""; "/dev/sda3"; "/mp1/mp2"];
2227        ["mkdir"; "/mp1/mp2/mp3"];
2228        ["umount_all"];
2229        ["mounts"]], [])],
2230    "unmount all filesystems",
2231    "\
2232 This unmounts all mounted filesystems.
2233
2234 Some internal mounts are not unmounted by this call.");
2235
2236   ("lvm_remove_all", (RErr, [], []), 48, [DangerWillRobinson; Optional "lvm2"],
2237    [],
2238    "remove all LVM LVs, VGs and PVs",
2239    "\
2240 This command removes all LVM logical volumes, volume groups
2241 and physical volumes.");
2242
2243   ("file", (RString "description", [Dev_or_Path "path"], []), 49, [],
2244    [InitISOFS, Always, TestOutput (
2245       [["file"; "/empty"]], "empty");
2246     InitISOFS, Always, TestOutput (
2247       [["file"; "/known-1"]], "ASCII text");
2248     InitISOFS, Always, TestLastFail (
2249       [["file"; "/notexists"]]);
2250     InitISOFS, Always, TestOutput (
2251       [["file"; "/abssymlink"]], "symbolic link");
2252     InitISOFS, Always, TestOutput (
2253       [["file"; "/directory"]], "directory")],
2254    "determine file type",
2255    "\
2256 This call uses the standard L<file(1)> command to determine
2257 the type or contents of the file.
2258
2259 This call will also transparently look inside various types
2260 of compressed file.
2261
2262 The exact command which runs is C<file -zb path>.  Note in
2263 particular that the filename is not prepended to the output
2264 (the C<-b> option).
2265
2266 This command can also be used on C</dev/> devices
2267 (and partitions, LV names).  You can for example use this
2268 to determine if a device contains a filesystem, although
2269 it's usually better to use C<guestfs_vfs_type>.
2270
2271 If the C<path> does not begin with C</dev/> then
2272 this command only works for the content of regular files.
2273 For other file types (directory, symbolic link etc) it
2274 will just return the string C<directory> etc.");
2275
2276   ("command", (RString "output", [StringList "arguments"], []), 50, [ProtocolLimitWarning],
2277    [InitScratchFS, Always, TestOutput (
2278       [["mkdir"; "/command"];
2279        ["upload"; "test-command"; "/command/test-command"];
2280        ["chmod"; "0o755"; "/command/test-command"];
2281        ["command"; "/command/test-command 1"]], "Result1");
2282     InitScratchFS, Always, TestOutput (
2283       [["mkdir"; "/command2"];
2284        ["upload"; "test-command"; "/command2/test-command"];
2285        ["chmod"; "0o755"; "/command2/test-command"];
2286        ["command"; "/command2/test-command 2"]], "Result2\n");
2287     InitScratchFS, Always, TestOutput (
2288       [["mkdir"; "/command3"];
2289        ["upload"; "test-command"; "/command3/test-command"];
2290        ["chmod"; "0o755"; "/command3/test-command"];
2291        ["command"; "/command3/test-command 3"]], "\nResult3");
2292     InitScratchFS, Always, TestOutput (
2293       [["mkdir"; "/command4"];
2294        ["upload"; "test-command"; "/command4/test-command"];
2295        ["chmod"; "0o755"; "/command4/test-command"];
2296        ["command"; "/command4/test-command 4"]], "\nResult4\n");
2297     InitScratchFS, Always, TestOutput (
2298       [["mkdir"; "/command5"];
2299        ["upload"; "test-command"; "/command5/test-command"];
2300        ["chmod"; "0o755"; "/command5/test-command"];
2301        ["command"; "/command5/test-command 5"]], "\nResult5\n\n");
2302     InitScratchFS, Always, TestOutput (
2303       [["mkdir"; "/command6"];
2304        ["upload"; "test-command"; "/command6/test-command"];
2305        ["chmod"; "0o755"; "/command6/test-command"];
2306        ["command"; "/command6/test-command 6"]], "\n\nResult6\n\n");
2307     InitScratchFS, Always, TestOutput (
2308       [["mkdir"; "/command7"];
2309        ["upload"; "test-command"; "/command7/test-command"];
2310        ["chmod"; "0o755"; "/command7/test-command"];
2311        ["command"; "/command7/test-command 7"]], "");
2312     InitScratchFS, Always, TestOutput (
2313       [["mkdir"; "/command8"];
2314        ["upload"; "test-command"; "/command8/test-command"];
2315        ["chmod"; "0o755"; "/command8/test-command"];
2316        ["command"; "/command8/test-command 8"]], "\n");
2317     InitScratchFS, Always, TestOutput (
2318       [["mkdir"; "/command9"];
2319        ["upload"; "test-command"; "/command9/test-command"];
2320        ["chmod"; "0o755"; "/command9/test-command"];
2321        ["command"; "/command9/test-command 9"]], "\n\n");
2322     InitScratchFS, Always, TestOutput (
2323       [["mkdir"; "/command10"];
2324        ["upload"; "test-command"; "/command10/test-command"];
2325        ["chmod"; "0o755"; "/command10/test-command"];
2326        ["command"; "/command10/test-command 10"]], "Result10-1\nResult10-2\n");
2327     InitScratchFS, Always, TestOutput (
2328       [["mkdir"; "/command11"];
2329        ["upload"; "test-command"; "/command11/test-command"];
2330        ["chmod"; "0o755"; "/command11/test-command"];
2331        ["command"; "/command11/test-command 11"]], "Result11-1\nResult11-2");
2332     InitScratchFS, Always, TestLastFail (
2333       [["mkdir"; "/command12"];
2334        ["upload"; "test-command"; "/command12/test-command"];
2335        ["chmod"; "0o755"; "/command12/test-command"];
2336        ["command"; "/command12/test-command"]])],
2337    "run a command from the guest filesystem",
2338    "\
2339 This call runs a command from the guest filesystem.  The
2340 filesystem must be mounted, and must contain a compatible
2341 operating system (ie. something Linux, with the same
2342 or compatible processor architecture).
2343
2344 The single parameter is an argv-style list of arguments.
2345 The first element is the name of the program to run.
2346 Subsequent elements are parameters.  The list must be
2347 non-empty (ie. must contain a program name).  Note that
2348 the command runs directly, and is I<not> invoked via
2349 the shell (see C<guestfs_sh>).
2350
2351 The return value is anything printed to I<stdout> by
2352 the command.
2353
2354 If the command returns a non-zero exit status, then
2355 this function returns an error message.  The error message
2356 string is the content of I<stderr> from the command.
2357
2358 The C<$PATH> environment variable will contain at least
2359 C</usr/bin> and C</bin>.  If you require a program from
2360 another location, you should provide the full path in the
2361 first parameter.
2362
2363 Shared libraries and data files required by the program
2364 must be available on filesystems which are mounted in the
2365 correct places.  It is the caller's responsibility to ensure
2366 all filesystems that are needed are mounted at the right
2367 locations.");
2368
2369   ("command_lines", (RStringList "lines", [StringList "arguments"], []), 51, [ProtocolLimitWarning],
2370    [InitScratchFS, Always, TestOutputList (
2371       [["mkdir"; "/command_lines"];
2372        ["upload"; "test-command"; "/command_lines/test-command"];
2373        ["chmod"; "0o755"; "/command_lines/test-command"];
2374        ["command_lines"; "/command_lines/test-command 1"]], ["Result1"]);
2375     InitScratchFS, Always, TestOutputList (
2376       [["mkdir"; "/command_lines2"];
2377        ["upload"; "test-command"; "/command_lines2/test-command"];
2378        ["chmod"; "0o755"; "/command_lines2/test-command"];
2379        ["command_lines"; "/command_lines2/test-command 2"]], ["Result2"]);
2380     InitScratchFS, Always, TestOutputList (
2381       [["mkdir"; "/command_lines3"];
2382        ["upload"; "test-command"; "/command_lines3/test-command"];
2383        ["chmod"; "0o755"; "/command_lines3/test-command"];
2384        ["command_lines"; "/command_lines3/test-command 3"]], ["";"Result3"]);
2385     InitScratchFS, Always, TestOutputList (
2386       [["mkdir"; "/command_lines4"];
2387        ["upload"; "test-command"; "/command_lines4/test-command"];
2388        ["chmod"; "0o755"; "/command_lines4/test-command"];
2389        ["command_lines"; "/command_lines4/test-command 4"]], ["";"Result4"]);
2390     InitScratchFS, Always, TestOutputList (
2391       [["mkdir"; "/command_lines5"];
2392        ["upload"; "test-command"; "/command_lines5/test-command"];
2393        ["chmod"; "0o755"; "/command_lines5/test-command"];
2394        ["command_lines"; "/command_lines5/test-command 5"]], ["";"Result5";""]);
2395     InitScratchFS, Always, TestOutputList (
2396       [["mkdir"; "/command_lines6"];
2397        ["upload"; "test-command"; "/command_lines6/test-command"];
2398        ["chmod"; "0o755"; "/command_lines6/test-command"];
2399        ["command_lines"; "/command_lines6/test-command 6"]], ["";"";"Result6";""]);
2400     InitScratchFS, Always, TestOutputList (
2401       [["mkdir"; "/command_lines7"];
2402        ["upload"; "test-command"; "/command_lines7/test-command"];
2403        ["chmod"; "0o755"; "/command_lines7/test-command"];
2404        ["command_lines"; "/command_lines7/test-command 7"]], []);
2405     InitScratchFS, Always, TestOutputList (
2406       [["mkdir"; "/command_lines8"];
2407        ["upload"; "test-command"; "/command_lines8/test-command"];
2408        ["chmod"; "0o755"; "/command_lines8/test-command"];
2409        ["command_lines"; "/command_lines8/test-command 8"]], [""]);
2410     InitScratchFS, Always, TestOutputList (
2411       [["mkdir"; "/command_lines9"];
2412        ["upload"; "test-command"; "/command_lines9/test-command"];
2413        ["chmod"; "0o755"; "/command_lines9/test-command"];
2414        ["command_lines"; "/command_lines9/test-command 9"]], ["";""]);
2415     InitScratchFS, Always, TestOutputList (
2416       [["mkdir"; "/command_lines10"];
2417        ["upload"; "test-command"; "/command_lines10/test-command"];
2418        ["chmod"; "0o755"; "/command_lines10/test-command"];
2419        ["command_lines"; "/command_lines10/test-command 10"]], ["Result10-1";"Result10-2"]);
2420     InitScratchFS, Always, TestOutputList (
2421       [["mkdir"; "/command_lines11"];
2422        ["upload"; "test-command"; "/command_lines11/test-command"];
2423        ["chmod"; "0o755"; "/command_lines11/test-command"];
2424        ["command_lines"; "/command_lines11/test-command 11"]], ["Result11-1";"Result11-2"])],
2425    "run a command, returning lines",
2426    "\
2427 This is the same as C<guestfs_command>, but splits the
2428 result into a list of lines.
2429
2430 See also: C<guestfs_sh_lines>");
2431
2432   ("stat", (RStruct ("statbuf", "stat"), [Pathname "path"], []), 52, [],
2433    [InitISOFS, Always, TestOutputStruct (
2434       [["stat"; "/empty"]], [CompareWithInt ("size", 0)])],
2435    "get file information",
2436    "\
2437 Returns file information for the given C<path>.
2438
2439 This is the same as the C<stat(2)> system call.");
2440
2441   ("lstat", (RStruct ("statbuf", "stat"), [Pathname "path"], []), 53, [],
2442    [InitISOFS, Always, TestOutputStruct (
2443       [["lstat"; "/empty"]], [CompareWithInt ("size", 0)])],
2444    "get file information for a symbolic link",
2445    "\
2446 Returns file information for the given C<path>.
2447
2448 This is the same as C<guestfs_stat> except that if C<path>
2449 is a symbolic link, then the link is stat-ed, not the file it
2450 refers to.
2451
2452 This is the same as the C<lstat(2)> system call.");
2453
2454   ("statvfs", (RStruct ("statbuf", "statvfs"), [Pathname "path"], []), 54, [],
2455    [InitISOFS, Always, TestOutputStruct (
2456       [["statvfs"; "/"]], [CompareWithInt ("namemax", 255)])],
2457    "get file system statistics",
2458    "\
2459 Returns file system statistics for any mounted file system.
2460 C<path> should be a file or directory in the mounted file system
2461 (typically it is the mount point itself, but it doesn't need to be).
2462
2463 This is the same as the C<statvfs(2)> system call.");
2464
2465   ("tune2fs_l", (RHashtable "superblock", [Device "device"], []), 55, [],
2466    [], (* XXX test *)
2467    "get ext2/ext3/ext4 superblock details",
2468    "\
2469 This returns the contents of the ext2, ext3 or ext4 filesystem
2470 superblock on C<device>.
2471
2472 It is the same as running C<tune2fs -l device>.  See L<tune2fs(8)>
2473 manpage for more details.  The list of fields returned isn't
2474 clearly defined, and depends on both the version of C<tune2fs>
2475 that libguestfs was built against, and the filesystem itself.");
2476
2477   ("blockdev_setro", (RErr, [Device "device"], []), 56, [],
2478    [InitEmpty, Always, TestOutputTrue (
2479       [["blockdev_setro"; "/dev/sda"];
2480        ["blockdev_getro"; "/dev/sda"]])],
2481    "set block device to read-only",
2482    "\
2483 Sets the block device named C<device> to read-only.
2484
2485 This uses the L<blockdev(8)> command.");
2486
2487   ("blockdev_setrw", (RErr, [Device "device"], []), 57, [],
2488    [InitEmpty, Always, TestOutputFalse (
2489       [["blockdev_setrw"; "/dev/sda"];
2490        ["blockdev_getro"; "/dev/sda"]])],
2491    "set block device to read-write",
2492    "\
2493 Sets the block device named C<device> to read-write.
2494
2495 This uses the L<blockdev(8)> command.");
2496
2497   ("blockdev_getro", (RBool "ro", [Device "device"], []), 58, [],
2498    [InitEmpty, Always, TestOutputTrue (
2499       [["blockdev_setro"; "/dev/sda"];
2500        ["blockdev_getro"; "/dev/sda"]])],
2501    "is block device set to read-only",
2502    "\
2503 Returns a boolean indicating if the block device is read-only
2504 (true if read-only, false if not).
2505
2506 This uses the L<blockdev(8)> command.");
2507
2508   ("blockdev_getss", (RInt "sectorsize", [Device "device"], []), 59, [],
2509    [InitEmpty, Always, TestOutputInt (
2510       [["blockdev_getss"; "/dev/sda"]], 512)],
2511    "get sectorsize of block device",
2512    "\
2513 This returns the size of sectors on a block device.
2514 Usually 512, but can be larger for modern devices.
2515
2516 (Note, this is not the size in sectors, use C<guestfs_blockdev_getsz>
2517 for that).
2518
2519 This uses the L<blockdev(8)> command.");
2520
2521   ("blockdev_getbsz", (RInt "blocksize", [Device "device"], []), 60, [],
2522    [InitEmpty, Always, TestOutputInt (
2523       [["blockdev_getbsz"; "/dev/sda"]], 4096)],
2524    "get blocksize of block device",
2525    "\
2526 This returns the block size of a device.
2527
2528 (Note this is different from both I<size in blocks> and
2529 I<filesystem block size>).
2530
2531 This uses the L<blockdev(8)> command.");
2532
2533   ("blockdev_setbsz", (RErr, [Device "device"; Int "blocksize"], []), 61, [],
2534    [], (* XXX test *)
2535    "set blocksize of block device",
2536    "\
2537 This sets the block size of a device.
2538
2539 (Note this is different from both I<size in blocks> and
2540 I<filesystem block size>).
2541
2542 This uses the L<blockdev(8)> command.");
2543
2544   ("blockdev_getsz", (RInt64 "sizeinsectors", [Device "device"], []), 62, [],
2545    [InitEmpty, Always, TestOutputInt (
2546       [["blockdev_getsz"; "/dev/sda"]], 1024000)],
2547    "get total size of device in 512-byte sectors",
2548    "\
2549 This returns the size of the device in units of 512-byte sectors
2550 (even if the sectorsize isn't 512 bytes ... weird).
2551
2552 See also C<guestfs_blockdev_getss> for the real sector size of
2553 the device, and C<guestfs_blockdev_getsize64> for the more
2554 useful I<size in bytes>.
2555
2556 This uses the L<blockdev(8)> command.");
2557
2558   ("blockdev_getsize64", (RInt64 "sizeinbytes", [Device "device"], []), 63, [],
2559    [InitEmpty, Always, TestOutputInt (
2560       [["blockdev_getsize64"; "/dev/sda"]], 524288000)],
2561    "get total size of device in bytes",
2562    "\
2563 This returns the size of the device in bytes.
2564
2565 See also C<guestfs_blockdev_getsz>.
2566
2567 This uses the L<blockdev(8)> command.");
2568
2569   ("blockdev_flushbufs", (RErr, [Device "device"], []), 64, [],
2570    [InitEmpty, Always, TestRun
2571       [["blockdev_flushbufs"; "/dev/sda"]]],
2572    "flush device buffers",
2573    "\
2574 This tells the kernel to flush internal buffers associated
2575 with C<device>.
2576
2577 This uses the L<blockdev(8)> command.");
2578
2579   ("blockdev_rereadpt", (RErr, [Device "device"], []), 65, [],
2580    [InitEmpty, Always, TestRun
2581       [["blockdev_rereadpt"; "/dev/sda"]]],
2582    "reread partition table",
2583    "\
2584 Reread the partition table on C<device>.
2585
2586 This uses the L<blockdev(8)> command.");
2587
2588   ("upload", (RErr, [FileIn "filename"; Dev_or_Path "remotefilename"], []), 66, [Progress],
2589    [InitScratchFS, Always, TestOutput (
2590       (* Pick a file from cwd which isn't likely to change. *)
2591       [["mkdir"; "/upload"];
2592        ["upload"; "../COPYING.LIB"; "/upload/COPYING.LIB"];
2593        ["checksum"; "md5"; "/upload/COPYING.LIB"]],
2594       Digest.to_hex (Digest.file "COPYING.LIB"))],
2595    "upload a file from the local machine",
2596    "\
2597 Upload local file C<filename> to C<remotefilename> on the
2598 filesystem.
2599
2600 C<filename> can also be a named pipe.
2601
2602 See also C<guestfs_download>.");
2603
2604   ("download", (RErr, [Dev_or_Path "remotefilename"; FileOut "filename"], []), 67, [Progress],
2605    [InitScratchFS, Always, TestOutput (
2606       (* Pick a file from cwd which isn't likely to change. *)
2607       [["mkdir"; "/download"];
2608        ["upload"; "../COPYING.LIB"; "/download/COPYING.LIB"];
2609        ["download"; "/download/COPYING.LIB"; "testdownload.tmp"];
2610        ["upload"; "testdownload.tmp"; "/download/upload"];
2611        ["checksum"; "md5"; "/download/upload"]],
2612       Digest.to_hex (Digest.file "COPYING.LIB"))],
2613    "download a file to the local machine",
2614    "\
2615 Download file C<remotefilename> and save it as C<filename>
2616 on the local machine.
2617
2618 C<filename> can also be a named pipe.
2619
2620 See also C<guestfs_upload>, C<guestfs_cat>.");
2621
2622   ("checksum", (RString "checksum", [String "csumtype"; Pathname "path"], []), 68, [],
2623    [InitISOFS, Always, TestOutput (
2624       [["checksum"; "crc"; "/known-3"]], "2891671662");
2625     InitISOFS, Always, TestLastFail (
2626       [["checksum"; "crc"; "/notexists"]]);
2627     InitISOFS, Always, TestOutput (
2628       [["checksum"; "md5"; "/known-3"]], "46d6ca27ee07cdc6fa99c2e138cc522c");
2629     InitISOFS, Always, TestOutput (
2630       [["checksum"; "sha1"; "/known-3"]], "b7ebccc3ee418311091c3eda0a45b83c0a770f15");
2631     InitISOFS, Always, TestOutput (
2632       [["checksum"; "sha224"; "/known-3"]], "d2cd1774b28f3659c14116be0a6dc2bb5c4b350ce9cd5defac707741");
2633     InitISOFS, Always, TestOutput (
2634       [["checksum"; "sha256"; "/known-3"]], "75bb71b90cd20cb13f86d2bea8dad63ac7194e7517c3b52b8d06ff52d3487d30");
2635     InitISOFS, Always, TestOutput (
2636       [["checksum"; "sha384"; "/known-3"]], "5fa7883430f357b5d7b7271d3a1d2872b51d73cba72731de6863d3dea55f30646af2799bef44d5ea776a5ec7941ac640");
2637     InitISOFS, Always, TestOutput (
2638       [["checksum"; "sha512"; "/known-3"]], "2794062c328c6b216dca90443b7f7134c5f40e56bd0ed7853123275a09982a6f992e6ca682f9d2fba34a4c5e870d8fe077694ff831e3032a004ee077e00603f6");
2639     (* Test for RHBZ#579608, absolute symbolic links. *)
2640     InitISOFS, Always, TestOutput (
2641       [["checksum"; "sha512"; "/abssymlink"]], "5f57d0639bc95081c53afc63a449403883818edc64da48930ad6b1a4fb49be90404686877743fbcd7c99811f3def7df7bc22635c885c6a8cf79c806b43451c1a")],
2642    "compute MD5, SHAx or CRC checksum of file",
2643    "\
2644 This call computes the MD5, SHAx or CRC checksum of the
2645 file named C<path>.
2646
2647 The type of checksum to compute is given by the C<csumtype>
2648 parameter which must have one of the following values:
2649
2650 =over 4
2651
2652 =item C<crc>
2653
2654 Compute the cyclic redundancy check (CRC) specified by POSIX
2655 for the C<cksum> command.
2656
2657 =item C<md5>
2658
2659 Compute the MD5 hash (using the C<md5sum> program).
2660
2661 =item C<sha1>
2662
2663 Compute the SHA1 hash (using the C<sha1sum> program).
2664
2665 =item C<sha224>
2666
2667 Compute the SHA224 hash (using the C<sha224sum> program).
2668
2669 =item C<sha256>
2670
2671 Compute the SHA256 hash (using the C<sha256sum> program).
2672
2673 =item C<sha384>
2674
2675 Compute the SHA384 hash (using the C<sha384sum> program).
2676
2677 =item C<sha512>
2678
2679 Compute the SHA512 hash (using the C<sha512sum> program).
2680
2681 =back
2682
2683 The checksum is returned as a printable string.
2684
2685 To get the checksum for a device, use C<guestfs_checksum_device>.
2686
2687 To get the checksums for many files, use C<guestfs_checksums_out>.");
2688
2689   ("tar_in", (RErr, [FileIn "tarfile"; Pathname "directory"], []), 69, [],
2690    [InitScratchFS, Always, TestOutput (
2691       [["mkdir"; "/tar_in"];
2692        ["tar_in"; "../images/helloworld.tar"; "/tar_in"];
2693        ["cat"; "/tar_in/hello"]], "hello\n")],
2694    "unpack tarfile to directory",
2695    "\
2696 This command uploads and unpacks local file C<tarfile> (an
2697 I<uncompressed> tar file) into C<directory>.
2698
2699 To upload a compressed tarball, use C<guestfs_tgz_in>
2700 or C<guestfs_txz_in>.");
2701
2702   ("tar_out", (RErr, [String "directory"; FileOut "tarfile"], []), 70, [],
2703    [],
2704    "pack directory into tarfile",
2705    "\
2706 This command packs the contents of C<directory> and downloads
2707 it to local file C<tarfile>.
2708
2709 To download a compressed tarball, use C<guestfs_tgz_out>
2710 or C<guestfs_txz_out>.");
2711
2712   ("tgz_in", (RErr, [FileIn "tarball"; Pathname "directory"], []), 71, [],
2713    [InitScratchFS, Always, TestOutput (
2714       [["mkdir"; "/tgz_in"];
2715        ["tgz_in"; "../images/helloworld.tar.gz"; "/tgz_in"];
2716        ["cat"; "/tgz_in/hello"]], "hello\n")],
2717    "unpack compressed tarball to directory",
2718    "\
2719 This command uploads and unpacks local file C<tarball> (a
2720 I<gzip compressed> tar file) into C<directory>.
2721
2722 To upload an uncompressed tarball, use C<guestfs_tar_in>.");
2723
2724   ("tgz_out", (RErr, [Pathname "directory"; FileOut "tarball"], []), 72, [],
2725    [],
2726    "pack directory into compressed tarball",
2727    "\
2728 This command packs the contents of C<directory> and downloads
2729 it to local file C<tarball>.
2730
2731 To download an uncompressed tarball, use C<guestfs_tar_out>.");
2732
2733   ("mount_ro", (RErr, [Device "device"; String "mountpoint"], []), 73, [],
2734    [InitBasicFS, Always, TestLastFail (
2735       [["umount"; "/"];
2736        ["mount_ro"; "/dev/sda1"; "/"];
2737        ["touch"; "/new"]]);
2738     InitBasicFS, Always, TestOutput (
2739       [["write"; "/new"; "data"];
2740        ["umount"; "/"];
2741        ["mount_ro"; "/dev/sda1"; "/"];
2742        ["cat"; "/new"]], "data")],
2743    "mount a guest disk, read-only",
2744    "\
2745 This is the same as the C<guestfs_mount> command, but it
2746 mounts the filesystem with the read-only (I<-o ro>) flag.");
2747
2748   ("mount_options", (RErr, [String "options"; Device "device"; String "mountpoint"], []), 74, [],
2749    [],
2750    "mount a guest disk with mount options",
2751    "\
2752 This is the same as the C<guestfs_mount> command, but it
2753 allows you to set the mount options as for the
2754 L<mount(8)> I<-o> flag.
2755
2756 If the C<options> parameter is an empty string, then
2757 no options are passed (all options default to whatever
2758 the filesystem uses).");
2759
2760   ("mount_vfs", (RErr, [String "options"; String "vfstype"; Device "device"; String "mountpoint"], []), 75, [],
2761    [],
2762    "mount a guest disk with mount options and vfstype",
2763    "\
2764 This is the same as the C<guestfs_mount> command, but it
2765 allows you to set both the mount options and the vfstype
2766 as for the L<mount(8)> I<-o> and I<-t> flags.");
2767
2768   ("debug", (RString "result", [String "subcmd"; StringList "extraargs"], []), 76, [NotInDocs],
2769    [],
2770    "debugging and internals",
2771    "\
2772 The C<guestfs_debug> command exposes some internals of
2773 C<guestfsd> (the guestfs daemon) that runs inside the
2774 qemu subprocess.
2775
2776 There is no comprehensive help for this command.  You have
2777 to look at the file C<daemon/debug.c> in the libguestfs source
2778 to find out what you can do.");
2779
2780   ("lvremove", (RErr, [Device "device"], []), 77, [Optional "lvm2"],
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/LV1"];
2788        ["lvs"]], ["/dev/VG/LV2"]);
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        ["lvs"]], []);
2797     InitEmpty, Always, TestOutputList (
2798       [["part_disk"; "/dev/sda"; "mbr"];
2799        ["pvcreate"; "/dev/sda1"];
2800        ["vgcreate"; "VG"; "/dev/sda1"];
2801        ["lvcreate"; "LV1"; "VG"; "50"];
2802        ["lvcreate"; "LV2"; "VG"; "50"];
2803        ["lvremove"; "/dev/VG"];
2804        ["vgs"]], ["VG"])],
2805    "remove an LVM logical volume",
2806    "\
2807 Remove an LVM logical volume C<device>, where C<device> is
2808 the path to the LV, such as C</dev/VG/LV>.
2809
2810 You can also remove all LVs in a volume group by specifying
2811 the VG name, C</dev/VG>.");
2812
2813   ("vgremove", (RErr, [String "vgname"], []), 78, [Optional "lvm2"],
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        ["lvs"]], []);
2822     InitEmpty, Always, TestOutputList (
2823       [["part_disk"; "/dev/sda"; "mbr"];
2824        ["pvcreate"; "/dev/sda1"];
2825        ["vgcreate"; "VG"; "/dev/sda1"];
2826        ["lvcreate"; "LV1"; "VG"; "50"];
2827        ["lvcreate"; "LV2"; "VG"; "50"];
2828        ["vgremove"; "VG"];
2829        ["vgs"]], [])],
2830    "remove an LVM volume group",
2831    "\
2832 Remove an LVM volume group C<vgname>, (for example C<VG>).
2833
2834 This also forcibly removes all logical volumes in the volume
2835 group (if any).");
2836
2837   ("pvremove", (RErr, [Device "device"], []), 79, [Optional "lvm2"],
2838    [InitEmpty, Always, TestOutputListOfDevices (
2839       [["part_disk"; "/dev/sda"; "mbr"];
2840        ["pvcreate"; "/dev/sda1"];
2841        ["vgcreate"; "VG"; "/dev/sda1"];
2842        ["lvcreate"; "LV1"; "VG"; "50"];
2843        ["lvcreate"; "LV2"; "VG"; "50"];
2844        ["vgremove"; "VG"];
2845        ["pvremove"; "/dev/sda1"];
2846        ["lvs"]], []);
2847     InitEmpty, Always, TestOutputListOfDevices (
2848       [["part_disk"; "/dev/sda"; "mbr"];
2849        ["pvcreate"; "/dev/sda1"];
2850        ["vgcreate"; "VG"; "/dev/sda1"];
2851        ["lvcreate"; "LV1"; "VG"; "50"];
2852        ["lvcreate"; "LV2"; "VG"; "50"];
2853        ["vgremove"; "VG"];
2854        ["pvremove"; "/dev/sda1"];
2855        ["vgs"]], []);
2856     InitEmpty, Always, TestOutputListOfDevices (
2857       [["part_disk"; "/dev/sda"; "mbr"];
2858        ["pvcreate"; "/dev/sda1"];
2859        ["vgcreate"; "VG"; "/dev/sda1"];
2860        ["lvcreate"; "LV1"; "VG"; "50"];
2861        ["lvcreate"; "LV2"; "VG"; "50"];
2862        ["vgremove"; "VG"];
2863        ["pvremove"; "/dev/sda1"];
2864        ["pvs"]], [])],
2865    "remove an LVM physical volume",
2866    "\
2867 This wipes a physical volume C<device> so that LVM will no longer
2868 recognise it.
2869
2870 The implementation uses the C<pvremove> command which refuses to
2871 wipe physical volumes that contain any volume groups, so you have
2872 to remove those first.");
2873
2874   ("set_e2label", (RErr, [Device "device"; String "label"], []), 80, [],
2875    [InitBasicFS, Always, TestOutput (
2876       [["set_e2label"; "/dev/sda1"; "testlabel"];
2877        ["get_e2label"; "/dev/sda1"]], "testlabel")],
2878    "set the ext2/3/4 filesystem label",
2879    "\
2880 This sets the ext2/3/4 filesystem label of the filesystem on
2881 C<device> to C<label>.  Filesystem labels are limited to
2882 16 characters.
2883
2884 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2label>
2885 to return the existing label on a filesystem.");
2886
2887   ("get_e2label", (RString "label", [Device "device"], []), 81, [DeprecatedBy "vfs_label"],
2888    [],
2889    "get the ext2/3/4 filesystem label",
2890    "\
2891 This returns the ext2/3/4 filesystem label of the filesystem on
2892 C<device>.");
2893
2894   ("set_e2uuid", (RErr, [Device "device"; String "uuid"], []), 82, [],
2895    (let uuid = uuidgen () in
2896     [InitBasicFS, Always, TestOutput (
2897        [["set_e2uuid"; "/dev/sda1"; uuid];
2898         ["get_e2uuid"; "/dev/sda1"]], uuid);
2899      InitBasicFS, Always, TestOutput (
2900        [["set_e2uuid"; "/dev/sda1"; "clear"];
2901         ["get_e2uuid"; "/dev/sda1"]], "");
2902      (* We can't predict what UUIDs will be, so just check the commands run. *)
2903      InitBasicFS, Always, TestRun (
2904        [["set_e2uuid"; "/dev/sda1"; "random"]]);
2905      InitBasicFS, Always, TestRun (
2906        [["set_e2uuid"; "/dev/sda1"; "time"]])]),
2907    "set the ext2/3/4 filesystem UUID",
2908    "\
2909 This sets the ext2/3/4 filesystem UUID of the filesystem on
2910 C<device> to C<uuid>.  The format of the UUID and alternatives
2911 such as C<clear>, C<random> and C<time> are described in the
2912 L<tune2fs(8)> manpage.
2913
2914 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2uuid>
2915 to return the existing UUID of a filesystem.");
2916
2917   ("get_e2uuid", (RString "uuid", [Device "device"], []), 83, [DeprecatedBy "vfs_uuid"],
2918    (* Regression test for RHBZ#597112. *)
2919    (let uuid = uuidgen () in
2920     [InitNone, Always, TestOutput (
2921        [["mke2journal"; "1024"; "/dev/sdc"];
2922         ["set_e2uuid"; "/dev/sdc"; uuid];
2923         ["get_e2uuid"; "/dev/sdc"]], uuid)]),
2924    "get the ext2/3/4 filesystem UUID",
2925    "\
2926 This returns the ext2/3/4 filesystem UUID of the filesystem on
2927 C<device>.");
2928
2929   ("fsck", (RInt "status", [String "fstype"; Device "device"], []), 84, [FishOutput FishOutputHexadecimal],
2930    [InitBasicFS, Always, TestOutputInt (
2931       [["umount"; "/dev/sda1"];
2932        ["fsck"; "ext2"; "/dev/sda1"]], 0);
2933     InitBasicFS, Always, TestOutputInt (
2934       [["umount"; "/dev/sda1"];
2935        ["zero"; "/dev/sda1"];
2936        ["fsck"; "ext2"; "/dev/sda1"]], 8)],
2937    "run the filesystem checker",
2938    "\
2939 This runs the filesystem checker (fsck) on C<device> which
2940 should have filesystem type C<fstype>.
2941
2942 The returned integer is the status.  See L<fsck(8)> for the
2943 list of status codes from C<fsck>.
2944
2945 Notes:
2946
2947 =over 4
2948
2949 =item *
2950
2951 Multiple status codes can be summed together.
2952
2953 =item *
2954
2955 A non-zero return code can mean \"success\", for example if
2956 errors have been corrected on the filesystem.
2957
2958 =item *
2959
2960 Checking or repairing NTFS volumes is not supported
2961 (by linux-ntfs).
2962
2963 =back
2964
2965 This command is entirely equivalent to running C<fsck -a -t fstype device>.");
2966
2967   ("zero", (RErr, [Device "device"], []), 85, [Progress],
2968    [InitBasicFS, Always, TestOutput (
2969       [["umount"; "/dev/sda1"];
2970        ["zero"; "/dev/sda1"];
2971        ["file"; "/dev/sda1"]], "data")],
2972    "write zeroes to the device",
2973    "\
2974 This command writes zeroes over the first few blocks of C<device>.
2975
2976 How many blocks are zeroed isn't specified (but it's I<not> enough
2977 to securely wipe the device).  It should be sufficient to remove
2978 any partition tables, filesystem superblocks and so on.
2979
2980 See also: C<guestfs_zero_device>, C<guestfs_scrub_device>.");
2981
2982   ("grub_install", (RErr, [Pathname "root"; Device "device"], []), 86, [],
2983    (* See:
2984     * https://bugzilla.redhat.com/show_bug.cgi?id=484986
2985     * https://bugzilla.redhat.com/show_bug.cgi?id=479760
2986     *)
2987    [InitBasicFS, Always, TestOutputTrue (
2988       [["mkdir_p"; "/boot/grub"];
2989        ["write"; "/boot/grub/device.map"; "(hd0) /dev/vda"];
2990        ["grub_install"; "/"; "/dev/vda"];
2991        ["is_dir"; "/boot"]])],
2992    "install GRUB",
2993    "\
2994 This command installs GRUB (the Grand Unified Bootloader) on
2995 C<device>, with the root directory being C<root>.
2996
2997 Note: If grub-install reports the error
2998 \"No suitable drive was found in the generated device map.\"
2999 it may be that you need to create a C</boot/grub/device.map>
3000 file first that contains the mapping between grub device names
3001 and Linux device names.  It is usually sufficient to create
3002 a file containing:
3003
3004  (hd0) /dev/vda
3005
3006 replacing C</dev/vda> with the name of the installation device.");
3007
3008   ("cp", (RErr, [Pathname "src"; Pathname "dest"], []), 87, [],
3009    [InitScratchFS, Always, TestOutput (
3010       [["mkdir"; "/cp"];
3011        ["write"; "/cp/old"; "file content"];
3012        ["cp"; "/cp/old"; "/cp/new"];
3013        ["cat"; "/cp/new"]], "file content");
3014     InitScratchFS, Always, TestOutputTrue (
3015       [["mkdir"; "/cp2"];
3016        ["write"; "/cp2/old"; "file content"];
3017        ["cp"; "/cp2/old"; "/cp2/new"];
3018        ["is_file"; "/cp2/old"]]);
3019     InitScratchFS, Always, TestOutput (
3020       [["mkdir"; "/cp3"];
3021        ["write"; "/cp3/old"; "file content"];
3022        ["mkdir"; "/cp3/dir"];
3023        ["cp"; "/cp3/old"; "/cp3/dir/new"];
3024        ["cat"; "/cp3/dir/new"]], "file content")],
3025    "copy a file",
3026    "\
3027 This copies a file from C<src> to C<dest> where C<dest> is
3028 either a destination filename or destination directory.");
3029
3030   ("cp_a", (RErr, [Pathname "src"; Pathname "dest"], []), 88, [],
3031    [InitScratchFS, Always, TestOutput (
3032       [["mkdir"; "/cp_a1"];
3033        ["mkdir"; "/cp_a2"];
3034        ["write"; "/cp_a1/file"; "file content"];
3035        ["cp_a"; "/cp_a1"; "/cp_a2"];
3036        ["cat"; "/cp_a2/cp_a1/file"]], "file content")],
3037    "copy a file or directory recursively",
3038    "\
3039 This copies a file or directory from C<src> to C<dest>
3040 recursively using the C<cp -a> command.");
3041
3042   ("mv", (RErr, [Pathname "src"; Pathname "dest"], []), 89, [],
3043    [InitScratchFS, Always, TestOutput (
3044       [["mkdir"; "/mv"];
3045        ["write"; "/mv/old"; "file content"];
3046        ["mv"; "/mv/old"; "/mv/new"];
3047        ["cat"; "/mv/new"]], "file content");
3048     InitScratchFS, Always, TestOutputFalse (
3049       [["mkdir"; "/mv2"];
3050        ["write"; "/mv2/old"; "file content"];
3051        ["mv"; "/mv2/old"; "/mv2/new"];
3052        ["is_file"; "/mv2/old"]])],
3053    "move a file",
3054    "\
3055 This moves a file from C<src> to C<dest> where C<dest> is
3056 either a destination filename or destination directory.");
3057
3058   ("drop_caches", (RErr, [Int "whattodrop"], []), 90, [],
3059    [InitEmpty, Always, TestRun (
3060       [["drop_caches"; "3"]])],
3061    "drop kernel page cache, dentries and inodes",
3062    "\
3063 This instructs the guest kernel to drop its page cache,
3064 and/or dentries and inode caches.  The parameter C<whattodrop>
3065 tells the kernel what precisely to drop, see
3066 L<http://linux-mm.org/Drop_Caches>
3067
3068 Setting C<whattodrop> to 3 should drop everything.
3069
3070 This automatically calls L<sync(2)> before the operation,
3071 so that the maximum guest memory is freed.");
3072
3073   ("dmesg", (RString "kmsgs", [], []), 91, [],
3074    [InitEmpty, Always, TestRun (
3075       [["dmesg"]])],
3076    "return kernel messages",
3077    "\
3078 This returns the kernel messages (C<dmesg> output) from
3079 the guest kernel.  This is sometimes useful for extended
3080 debugging of problems.
3081
3082 Another way to get the same information is to enable
3083 verbose messages with C<guestfs_set_verbose> or by setting
3084 the environment variable C<LIBGUESTFS_DEBUG=1> before
3085 running the program.");
3086
3087   ("ping_daemon", (RErr, [], []), 92, [],
3088    [InitEmpty, Always, TestRun (
3089       [["ping_daemon"]])],
3090    "ping the guest daemon",
3091    "\
3092 This is a test probe into the guestfs daemon running inside
3093 the qemu subprocess.  Calling this function checks that the
3094 daemon responds to the ping message, without affecting the daemon
3095 or attached block device(s) in any other way.");
3096
3097   ("equal", (RBool "equality", [Pathname "file1"; Pathname "file2"], []), 93, [],
3098    [InitScratchFS, Always, TestOutputTrue (
3099       [["mkdir"; "/equal"];
3100        ["write"; "/equal/file1"; "contents of a file"];
3101        ["cp"; "/equal/file1"; "/equal/file2"];
3102        ["equal"; "/equal/file1"; "/equal/file2"]]);
3103     InitScratchFS, Always, TestOutputFalse (
3104       [["mkdir"; "/equal2"];
3105        ["write"; "/equal2/file1"; "contents of a file"];
3106        ["write"; "/equal2/file2"; "contents of another file"];
3107        ["equal"; "/equal2/file1"; "/equal2/file2"]]);
3108     InitScratchFS, Always, TestLastFail (
3109       [["mkdir"; "/equal3"];
3110        ["equal"; "/equal3/file1"; "/equal3/file2"]])],
3111    "test if two files have equal contents",
3112    "\
3113 This compares the two files C<file1> and C<file2> and returns
3114 true if their content is exactly equal, or false otherwise.
3115
3116 The external L<cmp(1)> program is used for the comparison.");
3117
3118   ("strings", (RStringList "stringsout", [Pathname "path"], []), 94, [ProtocolLimitWarning],
3119    [InitISOFS, Always, TestOutputList (
3120       [["strings"; "/known-5"]], ["abcdefghi"; "jklmnopqr"]);
3121     InitISOFS, Always, TestOutputList (
3122       [["strings"; "/empty"]], []);
3123     (* Test for RHBZ#579608, absolute symbolic links. *)
3124     InitISOFS, Always, TestRun (
3125       [["strings"; "/abssymlink"]])],
3126    "print the printable strings in a file",
3127    "\
3128 This runs the L<strings(1)> command on a file and returns
3129 the list of printable strings found.");
3130
3131   ("strings_e", (RStringList "stringsout", [String "encoding"; Pathname "path"], []), 95, [ProtocolLimitWarning],
3132    [InitISOFS, Always, TestOutputList (
3133       [["strings_e"; "b"; "/known-5"]], []);
3134     InitScratchFS, Always, TestOutputList (
3135       [["write"; "/strings_e"; "\000h\000e\000l\000l\000o\000\n\000w\000o\000r\000l\000d\000\n"];
3136        ["strings_e"; "b"; "/strings_e"]], ["hello"; "world"])],
3137    "print the printable strings in a file",
3138    "\
3139 This is like the C<guestfs_strings> command, but allows you to
3140 specify the encoding of strings that are looked for in
3141 the source file C<path>.
3142
3143 Allowed encodings are:
3144
3145 =over 4
3146
3147 =item s
3148
3149 Single 7-bit-byte characters like ASCII and the ASCII-compatible
3150 parts of ISO-8859-X (this is what C<guestfs_strings> uses).
3151
3152 =item S
3153
3154 Single 8-bit-byte characters.
3155
3156 =item b
3157
3158 16-bit big endian strings such as those encoded in
3159 UTF-16BE or UCS-2BE.
3160
3161 =item l (lower case letter L)
3162
3163 16-bit little endian such as UTF-16LE and UCS-2LE.
3164 This is useful for examining binaries in Windows guests.
3165
3166 =item B
3167
3168 32-bit big endian such as UCS-4BE.
3169
3170 =item L
3171
3172 32-bit little endian such as UCS-4LE.
3173
3174 =back
3175
3176 The returned strings are transcoded to UTF-8.");
3177
3178   ("hexdump", (RString "dump", [Pathname "path"], []), 96, [ProtocolLimitWarning],
3179    [InitISOFS, Always, TestOutput (
3180       [["hexdump"; "/known-4"]], "00000000  61 62 63 0a 64 65 66 0a  67 68 69                 |abc.def.ghi|\n0000000b\n");
3181     (* Test for RHBZ#501888c2 regression which caused large hexdump
3182      * commands to segfault.
3183      *)
3184     InitISOFS, Always, TestRun (
3185       [["hexdump"; "/100krandom"]]);
3186     (* Test for RHBZ#579608, absolute symbolic links. *)
3187     InitISOFS, Always, TestRun (
3188       [["hexdump"; "/abssymlink"]])],
3189    "dump a file in hexadecimal",
3190    "\
3191 This runs C<hexdump -C> on the given C<path>.  The result is
3192 the human-readable, canonical hex dump of the file.");
3193
3194   ("zerofree", (RErr, [Device "device"], []), 97, [Optional "zerofree"],
3195    [InitNone, Always, TestOutput (
3196       [["part_disk"; "/dev/sda"; "mbr"];
3197        ["mkfs"; "ext3"; "/dev/sda1"];
3198        ["mount_options"; ""; "/dev/sda1"; "/"];
3199        ["write"; "/new"; "test file"];
3200        ["umount"; "/dev/sda1"];
3201        ["zerofree"; "/dev/sda1"];
3202        ["mount_options"; ""; "/dev/sda1"; "/"];
3203        ["cat"; "/new"]], "test file")],
3204    "zero unused inodes and disk blocks on ext2/3 filesystem",
3205    "\
3206 This runs the I<zerofree> program on C<device>.  This program
3207 claims to zero unused inodes and disk blocks on an ext2/3
3208 filesystem, thus making it possible to compress the filesystem
3209 more effectively.
3210
3211 You should B<not> run this program if the filesystem is
3212 mounted.
3213
3214 It is possible that using this program can damage the filesystem
3215 or data on the filesystem.");
3216
3217   ("pvresize", (RErr, [Device "device"], []), 98, [Optional "lvm2"],
3218    [],
3219    "resize an LVM physical volume",
3220    "\
3221 This resizes (expands or shrinks) an existing LVM physical
3222 volume to match the new size of the underlying device.");
3223
3224   ("sfdisk_N", (RErr, [Device "device"; Int "partnum";
3225                        Int "cyls"; Int "heads"; Int "sectors";
3226                        String "line"], []), 99, [DangerWillRobinson],
3227    [],
3228    "modify a single partition on a block device",
3229    "\
3230 This runs L<sfdisk(8)> option to modify just the single
3231 partition C<n> (note: C<n> counts from 1).
3232
3233 For other parameters, see C<guestfs_sfdisk>.  You should usually
3234 pass C<0> for the cyls/heads/sectors parameters.
3235
3236 See also: C<guestfs_part_add>");
3237
3238   ("sfdisk_l", (RString "partitions", [Device "device"], []), 100, [],
3239    [],
3240    "display the partition table",
3241    "\
3242 This displays the partition table on C<device>, in the
3243 human-readable output of the L<sfdisk(8)> command.  It is
3244 not intended to be parsed.
3245
3246 See also: C<guestfs_part_list>");
3247
3248   ("sfdisk_kernel_geometry", (RString "partitions", [Device "device"], []), 101, [],
3249    [],
3250    "display the kernel geometry",
3251    "\
3252 This displays the kernel's idea of the geometry of C<device>.
3253
3254 The result is in human-readable format, and not designed to
3255 be parsed.");
3256
3257   ("sfdisk_disk_geometry", (RString "partitions", [Device "device"], []), 102, [],
3258    [],
3259    "display the disk geometry from the partition table",
3260    "\
3261 This displays the disk geometry of C<device> read from the
3262 partition table.  Especially in the case where the underlying
3263 block device has been resized, this can be different from the
3264 kernel's idea of the geometry (see C<guestfs_sfdisk_kernel_geometry>).
3265
3266 The result is in human-readable format, and not designed to
3267 be parsed.");
3268
3269   ("vg_activate_all", (RErr, [Bool "activate"], []), 103, [Optional "lvm2"],
3270    [],
3271    "activate or deactivate all volume groups",
3272    "\
3273 This command activates or (if C<activate> is false) deactivates
3274 all logical volumes in all volume groups.
3275 If activated, then they are made known to the
3276 kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
3277 then those devices disappear.
3278
3279 This command is the same as running C<vgchange -a y|n>");
3280
3281   ("vg_activate", (RErr, [Bool "activate"; StringList "volgroups"], []), 104, [Optional "lvm2"],
3282    [],
3283    "activate or deactivate some volume groups",
3284    "\
3285 This command activates or (if C<activate> is false) deactivates
3286 all logical volumes in the listed volume groups C<volgroups>.
3287 If activated, then they are made known to the
3288 kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
3289 then those devices disappear.
3290
3291 This command is the same as running C<vgchange -a y|n volgroups...>
3292
3293 Note that if C<volgroups> is an empty list then B<all> volume groups
3294 are activated or deactivated.");
3295
3296   ("lvresize", (RErr, [Device "device"; Int "mbytes"], []), 105, [Optional "lvm2"],
3297    [InitNone, Always, TestOutput (
3298       [["part_disk"; "/dev/sda"; "mbr"];
3299        ["pvcreate"; "/dev/sda1"];
3300        ["vgcreate"; "VG"; "/dev/sda1"];
3301        ["lvcreate"; "LV"; "VG"; "10"];
3302        ["mkfs"; "ext2"; "/dev/VG/LV"];
3303        ["mount_options"; ""; "/dev/VG/LV"; "/"];
3304        ["write"; "/new"; "test content"];
3305        ["umount"; "/"];
3306        ["lvresize"; "/dev/VG/LV"; "20"];
3307        ["e2fsck_f"; "/dev/VG/LV"];
3308        ["resize2fs"; "/dev/VG/LV"];
3309        ["mount_options"; ""; "/dev/VG/LV"; "/"];
3310        ["cat"; "/new"]], "test content");
3311     InitNone, Always, TestRun (
3312       (* Make an LV smaller to test RHBZ#587484. *)
3313       [["part_disk"; "/dev/sda"; "mbr"];
3314        ["pvcreate"; "/dev/sda1"];
3315        ["vgcreate"; "VG"; "/dev/sda1"];
3316        ["lvcreate"; "LV"; "VG"; "20"];
3317        ["lvresize"; "/dev/VG/LV"; "10"]])],
3318    "resize an LVM logical volume",
3319    "\
3320 This resizes (expands or shrinks) an existing LVM logical
3321 volume to C<mbytes>.  When reducing, data in the reduced part
3322 is lost.");
3323
3324   ("resize2fs", (RErr, [Device "device"], []), 106, [],
3325    [], (* lvresize tests this *)
3326    "resize an ext2, ext3 or ext4 filesystem",
3327    "\
3328 This resizes an ext2, ext3 or ext4 filesystem to match the size of
3329 the underlying device.
3330
3331 I<Note:> It is sometimes required that you run C<guestfs_e2fsck_f>
3332 on the C<device> before calling this command.  For unknown reasons
3333 C<resize2fs> sometimes gives an error about this and sometimes not.
3334 In any case, it is always safe to call C<guestfs_e2fsck_f> before
3335 calling this function.");
3336
3337   ("find", (RStringList "names", [Pathname "directory"], []), 107, [ProtocolLimitWarning],
3338    [InitBasicFS, Always, TestOutputList (
3339       [["find"; "/"]], ["lost+found"]);
3340     InitBasicFS, Always, TestOutputList (
3341       [["touch"; "/a"];
3342        ["mkdir"; "/b"];
3343        ["touch"; "/b/c"];
3344        ["find"; "/"]], ["a"; "b"; "b/c"; "lost+found"]);
3345     InitScratchFS, Always, TestOutputList (
3346       [["mkdir_p"; "/find/b/c"];
3347        ["touch"; "/find/b/c/d"];
3348        ["find"; "/find/b/"]], ["c"; "c/d"])],
3349    "find all files and directories",
3350    "\
3351 This command lists out all files and directories, recursively,
3352 starting at C<directory>.  It is essentially equivalent to
3353 running the shell command C<find directory -print> but some
3354 post-processing happens on the output, described below.
3355
3356 This returns a list of strings I<without any prefix>.  Thus
3357 if the directory structure was:
3358
3359  /tmp/a
3360  /tmp/b
3361  /tmp/c/d
3362
3363 then the returned list from C<guestfs_find> C</tmp> would be
3364 4 elements:
3365
3366  a
3367  b
3368  c
3369  c/d
3370
3371 If C<directory> is not a directory, then this command returns
3372 an error.
3373
3374 The returned list is sorted.
3375
3376 See also C<guestfs_find0>.");
3377
3378   ("e2fsck_f", (RErr, [Device "device"], []), 108, [],
3379    [], (* lvresize tests this *)
3380    "check an ext2/ext3 filesystem",
3381    "\
3382 This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3
3383 filesystem checker on C<device>, noninteractively (C<-p>),
3384 even if the filesystem appears to be clean (C<-f>).
3385
3386 This command is only needed because of C<guestfs_resize2fs>
3387 (q.v.).  Normally you should use C<guestfs_fsck>.");
3388
3389   ("sleep", (RErr, [Int "secs"], []), 109, [],
3390    [InitNone, Always, TestRun (
3391       [["sleep"; "1"]])],
3392    "sleep for some seconds",
3393    "\
3394 Sleep for C<secs> seconds.");
3395
3396   ("ntfs_3g_probe", (RInt "status", [Bool "rw"; Device "device"], []), 110, [Optional "ntfs3g"],
3397    [InitNone, Always, TestOutputInt (
3398       [["part_disk"; "/dev/sda"; "mbr"];
3399        ["mkfs"; "ntfs"; "/dev/sda1"];
3400        ["ntfs_3g_probe"; "true"; "/dev/sda1"]], 0);
3401     InitNone, Always, TestOutputInt (
3402       [["part_disk"; "/dev/sda"; "mbr"];
3403        ["mkfs"; "ext2"; "/dev/sda1"];
3404        ["ntfs_3g_probe"; "true"; "/dev/sda1"]], 12)],
3405    "probe NTFS volume",
3406    "\
3407 This command runs the L<ntfs-3g.probe(8)> command which probes
3408 an NTFS C<device> for mountability.  (Not all NTFS volumes can
3409 be mounted read-write, and some cannot be mounted at all).
3410
3411 C<rw> is a boolean flag.  Set it to true if you want to test
3412 if the volume can be mounted read-write.  Set it to false if
3413 you want to test if the volume can be mounted read-only.
3414
3415 The return value is an integer which C<0> if the operation
3416 would succeed, or some non-zero value documented in the
3417 L<ntfs-3g.probe(8)> manual page.");
3418
3419   ("sh", (RString "output", [String "command"], []), 111, [],
3420    [], (* XXX needs tests *)
3421    "run a command via the shell",
3422    "\
3423 This call runs a command from the guest filesystem via the
3424 guest's C</bin/sh>.
3425
3426 This is like C<guestfs_command>, but passes the command to:
3427
3428  /bin/sh -c \"command\"
3429
3430 Depending on the guest's shell, this usually results in
3431 wildcards being expanded, shell expressions being interpolated
3432 and so on.
3433
3434 All the provisos about C<guestfs_command> apply to this call.");
3435
3436   ("sh_lines", (RStringList "lines", [String "command"], []), 112, [],
3437    [], (* XXX needs tests *)
3438    "run a command via the shell returning lines",
3439    "\
3440 This is the same as C<guestfs_sh>, but splits the result
3441 into a list of lines.
3442
3443 See also: C<guestfs_command_lines>");
3444
3445   ("glob_expand", (RStringList "paths", [Pathname "pattern"], []), 113, [],
3446    (* Use Pathname here, and hence ABS_PATH (pattern,... in generated
3447     * code in stubs.c, since all valid glob patterns must start with "/".
3448     * There is no concept of "cwd" in libguestfs, hence no "."-relative names.
3449     *)
3450    [InitScratchFS, Always, TestOutputList (
3451       [["mkdir_p"; "/glob_expand/b/c"];
3452        ["touch"; "/glob_expand/b/c/d"];
3453        ["touch"; "/glob_expand/b/c/e"];
3454        ["glob_expand"; "/glob_expand/b/c/*"]], ["/glob_expand/b/c/d"; "/glob_expand/b/c/e"]);
3455     InitScratchFS, Always, TestOutputList (
3456       [["mkdir_p"; "/glob_expand2/b/c"];
3457        ["touch"; "/glob_expand2/b/c/d"];
3458        ["touch"; "/glob_expand2/b/c/e"];
3459        ["glob_expand"; "/glob_expand2/*/c/*"]], ["/glob_expand2/b/c/d"; "/glob_expand2/b/c/e"]);
3460     InitScratchFS, Always, TestOutputList (
3461       [["mkdir_p"; "/glob_expand3/b/c"];
3462        ["touch"; "/glob_expand3/b/c/d"];
3463        ["touch"; "/glob_expand3/b/c/e"];
3464        ["glob_expand"; "/glob_expand3/*/x/*"]], [])],
3465    "expand a wildcard path",
3466    "\
3467 This command searches for all the pathnames matching
3468 C<pattern> according to the wildcard expansion rules
3469 used by the shell.
3470
3471 If no paths match, then this returns an empty list
3472 (note: not an error).
3473
3474 It is just a wrapper around the C L<glob(3)> function
3475 with flags C<GLOB_MARK|GLOB_BRACE>.
3476 See that manual page for more details.");
3477
3478   ("scrub_device", (RErr, [Device "device"], []), 114, [DangerWillRobinson; Optional "scrub"],
3479    [InitNone, Always, TestRun ( (* use /dev/sdc because it's smaller *)
3480       [["scrub_device"; "/dev/sdc"]])],
3481    "scrub (securely wipe) a device",
3482    "\
3483 This command writes patterns over C<device> to make data retrieval
3484 more difficult.
3485
3486 It is an interface to the L<scrub(1)> program.  See that
3487 manual page for more details.");
3488
3489   ("scrub_file", (RErr, [Pathname "file"], []), 115, [Optional "scrub"],
3490    [InitScratchFS, Always, TestRun (
3491       [["write"; "/scrub_file"; "content"];
3492        ["scrub_file"; "/scrub_file"]])],
3493    "scrub (securely wipe) a file",
3494    "\
3495 This command writes patterns over a file to make data retrieval
3496 more difficult.
3497
3498 The file is I<removed> after scrubbing.
3499
3500 It is an interface to the L<scrub(1)> program.  See that
3501 manual page for more details.");
3502
3503   ("scrub_freespace", (RErr, [Pathname "dir"], []), 116, [Optional "scrub"],
3504    [], (* XXX needs testing *)
3505    "scrub (securely wipe) free space",
3506    "\
3507 This command creates the directory C<dir> and then fills it
3508 with files until the filesystem is full, and scrubs the files
3509 as for C<guestfs_scrub_file>, and deletes them.
3510 The intention is to scrub any free space on the partition
3511 containing C<dir>.
3512
3513 It is an interface to the L<scrub(1)> program.  See that
3514 manual page for more details.");
3515
3516   ("mkdtemp", (RString "dir", [Pathname "template"], []), 117, [],
3517    [InitScratchFS, Always, TestRun (
3518       [["mkdir"; "/mkdtemp"];
3519        ["mkdtemp"; "/mkdtemp/tmpXXXXXX"]])],
3520    "create a temporary directory",
3521    "\
3522 This command creates a temporary directory.  The
3523 C<template> parameter should be a full pathname for the
3524 temporary directory name with the final six characters being
3525 \"XXXXXX\".
3526
3527 For example: \"/tmp/myprogXXXXXX\" or \"/Temp/myprogXXXXXX\",
3528 the second one being suitable for Windows filesystems.
3529
3530 The name of the temporary directory that was created
3531 is returned.
3532
3533 The temporary directory is created with mode 0700
3534 and is owned by root.
3535
3536 The caller is responsible for deleting the temporary
3537 directory and its contents after use.
3538
3539 See also: L<mkdtemp(3)>");
3540
3541   ("wc_l", (RInt "lines", [Pathname "path"], []), 118, [],
3542    [InitISOFS, Always, TestOutputInt (
3543       [["wc_l"; "/10klines"]], 10000);
3544     (* Test for RHBZ#579608, absolute symbolic links. *)
3545     InitISOFS, Always, TestOutputInt (
3546       [["wc_l"; "/abssymlink"]], 10000)],
3547    "count lines in a file",
3548    "\
3549 This command counts the lines in a file, using the
3550 C<wc -l> external command.");
3551
3552   ("wc_w", (RInt "words", [Pathname "path"], []), 119, [],
3553    [InitISOFS, Always, TestOutputInt (
3554       [["wc_w"; "/10klines"]], 10000)],
3555    "count words in a file",
3556    "\
3557 This command counts the words in a file, using the
3558 C<wc -w> external command.");
3559
3560   ("wc_c", (RInt "chars", [Pathname "path"], []), 120, [],
3561    [InitISOFS, Always, TestOutputInt (
3562       [["wc_c"; "/100kallspaces"]], 102400)],
3563    "count characters in a file",
3564    "\
3565 This command counts the characters in a file, using the
3566 C<wc -c> external command.");
3567
3568   ("head", (RStringList "lines", [Pathname "path"], []), 121, [ProtocolLimitWarning],
3569    [InitISOFS, Always, TestOutputList (
3570       [["head"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz";"3abcdefghijklmnopqrstuvwxyz";"4abcdefghijklmnopqrstuvwxyz";"5abcdefghijklmnopqrstuvwxyz";"6abcdefghijklmnopqrstuvwxyz";"7abcdefghijklmnopqrstuvwxyz";"8abcdefghijklmnopqrstuvwxyz";"9abcdefghijklmnopqrstuvwxyz"]);
3571     (* Test for RHBZ#579608, absolute symbolic links. *)
3572     InitISOFS, Always, TestOutputList (
3573       [["head"; "/abssymlink"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz";"3abcdefghijklmnopqrstuvwxyz";"4abcdefghijklmnopqrstuvwxyz";"5abcdefghijklmnopqrstuvwxyz";"6abcdefghijklmnopqrstuvwxyz";"7abcdefghijklmnopqrstuvwxyz";"8abcdefghijklmnopqrstuvwxyz";"9abcdefghijklmnopqrstuvwxyz"])],
3574    "return first 10 lines of a file",
3575    "\
3576 This command returns up to the first 10 lines of a file as
3577 a list of strings.");
3578
3579   ("head_n", (RStringList "lines", [Int "nrlines"; Pathname "path"], []), 122, [ProtocolLimitWarning],
3580    [InitISOFS, Always, TestOutputList (
3581       [["head_n"; "3"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz"]);
3582     InitISOFS, Always, TestOutputList (
3583       [["head_n"; "-9997"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz"]);
3584     InitISOFS, Always, TestOutputList (
3585       [["head_n"; "0"; "/10klines"]], [])],
3586    "return first N lines of a file",
3587    "\
3588 If the parameter C<nrlines> is a positive number, this returns the first
3589 C<nrlines> lines of the file C<path>.
3590
3591 If the parameter C<nrlines> is a negative number, this returns lines
3592 from the file C<path>, excluding the last C<nrlines> lines.
3593
3594 If the parameter C<nrlines> is zero, this returns an empty list.");
3595
3596   ("tail", (RStringList "lines", [Pathname "path"], []), 123, [ProtocolLimitWarning],
3597    [InitISOFS, Always, TestOutputList (
3598       [["tail"; "/10klines"]], ["9990abcdefghijklmnopqrstuvwxyz