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