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