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