85e5c02f228a40eaf34c51d05199d751783cb940
[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     (* Test for RHBZ#501888c2 regression which caused large hexdump
2136      * commands to segfault.
2137      *)
2138     InitBasicFS, Always, TestRun (
2139       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2140        ["hexdump"; "/100krandom"]])],
2141    "dump a file in hexadecimal",
2142    "\
2143 This runs C<hexdump -C> on the given C<path>.  The result is
2144 the human-readable, canonical hex dump of the file.");
2145
2146   ("zerofree", (RErr, [String "device"]), 97, [],
2147    [InitNone, Always, TestOutput (
2148       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
2149        ["mkfs"; "ext3"; "/dev/sda1"];
2150        ["mount"; "/dev/sda1"; "/"];
2151        ["write_file"; "/new"; "test file"; "0"];
2152        ["umount"; "/dev/sda1"];
2153        ["zerofree"; "/dev/sda1"];
2154        ["mount"; "/dev/sda1"; "/"];
2155        ["cat"; "/new"]], "test file")],
2156    "zero unused inodes and disk blocks on ext2/3 filesystem",
2157    "\
2158 This runs the I<zerofree> program on C<device>.  This program
2159 claims to zero unused inodes and disk blocks on an ext2/3
2160 filesystem, thus making it possible to compress the filesystem
2161 more effectively.
2162
2163 You should B<not> run this program if the filesystem is
2164 mounted.
2165
2166 It is possible that using this program can damage the filesystem
2167 or data on the filesystem.");
2168
2169   ("pvresize", (RErr, [String "device"]), 98, [],
2170    [],
2171    "resize an LVM physical volume",
2172    "\
2173 This resizes (expands or shrinks) an existing LVM physical
2174 volume to match the new size of the underlying device.");
2175
2176   ("sfdisk_N", (RErr, [String "device"; Int "partnum";
2177                        Int "cyls"; Int "heads"; Int "sectors";
2178                        String "line"]), 99, [DangerWillRobinson],
2179    [],
2180    "modify a single partition on a block device",
2181    "\
2182 This runs L<sfdisk(8)> option to modify just the single
2183 partition C<n> (note: C<n> counts from 1).
2184
2185 For other parameters, see C<guestfs_sfdisk>.  You should usually
2186 pass C<0> for the cyls/heads/sectors parameters.");
2187
2188   ("sfdisk_l", (RString "partitions", [String "device"]), 100, [],
2189    [],
2190    "display the partition table",
2191    "\
2192 This displays the partition table on C<device>, in the
2193 human-readable output of the L<sfdisk(8)> command.  It is
2194 not intended to be parsed.");
2195
2196   ("sfdisk_kernel_geometry", (RString "partitions", [String "device"]), 101, [],
2197    [],
2198    "display the kernel geometry",
2199    "\
2200 This displays the kernel's idea of the geometry of C<device>.
2201
2202 The result is in human-readable format, and not designed to
2203 be parsed.");
2204
2205   ("sfdisk_disk_geometry", (RString "partitions", [String "device"]), 102, [],
2206    [],
2207    "display the disk geometry from the partition table",
2208    "\
2209 This displays the disk geometry of C<device> read from the
2210 partition table.  Especially in the case where the underlying
2211 block device has been resized, this can be different from the
2212 kernel's idea of the geometry (see C<guestfs_sfdisk_kernel_geometry>).
2213
2214 The result is in human-readable format, and not designed to
2215 be parsed.");
2216
2217   ("vg_activate_all", (RErr, [Bool "activate"]), 103, [],
2218    [],
2219    "activate or deactivate all volume groups",
2220    "\
2221 This command activates or (if C<activate> is false) deactivates
2222 all logical volumes in all volume groups.
2223 If activated, then they are made known to the
2224 kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
2225 then those devices disappear.
2226
2227 This command is the same as running C<vgchange -a y|n>");
2228
2229   ("vg_activate", (RErr, [Bool "activate"; StringList "volgroups"]), 104, [],
2230    [],
2231    "activate or deactivate some volume groups",
2232    "\
2233 This command activates or (if C<activate> is false) deactivates
2234 all logical volumes in the listed volume groups C<volgroups>.
2235 If activated, then they are made known to the
2236 kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
2237 then those devices disappear.
2238
2239 This command is the same as running C<vgchange -a y|n volgroups...>
2240
2241 Note that if C<volgroups> is an empty list then B<all> volume groups
2242 are activated or deactivated.");
2243
2244   ("lvresize", (RErr, [String "device"; Int "mbytes"]), 105, [],
2245    [InitNone, Always, TestOutput (
2246     [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
2247      ["pvcreate"; "/dev/sda1"];
2248      ["vgcreate"; "VG"; "/dev/sda1"];
2249      ["lvcreate"; "LV"; "VG"; "10"];
2250      ["mkfs"; "ext2"; "/dev/VG/LV"];
2251      ["mount"; "/dev/VG/LV"; "/"];
2252      ["write_file"; "/new"; "test content"; "0"];
2253      ["umount"; "/"];
2254      ["lvresize"; "/dev/VG/LV"; "20"];
2255      ["e2fsck_f"; "/dev/VG/LV"];
2256      ["resize2fs"; "/dev/VG/LV"];
2257      ["mount"; "/dev/VG/LV"; "/"];
2258      ["cat"; "/new"]], "test content")],
2259    "resize an LVM logical volume",
2260    "\
2261 This resizes (expands or shrinks) an existing LVM logical
2262 volume to C<mbytes>.  When reducing, data in the reduced part
2263 is lost.");
2264
2265   ("resize2fs", (RErr, [String "device"]), 106, [],
2266    [], (* lvresize tests this *)
2267    "resize an ext2/ext3 filesystem",
2268    "\
2269 This resizes an ext2 or ext3 filesystem to match the size of
2270 the underlying device.
2271
2272 I<Note:> It is sometimes required that you run C<guestfs_e2fsck_f>
2273 on the C<device> before calling this command.  For unknown reasons
2274 C<resize2fs> sometimes gives an error about this and sometimes not.
2275 In any case, it is always safe to call C<guestfs_e2fsck_f> before
2276 calling this function.");
2277
2278   ("find", (RStringList "names", [String "directory"]), 107, [],
2279    [InitBasicFS, Always, TestOutputList (
2280       [["find"; "/"]], ["lost+found"]);
2281     InitBasicFS, Always, TestOutputList (
2282       [["touch"; "/a"];
2283        ["mkdir"; "/b"];
2284        ["touch"; "/b/c"];
2285        ["find"; "/"]], ["a"; "b"; "b/c"; "lost+found"]);
2286     InitBasicFS, Always, TestOutputList (
2287       [["mkdir_p"; "/a/b/c"];
2288        ["touch"; "/a/b/c/d"];
2289        ["find"; "/a/b/"]], ["c"; "c/d"])],
2290    "find all files and directories",
2291    "\
2292 This command lists out all files and directories, recursively,
2293 starting at C<directory>.  It is essentially equivalent to
2294 running the shell command C<find directory -print> but some
2295 post-processing happens on the output, described below.
2296
2297 This returns a list of strings I<without any prefix>.  Thus
2298 if the directory structure was:
2299
2300  /tmp/a
2301  /tmp/b
2302  /tmp/c/d
2303
2304 then the returned list from C<guestfs_find> C</tmp> would be
2305 4 elements:
2306
2307  a
2308  b
2309  c
2310  c/d
2311
2312 If C<directory> is not a directory, then this command returns
2313 an error.
2314
2315 The returned list is sorted.");
2316
2317   ("e2fsck_f", (RErr, [String "device"]), 108, [],
2318    [], (* lvresize tests this *)
2319    "check an ext2/ext3 filesystem",
2320    "\
2321 This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3
2322 filesystem checker on C<device>, noninteractively (C<-p>),
2323 even if the filesystem appears to be clean (C<-f>).
2324
2325 This command is only needed because of C<guestfs_resize2fs>
2326 (q.v.).  Normally you should use C<guestfs_fsck>.");
2327
2328   ("sleep", (RErr, [Int "secs"]), 109, [],
2329    [InitNone, Always, TestRun (
2330     [["sleep"; "1"]])],
2331    "sleep for some seconds",
2332    "\
2333 Sleep for C<secs> seconds.");
2334
2335   ("ntfs_3g_probe", (RInt "status", [Bool "rw"; String "device"]), 110, [],
2336    [InitNone, Always, TestOutputInt (
2337       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
2338        ["mkfs"; "ntfs"; "/dev/sda1"];
2339        ["ntfs_3g_probe"; "true"; "/dev/sda1"]], 0);
2340     InitNone, Always, TestOutputInt (
2341       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
2342        ["mkfs"; "ext2"; "/dev/sda1"];
2343        ["ntfs_3g_probe"; "true"; "/dev/sda1"]], 12)],
2344    "probe NTFS volume",
2345    "\
2346 This command runs the L<ntfs-3g.probe(8)> command which probes
2347 an NTFS C<device> for mountability.  (Not all NTFS volumes can
2348 be mounted read-write, and some cannot be mounted at all).
2349
2350 C<rw> is a boolean flag.  Set it to true if you want to test
2351 if the volume can be mounted read-write.  Set it to false if
2352 you want to test if the volume can be mounted read-only.
2353
2354 The return value is an integer which C<0> if the operation
2355 would succeed, or some non-zero value documented in the
2356 L<ntfs-3g.probe(8)> manual page.");
2357
2358   ("sh", (RString "output", [String "command"]), 111, [],
2359    [], (* XXX needs tests *)
2360    "run a command via the shell",
2361    "\
2362 This call runs a command from the guest filesystem via the
2363 guest's C</bin/sh>.
2364
2365 This is like C<guestfs_command>, but passes the command to:
2366
2367  /bin/sh -c \"command\"
2368
2369 Depending on the guest's shell, this usually results in
2370 wildcards being expanded, shell expressions being interpolated
2371 and so on.
2372
2373 All the provisos about C<guestfs_command> apply to this call.");
2374
2375   ("sh_lines", (RStringList "lines", [String "command"]), 112, [],
2376    [], (* XXX needs tests *)
2377    "run a command via the shell returning lines",
2378    "\
2379 This is the same as C<guestfs_sh>, but splits the result
2380 into a list of lines.
2381
2382 See also: C<guestfs_command_lines>");
2383
2384   ("glob_expand", (RStringList "paths", [String "pattern"]), 113, [],
2385    [InitBasicFS, Always, TestOutputList (
2386       [["mkdir_p"; "/a/b/c"];
2387        ["touch"; "/a/b/c/d"];
2388        ["touch"; "/a/b/c/e"];
2389        ["glob_expand"; "/a/b/c/*"]], ["/a/b/c/d"; "/a/b/c/e"]);
2390     InitBasicFS, Always, TestOutputList (
2391       [["mkdir_p"; "/a/b/c"];
2392        ["touch"; "/a/b/c/d"];
2393        ["touch"; "/a/b/c/e"];
2394        ["glob_expand"; "/a/*/c/*"]], ["/a/b/c/d"; "/a/b/c/e"]);
2395     InitBasicFS, Always, TestOutputList (
2396       [["mkdir_p"; "/a/b/c"];
2397        ["touch"; "/a/b/c/d"];
2398        ["touch"; "/a/b/c/e"];
2399        ["glob_expand"; "/a/*/x/*"]], [])],
2400    "expand a wildcard path",
2401    "\
2402 This command searches for all the pathnames matching
2403 C<pattern> according to the wildcard expansion rules
2404 used by the shell.
2405
2406 If no paths match, then this returns an empty list
2407 (note: not an error).
2408
2409 It is just a wrapper around the C L<glob(3)> function
2410 with flags C<GLOB_MARK|GLOB_BRACE>.
2411 See that manual page for more details.");
2412
2413   ("scrub_device", (RErr, [String "device"]), 114, [DangerWillRobinson],
2414    [InitNone, Always, TestRun ( (* use /dev/sdc because it's smaller *)
2415       [["scrub_device"; "/dev/sdc"]])],
2416    "scrub (securely wipe) a device",
2417    "\
2418 This command writes patterns over C<device> to make data retrieval
2419 more difficult.
2420
2421 It is an interface to the L<scrub(1)> program.  See that
2422 manual page for more details.");
2423
2424   ("scrub_file", (RErr, [String "file"]), 115, [],
2425    [InitBasicFS, Always, TestRun (
2426       [["write_file"; "/file"; "content"; "0"];
2427        ["scrub_file"; "/file"]])],
2428    "scrub (securely wipe) a file",
2429    "\
2430 This command writes patterns over a file to make data retrieval
2431 more difficult.
2432
2433 The file is I<removed> after scrubbing.
2434
2435 It is an interface to the L<scrub(1)> program.  See that
2436 manual page for more details.");
2437
2438   ("scrub_freespace", (RErr, [String "dir"]), 116, [],
2439    [], (* XXX needs testing *)
2440    "scrub (securely wipe) free space",
2441    "\
2442 This command creates the directory C<dir> and then fills it
2443 with files until the filesystem is full, and scrubs the files
2444 as for C<guestfs_scrub_file>, and deletes them.
2445 The intention is to scrub any free space on the partition
2446 containing C<dir>.
2447
2448 It is an interface to the L<scrub(1)> program.  See that
2449 manual page for more details.");
2450
2451   ("mkdtemp", (RString "dir", [String "template"]), 117, [],
2452    [InitBasicFS, Always, TestRun (
2453       [["mkdir"; "/tmp"];
2454        ["mkdtemp"; "/tmp/tmpXXXXXX"]])],
2455    "create a temporary directory",
2456    "\
2457 This command creates a temporary directory.  The
2458 C<template> parameter should be a full pathname for the
2459 temporary directory name with the final six characters being
2460 \"XXXXXX\".
2461
2462 For example: \"/tmp/myprogXXXXXX\" or \"/Temp/myprogXXXXXX\",
2463 the second one being suitable for Windows filesystems.
2464
2465 The name of the temporary directory that was created
2466 is returned.
2467
2468 The temporary directory is created with mode 0700
2469 and is owned by root.
2470
2471 The caller is responsible for deleting the temporary
2472 directory and its contents after use.
2473
2474 See also: L<mkdtemp(3)>");
2475
2476   ("wc_l", (RInt "lines", [String "path"]), 118, [],
2477    [InitBasicFS, Always, TestOutputInt (
2478       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2479        ["wc_l"; "/10klines"]], 10000)],
2480    "count lines in a file",
2481    "\
2482 This command counts the lines in a file, using the
2483 C<wc -l> external command.");
2484
2485   ("wc_w", (RInt "words", [String "path"]), 119, [],
2486    [InitBasicFS, Always, TestOutputInt (
2487       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2488        ["wc_w"; "/10klines"]], 10000)],
2489    "count words in a file",
2490    "\
2491 This command counts the words in a file, using the
2492 C<wc -w> external command.");
2493
2494   ("wc_c", (RInt "chars", [String "path"]), 120, [],
2495    [InitBasicFS, Always, TestOutputInt (
2496       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2497        ["wc_c"; "/100kallspaces"]], 102400)],
2498    "count characters in a file",
2499    "\
2500 This command counts the characters in a file, using the
2501 C<wc -c> external command.");
2502
2503   ("head", (RStringList "lines", [String "path"]), 121, [ProtocolLimitWarning],
2504    [InitBasicFS, Always, TestOutputList (
2505       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2506        ["head"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz";"3abcdefghijklmnopqrstuvwxyz";"4abcdefghijklmnopqrstuvwxyz";"5abcdefghijklmnopqrstuvwxyz";"6abcdefghijklmnopqrstuvwxyz";"7abcdefghijklmnopqrstuvwxyz";"8abcdefghijklmnopqrstuvwxyz";"9abcdefghijklmnopqrstuvwxyz"])],
2507    "return first 10 lines of a file",
2508    "\
2509 This command returns up to the first 10 lines of a file as
2510 a list of strings.");
2511
2512   ("head_n", (RStringList "lines", [Int "nrlines"; String "path"]), 122, [ProtocolLimitWarning],
2513    [InitBasicFS, Always, TestOutputList (
2514       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2515        ["head_n"; "3"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz"]);
2516     InitBasicFS, Always, TestOutputList (
2517       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2518        ["head_n"; "-9997"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz"]);
2519     InitBasicFS, Always, TestOutputList (
2520       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2521        ["head_n"; "0"; "/10klines"]], [])],
2522    "return first N lines of a file",
2523    "\
2524 If the parameter C<nrlines> is a positive number, this returns the first
2525 C<nrlines> lines of the file C<path>.
2526
2527 If the parameter C<nrlines> is a negative number, this returns lines
2528 from the file C<path>, excluding the last C<nrlines> lines.
2529
2530 If the parameter C<nrlines> is zero, this returns an empty list.");
2531
2532   ("tail", (RStringList "lines", [String "path"]), 123, [ProtocolLimitWarning],
2533    [InitBasicFS, Always, TestOutputList (
2534       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2535        ["tail"; "/10klines"]], ["9990abcdefghijklmnopqrstuvwxyz";"9991abcdefghijklmnopqrstuvwxyz";"9992abcdefghijklmnopqrstuvwxyz";"9993abcdefghijklmnopqrstuvwxyz";"9994abcdefghijklmnopqrstuvwxyz";"9995abcdefghijklmnopqrstuvwxyz";"9996abcdefghijklmnopqrstuvwxyz";"9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"])],
2536    "return last 10 lines of a file",
2537    "\
2538 This command returns up to the last 10 lines of a file as
2539 a list of strings.");
2540
2541   ("tail_n", (RStringList "lines", [Int "nrlines"; String "path"]), 124, [ProtocolLimitWarning],
2542    [InitBasicFS, Always, TestOutputList (
2543       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2544        ["tail_n"; "3"; "/10klines"]], ["9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"]);
2545     InitBasicFS, Always, TestOutputList (
2546       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2547        ["tail_n"; "-9998"; "/10klines"]], ["9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"]);
2548     InitBasicFS, Always, TestOutputList (
2549       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2550        ["tail_n"; "0"; "/10klines"]], [])],
2551    "return last N lines of a file",
2552    "\
2553 If the parameter C<nrlines> is a positive number, this returns the last
2554 C<nrlines> lines of the file C<path>.
2555
2556 If the parameter C<nrlines> is a negative number, this returns lines
2557 from the file C<path>, starting with the C<-nrlines>th line.
2558
2559 If the parameter C<nrlines> is zero, this returns an empty list.");
2560
2561   ("df", (RString "output", []), 125, [],
2562    [], (* XXX Tricky to test because it depends on the exact format
2563         * of the 'df' command and other imponderables.
2564         *)
2565    "report file system disk space usage",
2566    "\
2567 This command runs the C<df> command to report disk space used.
2568
2569 This command is mostly useful for interactive sessions.  It
2570 is I<not> intended that you try to parse the output string.
2571 Use C<statvfs> from programs.");
2572
2573   ("df_h", (RString "output", []), 126, [],
2574    [], (* XXX Tricky to test because it depends on the exact format
2575         * of the 'df' command and other imponderables.
2576         *)
2577    "report file system disk space usage (human readable)",
2578    "\
2579 This command runs the C<df -h> command to report disk space used
2580 in human-readable format.
2581
2582 This command is mostly useful for interactive sessions.  It
2583 is I<not> intended that you try to parse the output string.
2584 Use C<statvfs> from programs.");
2585
2586 ]
2587
2588 let all_functions = non_daemon_functions @ daemon_functions
2589
2590 (* In some places we want the functions to be displayed sorted
2591  * alphabetically, so this is useful:
2592  *)
2593 let all_functions_sorted =
2594   List.sort (fun (n1,_,_,_,_,_,_) (n2,_,_,_,_,_,_) ->
2595                compare n1 n2) all_functions
2596
2597 (* Column names and types from LVM PVs/VGs/LVs. *)
2598 let pv_cols = [
2599   "pv_name", `String;
2600   "pv_uuid", `UUID;
2601   "pv_fmt", `String;
2602   "pv_size", `Bytes;
2603   "dev_size", `Bytes;
2604   "pv_free", `Bytes;
2605   "pv_used", `Bytes;
2606   "pv_attr", `String (* XXX *);
2607   "pv_pe_count", `Int;
2608   "pv_pe_alloc_count", `Int;
2609   "pv_tags", `String;
2610   "pe_start", `Bytes;
2611   "pv_mda_count", `Int;
2612   "pv_mda_free", `Bytes;
2613 (* Not in Fedora 10:
2614   "pv_mda_size", `Bytes;
2615 *)
2616 ]
2617 let vg_cols = [
2618   "vg_name", `String;
2619   "vg_uuid", `UUID;
2620   "vg_fmt", `String;
2621   "vg_attr", `String (* XXX *);
2622   "vg_size", `Bytes;
2623   "vg_free", `Bytes;
2624   "vg_sysid", `String;
2625   "vg_extent_size", `Bytes;
2626   "vg_extent_count", `Int;
2627   "vg_free_count", `Int;
2628   "max_lv", `Int;
2629   "max_pv", `Int;
2630   "pv_count", `Int;
2631   "lv_count", `Int;
2632   "snap_count", `Int;
2633   "vg_seqno", `Int;
2634   "vg_tags", `String;
2635   "vg_mda_count", `Int;
2636   "vg_mda_free", `Bytes;
2637 (* Not in Fedora 10:
2638   "vg_mda_size", `Bytes;
2639 *)
2640 ]
2641 let lv_cols = [
2642   "lv_name", `String;
2643   "lv_uuid", `UUID;
2644   "lv_attr", `String (* XXX *);
2645   "lv_major", `Int;
2646   "lv_minor", `Int;
2647   "lv_kernel_major", `Int;
2648   "lv_kernel_minor", `Int;
2649   "lv_size", `Bytes;
2650   "seg_count", `Int;
2651   "origin", `String;
2652   "snap_percent", `OptPercent;
2653   "copy_percent", `OptPercent;
2654   "move_pv", `String;
2655   "lv_tags", `String;
2656   "mirror_log", `String;
2657   "modules", `String;
2658 ]
2659
2660 (* Column names and types from stat structures.
2661  * NB. Can't use things like 'st_atime' because glibc header files
2662  * define some of these as macros.  Ugh.
2663  *)
2664 let stat_cols = [
2665   "dev", `Int;
2666   "ino", `Int;
2667   "mode", `Int;
2668   "nlink", `Int;
2669   "uid", `Int;
2670   "gid", `Int;
2671   "rdev", `Int;
2672   "size", `Int;
2673   "blksize", `Int;
2674   "blocks", `Int;
2675   "atime", `Int;
2676   "mtime", `Int;
2677   "ctime", `Int;
2678 ]
2679 let statvfs_cols = [
2680   "bsize", `Int;
2681   "frsize", `Int;
2682   "blocks", `Int;
2683   "bfree", `Int;
2684   "bavail", `Int;
2685   "files", `Int;
2686   "ffree", `Int;
2687   "favail", `Int;
2688   "fsid", `Int;
2689   "flag", `Int;
2690   "namemax", `Int;
2691 ]
2692
2693 (* Used for testing language bindings. *)
2694 type callt =
2695   | CallString of string
2696   | CallOptString of string option
2697   | CallStringList of string list
2698   | CallInt of int
2699   | CallBool of bool
2700
2701 (* Useful functions.
2702  * Note we don't want to use any external OCaml libraries which
2703  * makes this a bit harder than it should be.
2704  *)
2705 let failwithf fs = ksprintf failwith fs
2706
2707 let replace_char s c1 c2 =
2708   let s2 = String.copy s in
2709   let r = ref false in
2710   for i = 0 to String.length s2 - 1 do
2711     if String.unsafe_get s2 i = c1 then (
2712       String.unsafe_set s2 i c2;
2713       r := true
2714     )
2715   done;
2716   if not !r then s else s2
2717
2718 let isspace c =
2719   c = ' '
2720   (* || c = '\f' *) || c = '\n' || c = '\r' || c = '\t' (* || c = '\v' *)
2721
2722 let triml ?(test = isspace) str =
2723   let i = ref 0 in
2724   let n = ref (String.length str) in
2725   while !n > 0 && test str.[!i]; do
2726     decr n;
2727     incr i
2728   done;
2729   if !i = 0 then str
2730   else String.sub str !i !n
2731
2732 let trimr ?(test = isspace) str =
2733   let n = ref (String.length str) in
2734   while !n > 0 && test str.[!n-1]; do
2735     decr n
2736   done;
2737   if !n = String.length str then str
2738   else String.sub str 0 !n
2739
2740 let trim ?(test = isspace) str =
2741   trimr ~test (triml ~test str)
2742
2743 let rec find s sub =
2744   let len = String.length s in
2745   let sublen = String.length sub in
2746   let rec loop i =
2747     if i <= len-sublen then (
2748       let rec loop2 j =
2749         if j < sublen then (
2750           if s.[i+j] = sub.[j] then loop2 (j+1)
2751           else -1
2752         ) else
2753           i (* found *)
2754       in
2755       let r = loop2 0 in
2756       if r = -1 then loop (i+1) else r
2757     ) else
2758       -1 (* not found *)
2759   in
2760   loop 0
2761
2762 let rec replace_str s s1 s2 =
2763   let len = String.length s in
2764   let sublen = String.length s1 in
2765   let i = find s s1 in
2766   if i = -1 then s
2767   else (
2768     let s' = String.sub s 0 i in
2769     let s'' = String.sub s (i+sublen) (len-i-sublen) in
2770     s' ^ s2 ^ replace_str s'' s1 s2
2771   )
2772
2773 let rec string_split sep str =
2774   let len = String.length str in
2775   let seplen = String.length sep in
2776   let i = find str sep in
2777   if i = -1 then [str]
2778   else (
2779     let s' = String.sub str 0 i in
2780     let s'' = String.sub str (i+seplen) (len-i-seplen) in
2781     s' :: string_split sep s''
2782   )
2783
2784 let files_equal n1 n2 =
2785   let cmd = sprintf "cmp -s %s %s" (Filename.quote n1) (Filename.quote n2) in
2786   match Sys.command cmd with
2787   | 0 -> true
2788   | 1 -> false
2789   | i -> failwithf "%s: failed with error code %d" cmd i
2790
2791 let rec find_map f = function
2792   | [] -> raise Not_found
2793   | x :: xs ->
2794       match f x with
2795       | Some y -> y
2796       | None -> find_map f xs
2797
2798 let iteri f xs =
2799   let rec loop i = function
2800     | [] -> ()
2801     | x :: xs -> f i x; loop (i+1) xs
2802   in
2803   loop 0 xs
2804
2805 let mapi f xs =
2806   let rec loop i = function
2807     | [] -> []
2808     | x :: xs -> let r = f i x in r :: loop (i+1) xs
2809   in
2810   loop 0 xs
2811
2812 let name_of_argt = function
2813   | String n | OptString n | StringList n | Bool n | Int n
2814   | FileIn n | FileOut n -> n
2815
2816 let seq_of_test = function
2817   | TestRun s | TestOutput (s, _) | TestOutputList (s, _)
2818   | TestOutputListOfDevices (s, _)
2819   | TestOutputInt (s, _) | TestOutputTrue s | TestOutputFalse s
2820   | TestOutputLength (s, _) | TestOutputStruct (s, _)
2821   | TestLastFail s -> s
2822
2823 (* Check function names etc. for consistency. *)
2824 let check_functions () =
2825   let contains_uppercase str =
2826     let len = String.length str in
2827     let rec loop i =
2828       if i >= len then false
2829       else (
2830         let c = str.[i] in
2831         if c >= 'A' && c <= 'Z' then true
2832         else loop (i+1)
2833       )
2834     in
2835     loop 0
2836   in
2837
2838   (* Check function names. *)
2839   List.iter (
2840     fun (name, _, _, _, _, _, _) ->
2841       if String.length name >= 7 && String.sub name 0 7 = "guestfs" then
2842         failwithf "function name %s does not need 'guestfs' prefix" name;
2843       if name = "" then
2844         failwithf "function name is empty";
2845       if name.[0] < 'a' || name.[0] > 'z' then
2846         failwithf "function name %s must start with lowercase a-z" name;
2847       if String.contains name '-' then
2848         failwithf "function name %s should not contain '-', use '_' instead."
2849           name
2850   ) all_functions;
2851
2852   (* Check function parameter/return names. *)
2853   List.iter (
2854     fun (name, style, _, _, _, _, _) ->
2855       let check_arg_ret_name n =
2856         if contains_uppercase n then
2857           failwithf "%s param/ret %s should not contain uppercase chars"
2858             name n;
2859         if String.contains n '-' || String.contains n '_' then
2860           failwithf "%s param/ret %s should not contain '-' or '_'"
2861             name n;
2862         if n = "value" then
2863           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;
2864         if n = "int" || n = "char" || n = "short" || n = "long" then
2865           failwithf "%s has a param/ret which conflicts with a C type (eg. 'int', 'char' etc.)" name;
2866         if n = "i" || n = "n" then
2867           failwithf "%s has a param/ret called 'i' or 'n', which will cause some conflicts in the generated code" name;
2868         if n = "argv" || n = "args" then
2869           failwithf "%s has a param/ret called 'argv' or 'args', which will cause some conflicts in the generated code" name
2870       in
2871
2872       (match fst style with
2873        | RErr -> ()
2874        | RInt n | RInt64 n | RBool n | RConstString n | RString n
2875        | RStringList n | RPVList n | RVGList n | RLVList n
2876        | RStat n | RStatVFS n
2877        | RHashtable n ->
2878            check_arg_ret_name n
2879        | RIntBool (n,m) ->
2880            check_arg_ret_name n;
2881            check_arg_ret_name m
2882       );
2883       List.iter (fun arg -> check_arg_ret_name (name_of_argt arg)) (snd style)
2884   ) all_functions;
2885
2886   (* Check short descriptions. *)
2887   List.iter (
2888     fun (name, _, _, _, _, shortdesc, _) ->
2889       if shortdesc.[0] <> Char.lowercase shortdesc.[0] then
2890         failwithf "short description of %s should begin with lowercase." name;
2891       let c = shortdesc.[String.length shortdesc-1] in
2892       if c = '\n' || c = '.' then
2893         failwithf "short description of %s should not end with . or \\n." name
2894   ) all_functions;
2895
2896   (* Check long dscriptions. *)
2897   List.iter (
2898     fun (name, _, _, _, _, _, longdesc) ->
2899       if longdesc.[String.length longdesc-1] = '\n' then
2900         failwithf "long description of %s should not end with \\n." name
2901   ) all_functions;
2902
2903   (* Check proc_nrs. *)
2904   List.iter (
2905     fun (name, _, proc_nr, _, _, _, _) ->
2906       if proc_nr <= 0 then
2907         failwithf "daemon function %s should have proc_nr > 0" name
2908   ) daemon_functions;
2909
2910   List.iter (
2911     fun (name, _, proc_nr, _, _, _, _) ->
2912       if proc_nr <> -1 then
2913         failwithf "non-daemon function %s should have proc_nr -1" name
2914   ) non_daemon_functions;
2915
2916   let proc_nrs =
2917     List.map (fun (name, _, proc_nr, _, _, _, _) -> name, proc_nr)
2918       daemon_functions in
2919   let proc_nrs =
2920     List.sort (fun (_,nr1) (_,nr2) -> compare nr1 nr2) proc_nrs in
2921   let rec loop = function
2922     | [] -> ()
2923     | [_] -> ()
2924     | (name1,nr1) :: ((name2,nr2) :: _ as rest) when nr1 < nr2 ->
2925         loop rest
2926     | (name1,nr1) :: (name2,nr2) :: _ ->
2927         failwithf "%s and %s have conflicting procedure numbers (%d, %d)"
2928           name1 name2 nr1 nr2
2929   in
2930   loop proc_nrs;
2931
2932   (* Check tests. *)
2933   List.iter (
2934     function
2935       (* Ignore functions that have no tests.  We generate a
2936        * warning when the user does 'make check' instead.
2937        *)
2938     | name, _, _, _, [], _, _ -> ()
2939     | name, _, _, _, tests, _, _ ->
2940         let funcs =
2941           List.map (
2942             fun (_, _, test) ->
2943               match seq_of_test test with
2944               | [] ->
2945                   failwithf "%s has a test containing an empty sequence" name
2946               | cmds -> List.map List.hd cmds
2947           ) tests in
2948         let funcs = List.flatten funcs in
2949
2950         let tested = List.mem name funcs in
2951
2952         if not tested then
2953           failwithf "function %s has tests but does not test itself" name
2954   ) all_functions
2955
2956 (* 'pr' prints to the current output file. *)
2957 let chan = ref stdout
2958 let pr fs = ksprintf (output_string !chan) fs
2959
2960 (* Generate a header block in a number of standard styles. *)
2961 type comment_style = CStyle | HashStyle | OCamlStyle | HaskellStyle
2962 type license = GPLv2 | LGPLv2
2963
2964 let generate_header comment license =
2965   let c = match comment with
2966     | CStyle ->     pr "/* "; " *"
2967     | HashStyle ->  pr "# ";  "#"
2968     | OCamlStyle -> pr "(* "; " *"
2969     | HaskellStyle -> pr "{- "; "  " in
2970   pr "libguestfs generated file\n";
2971   pr "%s WARNING: THIS FILE IS GENERATED BY 'src/generator.ml'.\n" c;
2972   pr "%s ANY CHANGES YOU MAKE TO THIS FILE WILL BE LOST.\n" c;
2973   pr "%s\n" c;
2974   pr "%s Copyright (C) 2009 Red Hat Inc.\n" c;
2975   pr "%s\n" c;
2976   (match license with
2977    | GPLv2 ->
2978        pr "%s This program is free software; you can redistribute it and/or modify\n" c;
2979        pr "%s it under the terms of the GNU General Public License as published by\n" c;
2980        pr "%s the Free Software Foundation; either version 2 of the License, or\n" c;
2981        pr "%s (at your option) any later version.\n" c;
2982        pr "%s\n" c;
2983        pr "%s This program is distributed in the hope that it will be useful,\n" c;
2984        pr "%s but WITHOUT ANY WARRANTY; without even the implied warranty of\n" c;
2985        pr "%s MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\n" c;
2986        pr "%s GNU General Public License for more details.\n" c;
2987        pr "%s\n" c;
2988        pr "%s You should have received a copy of the GNU General Public License along\n" c;
2989        pr "%s with this program; if not, write to the Free Software Foundation, Inc.,\n" c;
2990        pr "%s 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.\n" c;
2991
2992    | LGPLv2 ->
2993        pr "%s This library is free software; you can redistribute it and/or\n" c;
2994        pr "%s modify it under the terms of the GNU Lesser General Public\n" c;
2995        pr "%s License as published by the Free Software Foundation; either\n" c;
2996        pr "%s version 2 of the License, or (at your option) any later version.\n" c;
2997        pr "%s\n" c;
2998        pr "%s This library is distributed in the hope that it will be useful,\n" c;
2999        pr "%s but WITHOUT ANY WARRANTY; without even the implied warranty of\n" c;
3000        pr "%s MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU\n" c;
3001        pr "%s Lesser General Public License for more details.\n" c;
3002        pr "%s\n" c;
3003        pr "%s You should have received a copy of the GNU Lesser General Public\n" c;
3004        pr "%s License along with this library; if not, write to the Free Software\n" c;
3005        pr "%s Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA\n" c;
3006   );
3007   (match comment with
3008    | CStyle -> pr " */\n"
3009    | HashStyle -> ()
3010    | OCamlStyle -> pr " *)\n"
3011    | HaskellStyle -> pr "-}\n"
3012   );
3013   pr "\n"
3014
3015 (* Start of main code generation functions below this line. *)
3016
3017 (* Generate the pod documentation for the C API. *)
3018 let rec generate_actions_pod () =
3019   List.iter (
3020     fun (shortname, style, _, flags, _, _, longdesc) ->
3021       if not (List.mem NotInDocs flags) then (
3022         let name = "guestfs_" ^ shortname in
3023         pr "=head2 %s\n\n" name;
3024         pr " ";
3025         generate_prototype ~extern:false ~handle:"handle" name style;
3026         pr "\n\n";
3027         pr "%s\n\n" longdesc;
3028         (match fst style with
3029          | RErr ->
3030              pr "This function returns 0 on success or -1 on error.\n\n"
3031          | RInt _ ->
3032              pr "On error this function returns -1.\n\n"
3033          | RInt64 _ ->
3034              pr "On error this function returns -1.\n\n"
3035          | RBool _ ->
3036              pr "This function returns a C truth value on success or -1 on error.\n\n"
3037          | RConstString _ ->
3038              pr "This function returns a string, or NULL on error.
3039 The string is owned by the guest handle and must I<not> be freed.\n\n"
3040          | RString _ ->
3041              pr "This function returns a string, or NULL on error.
3042 I<The caller must free the returned string after use>.\n\n"
3043          | RStringList _ ->
3044              pr "This function returns a NULL-terminated array of strings
3045 (like L<environ(3)>), or NULL if there was an error.
3046 I<The caller must free the strings and the array after use>.\n\n"
3047          | RIntBool _ ->
3048              pr "This function returns a C<struct guestfs_int_bool *>,
3049 or NULL if there was an error.
3050 I<The caller must call C<guestfs_free_int_bool> after use>.\n\n"
3051          | RPVList _ ->
3052              pr "This function returns a C<struct guestfs_lvm_pv_list *>
3053 (see E<lt>guestfs-structs.hE<gt>),
3054 or NULL if there was an error.
3055 I<The caller must call C<guestfs_free_lvm_pv_list> after use>.\n\n"
3056          | RVGList _ ->
3057              pr "This function returns a C<struct guestfs_lvm_vg_list *>
3058 (see E<lt>guestfs-structs.hE<gt>),
3059 or NULL if there was an error.
3060 I<The caller must call C<guestfs_free_lvm_vg_list> after use>.\n\n"
3061          | RLVList _ ->
3062              pr "This function returns a C<struct guestfs_lvm_lv_list *>
3063 (see E<lt>guestfs-structs.hE<gt>),
3064 or NULL if there was an error.
3065 I<The caller must call C<guestfs_free_lvm_lv_list> after use>.\n\n"
3066          | RStat _ ->
3067              pr "This function returns a C<struct guestfs_stat *>
3068 (see L<stat(2)> and E<lt>guestfs-structs.hE<gt>),
3069 or NULL if there was an error.
3070 I<The caller must call C<free> after use>.\n\n"
3071          | RStatVFS _ ->
3072              pr "This function returns a C<struct guestfs_statvfs *>
3073 (see L<statvfs(2)> and E<lt>guestfs-structs.hE<gt>),
3074 or NULL if there was an error.
3075 I<The caller must call C<free> after use>.\n\n"
3076          | RHashtable _ ->
3077              pr "This function returns a NULL-terminated array of
3078 strings, or NULL if there was an error.
3079 The array of strings will always have length C<2n+1>, where
3080 C<n> keys and values alternate, followed by the trailing NULL entry.
3081 I<The caller must free the strings and the array after use>.\n\n"
3082         );
3083         if List.mem ProtocolLimitWarning flags then
3084           pr "%s\n\n" protocol_limit_warning;
3085         if List.mem DangerWillRobinson flags then
3086           pr "%s\n\n" danger_will_robinson
3087       )
3088   ) all_functions_sorted
3089
3090 and generate_structs_pod () =
3091   (* LVM structs documentation. *)
3092   List.iter (
3093     fun (typ, cols) ->
3094       pr "=head2 guestfs_lvm_%s\n" typ;
3095       pr "\n";
3096       pr " struct guestfs_lvm_%s {\n" typ;
3097       List.iter (
3098         function
3099         | name, `String -> pr "  char *%s;\n" name
3100         | name, `UUID ->
3101             pr "  /* The next field is NOT nul-terminated, be careful when printing it: */\n";
3102             pr "  char %s[32];\n" name
3103         | name, `Bytes -> pr "  uint64_t %s;\n" name
3104         | name, `Int -> pr "  int64_t %s;\n" name
3105         | name, `OptPercent ->
3106             pr "  /* The next field is [0..100] or -1 meaning 'not present': */\n";
3107             pr "  float %s;\n" name
3108       ) cols;
3109       pr " \n";
3110       pr " struct guestfs_lvm_%s_list {\n" typ;
3111       pr "   uint32_t len; /* Number of elements in list. */\n";
3112       pr "   struct guestfs_lvm_%s *val; /* Elements. */\n" typ;
3113       pr " };\n";
3114       pr " \n";
3115       pr " void guestfs_free_lvm_%s_list (struct guestfs_free_lvm_%s_list *);\n"
3116         typ typ;
3117       pr "\n"
3118   ) ["pv", pv_cols; "vg", vg_cols; "lv", lv_cols]
3119
3120 (* Generate the protocol (XDR) file, 'guestfs_protocol.x' and
3121  * indirectly 'guestfs_protocol.h' and 'guestfs_protocol.c'.
3122  *
3123  * We have to use an underscore instead of a dash because otherwise
3124  * rpcgen generates incorrect code.
3125  *
3126  * This header is NOT exported to clients, but see also generate_structs_h.
3127  *)
3128 and generate_xdr () =
3129   generate_header CStyle LGPLv2;
3130
3131   (* This has to be defined to get around a limitation in Sun's rpcgen. *)
3132   pr "typedef string str<>;\n";
3133   pr "\n";
3134
3135   (* LVM internal structures. *)
3136   List.iter (
3137     function
3138     | typ, cols ->
3139         pr "struct guestfs_lvm_int_%s {\n" typ;
3140         List.iter (function
3141                    | name, `String -> pr "  string %s<>;\n" name
3142                    | name, `UUID -> pr "  opaque %s[32];\n" name
3143                    | name, `Bytes -> pr "  hyper %s;\n" name
3144                    | name, `Int -> pr "  hyper %s;\n" name
3145                    | name, `OptPercent -> pr "  float %s;\n" name
3146                   ) cols;
3147         pr "};\n";
3148         pr "\n";
3149         pr "typedef struct guestfs_lvm_int_%s guestfs_lvm_int_%s_list<>;\n" typ typ;
3150         pr "\n";
3151   ) ["pv", pv_cols; "vg", vg_cols; "lv", lv_cols];
3152
3153   (* Stat internal structures. *)
3154   List.iter (
3155     function
3156     | typ, cols ->
3157         pr "struct guestfs_int_%s {\n" typ;
3158         List.iter (function
3159                    | name, `Int -> pr "  hyper %s;\n" name
3160                   ) cols;
3161         pr "};\n";
3162         pr "\n";
3163   ) ["stat", stat_cols; "statvfs", statvfs_cols];
3164
3165   List.iter (
3166     fun (shortname, style, _, _, _, _, _) ->
3167       let name = "guestfs_" ^ shortname in
3168
3169       (match snd style with
3170        | [] -> ()
3171        | args ->
3172            pr "struct %s_args {\n" name;
3173            List.iter (
3174              function
3175              | String n -> pr "  string %s<>;\n" n
3176              | OptString n -> pr "  str *%s;\n" n
3177              | StringList n -> pr "  str %s<>;\n" n
3178              | Bool n -> pr "  bool %s;\n" n
3179              | Int n -> pr "  int %s;\n" n
3180              | FileIn _ | FileOut _ -> ()
3181            ) args;
3182            pr "};\n\n"
3183       );
3184       (match fst style with
3185        | RErr -> ()
3186        | RInt n ->
3187            pr "struct %s_ret {\n" name;
3188            pr "  int %s;\n" n;
3189            pr "};\n\n"
3190        | RInt64 n ->
3191            pr "struct %s_ret {\n" name;
3192            pr "  hyper %s;\n" n;
3193            pr "};\n\n"
3194        | RBool n ->
3195            pr "struct %s_ret {\n" name;
3196            pr "  bool %s;\n" n;
3197            pr "};\n\n"
3198        | RConstString _ ->
3199            failwithf "RConstString cannot be returned from a daemon function"
3200        | RString n ->
3201            pr "struct %s_ret {\n" name;
3202            pr "  string %s<>;\n" n;
3203            pr "};\n\n"
3204        | RStringList n ->
3205            pr "struct %s_ret {\n" name;
3206            pr "  str %s<>;\n" n;
3207            pr "};\n\n"
3208        | RIntBool (n,m) ->
3209            pr "struct %s_ret {\n" name;
3210            pr "  int %s;\n" n;
3211            pr "  bool %s;\n" m;
3212            pr "};\n\n"
3213        | RPVList n ->
3214            pr "struct %s_ret {\n" name;
3215            pr "  guestfs_lvm_int_pv_list %s;\n" n;
3216            pr "};\n\n"
3217        | RVGList n ->
3218            pr "struct %s_ret {\n" name;
3219            pr "  guestfs_lvm_int_vg_list %s;\n" n;
3220            pr "};\n\n"
3221        | RLVList n ->
3222            pr "struct %s_ret {\n" name;
3223            pr "  guestfs_lvm_int_lv_list %s;\n" n;
3224            pr "};\n\n"
3225        | RStat n ->
3226            pr "struct %s_ret {\n" name;
3227            pr "  guestfs_int_stat %s;\n" n;
3228            pr "};\n\n"
3229        | RStatVFS n ->
3230            pr "struct %s_ret {\n" name;
3231            pr "  guestfs_int_statvfs %s;\n" n;
3232            pr "};\n\n"
3233        | RHashtable n ->
3234            pr "struct %s_ret {\n" name;
3235            pr "  str %s<>;\n" n;
3236            pr "};\n\n"
3237       );
3238   ) daemon_functions;
3239
3240   (* Table of procedure numbers. *)
3241   pr "enum guestfs_procedure {\n";
3242   List.iter (
3243     fun (shortname, _, proc_nr, _, _, _, _) ->
3244       pr "  GUESTFS_PROC_%s = %d,\n" (String.uppercase shortname) proc_nr
3245   ) daemon_functions;
3246   pr "  GUESTFS_PROC_NR_PROCS\n";
3247   pr "};\n";
3248   pr "\n";
3249
3250   (* Having to choose a maximum message size is annoying for several
3251    * reasons (it limits what we can do in the API), but it (a) makes
3252    * the protocol a lot simpler, and (b) provides a bound on the size
3253    * of the daemon which operates in limited memory space.  For large
3254    * file transfers you should use FTP.
3255    *)
3256   pr "const GUESTFS_MESSAGE_MAX = %d;\n" (4 * 1024 * 1024);
3257   pr "\n";
3258
3259   (* Message header, etc. *)
3260   pr "\
3261 /* The communication protocol is now documented in the guestfs(3)
3262  * manpage.
3263  */
3264
3265 const GUESTFS_PROGRAM = 0x2000F5F5;
3266 const GUESTFS_PROTOCOL_VERSION = 1;
3267
3268 /* These constants must be larger than any possible message length. */
3269 const GUESTFS_LAUNCH_FLAG = 0xf5f55ff5;
3270 const GUESTFS_CANCEL_FLAG = 0xffffeeee;
3271
3272 enum guestfs_message_direction {
3273   GUESTFS_DIRECTION_CALL = 0,        /* client -> daemon */
3274   GUESTFS_DIRECTION_REPLY = 1        /* daemon -> client */
3275 };
3276
3277 enum guestfs_message_status {
3278   GUESTFS_STATUS_OK = 0,
3279   GUESTFS_STATUS_ERROR = 1
3280 };
3281
3282 const GUESTFS_ERROR_LEN = 256;
3283
3284 struct guestfs_message_error {
3285   string error_message<GUESTFS_ERROR_LEN>;
3286 };
3287
3288 struct guestfs_message_header {
3289   unsigned prog;                     /* GUESTFS_PROGRAM */
3290   unsigned vers;                     /* GUESTFS_PROTOCOL_VERSION */
3291   guestfs_procedure proc;            /* GUESTFS_PROC_x */
3292   guestfs_message_direction direction;
3293   unsigned serial;                   /* message serial number */
3294   guestfs_message_status status;
3295 };
3296
3297 const GUESTFS_MAX_CHUNK_SIZE = 8192;
3298
3299 struct guestfs_chunk {
3300   int cancel;                        /* if non-zero, transfer is cancelled */
3301   /* data size is 0 bytes if the transfer has finished successfully */
3302   opaque data<GUESTFS_MAX_CHUNK_SIZE>;
3303 };
3304 "
3305
3306 (* Generate the guestfs-structs.h file. *)
3307 and generate_structs_h () =
3308   generate_header CStyle LGPLv2;
3309
3310   (* This is a public exported header file containing various
3311    * structures.  The structures are carefully written to have
3312    * exactly the same in-memory format as the XDR structures that
3313    * we use on the wire to the daemon.  The reason for creating
3314    * copies of these structures here is just so we don't have to
3315    * export the whole of guestfs_protocol.h (which includes much
3316    * unrelated and XDR-dependent stuff that we don't want to be
3317    * public, or required by clients).
3318    *
3319    * To reiterate, we will pass these structures to and from the
3320    * client with a simple assignment or memcpy, so the format
3321    * must be identical to what rpcgen / the RFC defines.
3322    *)
3323
3324   (* guestfs_int_bool structure. *)
3325   pr "struct guestfs_int_bool {\n";
3326   pr "  int32_t i;\n";
3327   pr "  int32_t b;\n";
3328   pr "};\n";
3329   pr "\n";
3330
3331   (* LVM public structures. *)
3332   List.iter (
3333     function
3334     | typ, cols ->
3335         pr "struct guestfs_lvm_%s {\n" typ;
3336         List.iter (
3337           function
3338           | name, `String -> pr "  char *%s;\n" name
3339           | name, `UUID -> pr "  char %s[32]; /* this is NOT nul-terminated, be careful when printing */\n" name
3340           | name, `Bytes -> pr "  uint64_t %s;\n" name
3341           | name, `Int -> pr "  int64_t %s;\n" name
3342           | name, `OptPercent -> pr "  float %s; /* [0..100] or -1 */\n" name
3343         ) cols;
3344         pr "};\n";
3345         pr "\n";
3346         pr "struct guestfs_lvm_%s_list {\n" typ;
3347         pr "  uint32_t len;\n";
3348         pr "  struct guestfs_lvm_%s *val;\n" typ;
3349         pr "};\n";
3350         pr "\n"
3351   ) ["pv", pv_cols; "vg", vg_cols; "lv", lv_cols];
3352
3353   (* Stat structures. *)
3354   List.iter (
3355     function
3356     | typ, cols ->
3357         pr "struct guestfs_%s {\n" typ;
3358         List.iter (
3359           function
3360           | name, `Int -> pr "  int64_t %s;\n" name
3361         ) cols;
3362         pr "};\n";
3363         pr "\n"
3364   ) ["stat", stat_cols; "statvfs", statvfs_cols]
3365
3366 (* Generate the guestfs-actions.h file. *)
3367 and generate_actions_h () =
3368   generate_header CStyle LGPLv2;
3369   List.iter (
3370     fun (shortname, style, _, _, _, _, _) ->
3371       let name = "guestfs_" ^ shortname in
3372       generate_prototype ~single_line:true ~newline:true ~handle:"handle"
3373         name style
3374   ) all_functions
3375
3376 (* Generate the client-side dispatch stubs. *)
3377 and generate_client_actions () =
3378   generate_header CStyle LGPLv2;
3379
3380   pr "\
3381 #include <stdio.h>
3382 #include <stdlib.h>
3383
3384 #include \"guestfs.h\"
3385 #include \"guestfs_protocol.h\"
3386
3387 #define error guestfs_error
3388 #define perrorf guestfs_perrorf
3389 #define safe_malloc guestfs_safe_malloc
3390 #define safe_realloc guestfs_safe_realloc
3391 #define safe_strdup guestfs_safe_strdup
3392 #define safe_memdup guestfs_safe_memdup
3393
3394 /* Check the return message from a call for validity. */
3395 static int
3396 check_reply_header (guestfs_h *g,
3397                     const struct guestfs_message_header *hdr,
3398                     int proc_nr, int serial)
3399 {
3400   if (hdr->prog != GUESTFS_PROGRAM) {
3401     error (g, \"wrong program (%%d/%%d)\", hdr->prog, GUESTFS_PROGRAM);
3402     return -1;
3403   }
3404   if (hdr->vers != GUESTFS_PROTOCOL_VERSION) {
3405     error (g, \"wrong protocol version (%%d/%%d)\",
3406            hdr->vers, GUESTFS_PROTOCOL_VERSION);
3407     return -1;
3408   }
3409   if (hdr->direction != GUESTFS_DIRECTION_REPLY) {
3410     error (g, \"unexpected message direction (%%d/%%d)\",
3411            hdr->direction, GUESTFS_DIRECTION_REPLY);
3412     return -1;
3413   }
3414   if (hdr->proc != proc_nr) {
3415     error (g, \"unexpected procedure number (%%d/%%d)\", hdr->proc, proc_nr);
3416     return -1;
3417   }
3418   if (hdr->serial != serial) {
3419     error (g, \"unexpected serial (%%d/%%d)\", hdr->serial, serial);
3420     return -1;
3421   }
3422
3423   return 0;
3424 }
3425
3426 /* Check we are in the right state to run a high-level action. */
3427 static int
3428 check_state (guestfs_h *g, const char *caller)
3429 {
3430   if (!guestfs_is_ready (g)) {
3431     if (guestfs_is_config (g))
3432       error (g, \"%%s: call launch() before using this function\",
3433         caller);
3434     else if (guestfs_is_launching (g))
3435       error (g, \"%%s: call wait_ready() before using this function\",
3436         caller);
3437     else
3438       error (g, \"%%s called from the wrong state, %%d != READY\",
3439         caller, guestfs_get_state (g));
3440     return -1;
3441   }
3442   return 0;
3443 }
3444
3445 ";
3446
3447   (* Client-side stubs for each function. *)
3448   List.iter (
3449     fun (shortname, style, _, _, _, _, _) ->
3450       let name = "guestfs_" ^ shortname in
3451
3452       (* Generate the context struct which stores the high-level
3453        * state between callback functions.
3454        *)
3455       pr "struct %s_ctx {\n" shortname;
3456       pr "  /* This flag is set by the callbacks, so we know we've done\n";
3457       pr "   * the callbacks as expected, and in the right sequence.\n";
3458       pr "   * 0 = not called, 1 = reply_cb called.\n";
3459       pr "   */\n";
3460       pr "  int cb_sequence;\n";
3461       pr "  struct guestfs_message_header hdr;\n";
3462       pr "  struct guestfs_message_error err;\n";
3463       (match fst style with
3464        | RErr -> ()
3465        | RConstString _ ->
3466            failwithf "RConstString cannot be returned from a daemon function"
3467        | RInt _ | RInt64 _
3468        | RBool _ | RString _ | RStringList _
3469        | RIntBool _
3470        | RPVList _ | RVGList _ | RLVList _
3471        | RStat _ | RStatVFS _
3472        | RHashtable _ ->
3473            pr "  struct %s_ret ret;\n" name
3474       );
3475       pr "};\n";
3476       pr "\n";
3477
3478       (* Generate the reply callback function. *)
3479       pr "static void %s_reply_cb (guestfs_h *g, void *data, XDR *xdr)\n" shortname;
3480       pr "{\n";
3481       pr "  guestfs_main_loop *ml = guestfs_get_main_loop (g);\n";
3482       pr "  struct %s_ctx *ctx = (struct %s_ctx *) data;\n" shortname shortname;
3483       pr "\n";
3484       pr "  /* This should definitely not happen. */\n";
3485       pr "  if (ctx->cb_sequence != 0) {\n";
3486       pr "    ctx->cb_sequence = 9999;\n";
3487       pr "    error (g, \"%%s: internal error: reply callback called twice\", \"%s\");\n" name;
3488       pr "    return;\n";
3489       pr "  }\n";
3490       pr "\n";
3491       pr "  ml->main_loop_quit (ml, g);\n";
3492       pr "\n";
3493       pr "  if (!xdr_guestfs_message_header (xdr, &ctx->hdr)) {\n";
3494       pr "    error (g, \"%%s: failed to parse reply header\", \"%s\");\n" name;
3495       pr "    return;\n";
3496       pr "  }\n";
3497       pr "  if (ctx->hdr.status == GUESTFS_STATUS_ERROR) {\n";
3498       pr "    if (!xdr_guestfs_message_error (xdr, &ctx->err)) {\n";
3499       pr "      error (g, \"%%s: failed to parse reply error\", \"%s\");\n"
3500         name;
3501       pr "      return;\n";
3502       pr "    }\n";
3503       pr "    goto done;\n";
3504       pr "  }\n";
3505
3506       (match fst style with
3507        | RErr -> ()
3508        | RConstString _ ->
3509            failwithf "RConstString cannot be returned from a daemon function"
3510        | RInt _ | RInt64 _
3511        | RBool _ | RString _ | RStringList _
3512        | RIntBool _
3513        | RPVList _ | RVGList _ | RLVList _
3514        | RStat _ | RStatVFS _
3515        | RHashtable _ ->
3516             pr "  if (!xdr_%s_ret (xdr, &ctx->ret)) {\n" name;
3517             pr "    error (g, \"%%s: failed to parse reply\", \"%s\");\n" name;
3518             pr "    return;\n";
3519             pr "  }\n";
3520       );
3521
3522       pr " done:\n";
3523       pr "  ctx->cb_sequence = 1;\n";
3524       pr "}\n\n";
3525
3526       (* Generate the action stub. *)
3527       generate_prototype ~extern:false ~semicolon:false ~newline:true
3528         ~handle:"g" name style;
3529
3530       let error_code =
3531         match fst style with
3532         | RErr | RInt _ | RInt64 _ | RBool _ -> "-1"
3533         | RConstString _ ->
3534             failwithf "RConstString cannot be returned from a daemon function"
3535         | RString _ | RStringList _ | RIntBool _
3536         | RPVList _ | RVGList _ | RLVList _
3537         | RStat _ | RStatVFS _
3538         | RHashtable _ ->
3539             "NULL" in
3540
3541       pr "{\n";
3542
3543       (match snd style with
3544        | [] -> ()
3545        | _ -> pr "  struct %s_args args;\n" name
3546       );
3547
3548       pr "  struct %s_ctx ctx;\n" shortname;
3549       pr "  guestfs_main_loop *ml = guestfs_get_main_loop (g);\n";
3550       pr "  int serial;\n";
3551       pr "\n";
3552       pr "  if (check_state (g, \"%s\") == -1) return %s;\n" name error_code;
3553       pr "  guestfs_set_busy (g);\n";
3554       pr "\n";
3555       pr "  memset (&ctx, 0, sizeof ctx);\n";
3556       pr "\n";
3557
3558       (* Send the main header and arguments. *)
3559       (match snd style with
3560        | [] ->
3561            pr "  serial = guestfs__send_sync (g, GUESTFS_PROC_%s, NULL, NULL);\n"
3562              (String.uppercase shortname)
3563        | args ->
3564            List.iter (
3565              function
3566              | String n ->
3567                  pr "  args.%s = (char *) %s;\n" n n
3568              | OptString n ->
3569                  pr "  args.%s = %s ? (char **) &%s : NULL;\n" n n n
3570              | StringList n ->
3571                  pr "  args.%s.%s_val = (char **) %s;\n" n n n;
3572                  pr "  for (args.%s.%s_len = 0; %s[args.%s.%s_len]; args.%s.%s_len++) ;\n" n n n n n n n;
3573              | Bool n ->
3574                  pr "  args.%s = %s;\n" n n
3575              | Int n ->
3576                  pr "  args.%s = %s;\n" n n
3577              | FileIn _ | FileOut _ -> ()
3578            ) args;
3579            pr "  serial = guestfs__send_sync (g, GUESTFS_PROC_%s,\n"
3580              (String.uppercase shortname);
3581            pr "        (xdrproc_t) xdr_%s_args, (char *) &args);\n"
3582              name;
3583       );
3584       pr "  if (serial == -1) {\n";
3585       pr "    guestfs_end_busy (g);\n";
3586       pr "    return %s;\n" error_code;
3587       pr "  }\n";
3588       pr "\n";
3589
3590       (* Send any additional files (FileIn) requested. *)
3591       let need_read_reply_label = ref false in
3592       List.iter (
3593         function
3594         | FileIn n ->
3595             pr "  {\n";
3596             pr "    int r;\n";
3597             pr "\n";
3598             pr "    r = guestfs__send_file_sync (g, %s);\n" n;
3599             pr "    if (r == -1) {\n";
3600             pr "      guestfs_end_busy (g);\n";
3601             pr "      return %s;\n" error_code;
3602             pr "    }\n";
3603             pr "    if (r == -2) /* daemon cancelled */\n";
3604             pr "      goto read_reply;\n";
3605             need_read_reply_label := true;
3606             pr "  }\n";
3607             pr "\n";
3608         | _ -> ()
3609       ) (snd style);
3610
3611       (* Wait for the reply from the remote end. *)
3612       if !need_read_reply_label then pr " read_reply:\n";
3613       pr "  guestfs__switch_to_receiving (g);\n";
3614       pr "  ctx.cb_sequence = 0;\n";
3615       pr "  guestfs_set_reply_callback (g, %s_reply_cb, &ctx);\n" shortname;
3616       pr "  (void) ml->main_loop_run (ml, g);\n";
3617       pr "  guestfs_set_reply_callback (g, NULL, NULL);\n";
3618       pr "  if (ctx.cb_sequence != 1) {\n";
3619       pr "    error (g, \"%%s reply failed, see earlier error messages\", \"%s\");\n" name;
3620       pr "    guestfs_end_busy (g);\n";
3621       pr "    return %s;\n" error_code;
3622       pr "  }\n";
3623       pr "\n";
3624
3625       pr "  if (check_reply_header (g, &ctx.hdr, GUESTFS_PROC_%s, serial) == -1) {\n"
3626         (String.uppercase shortname);
3627       pr "    guestfs_end_busy (g);\n";
3628       pr "    return %s;\n" error_code;
3629       pr "  }\n";
3630       pr "\n";
3631
3632       pr "  if (ctx.hdr.status == GUESTFS_STATUS_ERROR) {\n";
3633       pr "    error (g, \"%%s\", ctx.err.error_message);\n";
3634       pr "    free (ctx.err.error_message);\n";
3635       pr "    guestfs_end_busy (g);\n";
3636       pr "    return %s;\n" error_code;
3637       pr "  }\n";
3638       pr "\n";
3639
3640       (* Expecting to receive further files (FileOut)? *)
3641       List.iter (
3642         function
3643         | FileOut n ->
3644             pr "  if (guestfs__receive_file_sync (g, %s) == -1) {\n" n;
3645             pr "    guestfs_end_busy (g);\n";
3646             pr "    return %s;\n" error_code;
3647             pr "  }\n";
3648             pr "\n";
3649         | _ -> ()
3650       ) (snd style);
3651
3652       pr "  guestfs_end_busy (g);\n";
3653
3654       (match fst style with
3655        | RErr -> pr "  return 0;\n"
3656        | RInt n | RInt64 n | RBool n ->
3657            pr "  return ctx.ret.%s;\n" n
3658        | RConstString _ ->
3659            failwithf "RConstString cannot be returned from a daemon function"
3660        | RString n ->
3661            pr "  return ctx.ret.%s; /* caller will free */\n" n
3662        | RStringList n | RHashtable n ->
3663            pr "  /* caller will free this, but we need to add a NULL entry */\n";
3664            pr "  ctx.ret.%s.%s_val =\n" n n;
3665            pr "    safe_realloc (g, ctx.ret.%s.%s_val,\n" n n;
3666            pr "                  sizeof (char *) * (ctx.ret.%s.%s_len + 1));\n"
3667              n n;
3668            pr "  ctx.ret.%s.%s_val[ctx.ret.%s.%s_len] = NULL;\n" n n n n;
3669            pr "  return ctx.ret.%s.%s_val;\n" n n
3670        | RIntBool _ ->
3671            pr "  /* caller with free this */\n";
3672            pr "  return safe_memdup (g, &ctx.ret, sizeof (ctx.ret));\n"
3673        | RPVList n | RVGList n | RLVList n
3674        | RStat n | RStatVFS n ->
3675            pr "  /* caller will free this */\n";
3676            pr "  return safe_memdup (g, &ctx.ret.%s, sizeof (ctx.ret.%s));\n" n n
3677       );
3678
3679       pr "}\n\n"
3680   ) daemon_functions
3681
3682 (* Generate daemon/actions.h. *)
3683 and generate_daemon_actions_h () =
3684   generate_header CStyle GPLv2;
3685
3686   pr "#include \"../src/guestfs_protocol.h\"\n";
3687   pr "\n";
3688
3689   List.iter (
3690     fun (name, style, _, _, _, _, _) ->
3691         generate_prototype
3692           ~single_line:true ~newline:true ~in_daemon:true ~prefix:"do_"
3693           name style;
3694   ) daemon_functions
3695
3696 (* Generate the server-side stubs. *)
3697 and generate_daemon_actions () =
3698   generate_header CStyle GPLv2;
3699
3700   pr "#include <config.h>\n";
3701   pr "\n";
3702   pr "#include <stdio.h>\n";
3703   pr "#include <stdlib.h>\n";
3704   pr "#include <string.h>\n";
3705   pr "#include <inttypes.h>\n";
3706   pr "#include <ctype.h>\n";
3707   pr "#include <rpc/types.h>\n";
3708   pr "#include <rpc/xdr.h>\n";
3709   pr "\n";
3710   pr "#include \"daemon.h\"\n";
3711   pr "#include \"../src/guestfs_protocol.h\"\n";
3712   pr "#include \"actions.h\"\n";
3713   pr "\n";
3714
3715   List.iter (
3716     fun (name, style, _, _, _, _, _) ->
3717       (* Generate server-side stubs. *)
3718       pr "static void %s_stub (XDR *xdr_in)\n" name;
3719       pr "{\n";
3720       let error_code =
3721         match fst style with
3722         | RErr | RInt _ -> pr "  int r;\n"; "-1"
3723         | RInt64 _ -> pr "  int64_t r;\n"; "-1"
3724         | RBool _ -> pr "  int r;\n"; "-1"
3725         | RConstString _ ->
3726             failwithf "RConstString cannot be returned from a daemon function"
3727         | RString _ -> pr "  char *r;\n"; "NULL"
3728         | RStringList _ | RHashtable _ -> pr "  char **r;\n"; "NULL"
3729         | RIntBool _ -> pr "  guestfs_%s_ret *r;\n" name; "NULL"
3730         | RPVList _ -> pr "  guestfs_lvm_int_pv_list *r;\n"; "NULL"
3731         | RVGList _ -> pr "  guestfs_lvm_int_vg_list *r;\n"; "NULL"
3732         | RLVList _ -> pr "  guestfs_lvm_int_lv_list *r;\n"; "NULL"
3733         | RStat _ -> pr "  guestfs_int_stat *r;\n"; "NULL"
3734         | RStatVFS _ -> pr "  guestfs_int_statvfs *r;\n"; "NULL" in
3735
3736       (match snd style with
3737        | [] -> ()
3738        | args ->
3739            pr "  struct guestfs_%s_args args;\n" name;
3740            List.iter (
3741              function
3742                (* Note we allow the string to be writable, in order to
3743                 * allow device name translation.  This is safe because
3744                 * we can modify the string (passed from RPC).
3745                 *)
3746              | String n
3747              | OptString n -> pr "  char *%s;\n" n
3748              | StringList n -> pr "  char **%s;\n" n
3749              | Bool n -> pr "  int %s;\n" n
3750              | Int n -> pr "  int %s;\n" n
3751              | FileIn _ | FileOut _ -> ()
3752            ) args
3753       );
3754       pr "\n";
3755
3756       (match snd style with
3757        | [] -> ()
3758        | args ->
3759            pr "  memset (&args, 0, sizeof args);\n";
3760            pr "\n";
3761            pr "  if (!xdr_guestfs_%s_args (xdr_in, &args)) {\n" name;
3762            pr "    reply_with_error (\"%%s: daemon failed to decode procedure arguments\", \"%s\");\n" name;
3763            pr "    return;\n";
3764            pr "  }\n";
3765            List.iter (
3766              function
3767              | String n -> pr "  %s = args.%s;\n" n n
3768              | OptString n -> pr "  %s = args.%s ? *args.%s : NULL;\n" n n n
3769              | StringList n ->
3770                  pr "  %s = realloc (args.%s.%s_val,\n" n n n;
3771                  pr "                sizeof (char *) * (args.%s.%s_len+1));\n" n n;
3772                  pr "  if (%s == NULL) {\n" n;
3773                  pr "    reply_with_perror (\"realloc\");\n";
3774                  pr "    goto done;\n";
3775                  pr "  }\n";
3776                  pr "  %s[args.%s.%s_len] = NULL;\n" n n n;
3777                  pr "  args.%s.%s_val = %s;\n" n n n;
3778              | Bool n -> pr "  %s = args.%s;\n" n n
3779              | Int n -> pr "  %s = args.%s;\n" n n
3780              | FileIn _ | FileOut _ -> ()
3781            ) args;
3782            pr "\n"
3783       );
3784
3785       (* Don't want to call the impl with any FileIn or FileOut
3786        * parameters, since these go "outside" the RPC protocol.
3787        *)
3788       let argsnofile =
3789         List.filter (function FileIn _ | FileOut _ -> false | _ -> true)
3790           (snd style) in
3791       pr "  r = do_%s " name;
3792       generate_call_args argsnofile;
3793       pr ";\n";
3794
3795       pr "  if (r == %s)\n" error_code;
3796       pr "    /* do_%s has already called reply_with_error */\n" name;
3797       pr "    goto done;\n";
3798       pr "\n";
3799
3800       (* If there are any FileOut parameters, then the impl must
3801        * send its own reply.
3802        *)
3803       let no_reply =
3804         List.exists (function FileOut _ -> true | _ -> false) (snd style) in
3805       if no_reply then
3806         pr "  /* do_%s has already sent a reply */\n" name
3807       else (
3808         match fst style with
3809         | RErr -> pr "  reply (NULL, NULL);\n"
3810         | RInt n | RInt64 n | RBool n ->
3811             pr "  struct guestfs_%s_ret ret;\n" name;
3812             pr "  ret.%s = r;\n" n;
3813             pr "  reply ((xdrproc_t) &xdr_guestfs_%s_ret, (char *) &ret);\n"
3814               name
3815         | RConstString _ ->
3816             failwithf "RConstString cannot be returned from a daemon function"
3817         | RString n ->
3818             pr "  struct guestfs_%s_ret ret;\n" name;
3819             pr "  ret.%s = r;\n" n;
3820             pr "  reply ((xdrproc_t) &xdr_guestfs_%s_ret, (char *) &ret);\n"
3821               name;
3822             pr "  free (r);\n"
3823         | RStringList n | RHashtable n ->
3824             pr "  struct guestfs_%s_ret ret;\n" name;
3825             pr "  ret.%s.%s_len = count_strings (r);\n" n n;
3826             pr "  ret.%s.%s_val = r;\n" n n;
3827             pr "  reply ((xdrproc_t) &xdr_guestfs_%s_ret, (char *) &ret);\n"
3828               name;
3829             pr "  free_strings (r);\n"
3830         | RIntBool _ ->
3831             pr "  reply ((xdrproc_t) xdr_guestfs_%s_ret, (char *) r);\n"
3832               name;
3833             pr "  xdr_free ((xdrproc_t) xdr_guestfs_%s_ret, (char *) r);\n" name
3834         | RPVList n | RVGList n | RLVList n
3835         | RStat n | RStatVFS n ->
3836             pr "  struct guestfs_%s_ret ret;\n" name;
3837             pr "  ret.%s = *r;\n" n;
3838             pr "  reply ((xdrproc_t) xdr_guestfs_%s_ret, (char *) &ret);\n"
3839               name;
3840             pr "  xdr_free ((xdrproc_t) xdr_guestfs_%s_ret, (char *) &ret);\n"
3841               name
3842       );
3843
3844       (* Free the args. *)
3845       (match snd style with
3846        | [] ->
3847            pr "done: ;\n";
3848        | _ ->
3849            pr "done:\n";
3850            pr "  xdr_free ((xdrproc_t) xdr_guestfs_%s_args, (char *) &args);\n"
3851              name
3852       );
3853
3854       pr "}\n\n";
3855   ) daemon_functions;
3856
3857   (* Dispatch function. *)
3858   pr "void dispatch_incoming_message (XDR *xdr_in)\n";
3859   pr "{\n";
3860   pr "  switch (proc_nr) {\n";
3861
3862   List.iter (
3863     fun (name, style, _, _, _, _, _) ->
3864         pr "    case GUESTFS_PROC_%s:\n" (String.uppercase name);
3865         pr "      %s_stub (xdr_in);\n" name;
3866         pr "      break;\n"
3867   ) daemon_functions;
3868
3869   pr "    default:\n";
3870   pr "      reply_with_error (\"dispatch_incoming_message: unknown procedure number %%d, set LIBGUESTFS_PATH to point to the matching libguestfs appliance directory\", proc_nr);\n";
3871   pr "  }\n";
3872   pr "}\n";
3873   pr "\n";
3874
3875   (* LVM columns and tokenization functions. *)
3876   (* XXX This generates crap code.  We should rethink how we
3877    * do this parsing.
3878    *)
3879   List.iter (
3880     function
3881     | typ, cols ->
3882         pr "static const char *lvm_%s_cols = \"%s\";\n"
3883           typ (String.concat "," (List.map fst cols));
3884         pr "\n";
3885
3886         pr "static int lvm_tokenize_%s (char *str, struct guestfs_lvm_int_%s *r)\n" typ typ;
3887         pr "{\n";
3888         pr "  char *tok, *p, *next;\n";
3889         pr "  int i, j;\n";
3890         pr "\n";
3891         (*
3892         pr "  fprintf (stderr, \"%%s: <<%%s>>\\n\", __func__, str);\n";
3893         pr "\n";
3894         *)
3895         pr "  if (!str) {\n";
3896         pr "    fprintf (stderr, \"%%s: failed: passed a NULL string\\n\", __func__);\n";
3897         pr "    return -1;\n";
3898         pr "  }\n";
3899         pr "  if (!*str || isspace (*str)) {\n";
3900         pr "    fprintf (stderr, \"%%s: failed: passed a empty string or one beginning with whitespace\\n\", __func__);\n";
3901         pr "    return -1;\n";
3902         pr "  }\n";
3903         pr "  tok = str;\n";
3904         List.iter (
3905           fun (name, coltype) ->
3906             pr "  if (!tok) {\n";
3907             pr "    fprintf (stderr, \"%%s: failed: string finished early, around token %%s\\n\", __func__, \"%s\");\n" name;
3908             pr "    return -1;\n";
3909             pr "  }\n";
3910             pr "  p = strchrnul (tok, ',');\n";
3911             pr "  if (*p) next = p+1; else next = NULL;\n";
3912             pr "  *p = '\\0';\n";
3913             (match coltype with
3914              | `String ->
3915                  pr "  r->%s = strdup (tok);\n" name;
3916                  pr "  if (r->%s == NULL) {\n" name;
3917                  pr "    perror (\"strdup\");\n";
3918                  pr "    return -1;\n";
3919                  pr "  }\n"
3920              | `UUID ->
3921                  pr "  for (i = j = 0; i < 32; ++j) {\n";
3922                  pr "    if (tok[j] == '\\0') {\n";
3923                  pr "      fprintf (stderr, \"%%s: failed to parse UUID from '%%s'\\n\", __func__, tok);\n";
3924                  pr "      return -1;\n";
3925                  pr "    } else if (tok[j] != '-')\n";
3926                  pr "      r->%s[i++] = tok[j];\n" name;
3927                  pr "  }\n";
3928              | `Bytes ->
3929                  pr "  if (sscanf (tok, \"%%\"SCNu64, &r->%s) != 1) {\n" name;
3930                  pr "    fprintf (stderr, \"%%s: failed to parse size '%%s' from token %%s\\n\", __func__, tok, \"%s\");\n" name;
3931                  pr "    return -1;\n";
3932                  pr "  }\n";
3933              | `Int ->
3934                  pr "  if (sscanf (tok, \"%%\"SCNi64, &r->%s) != 1) {\n" name;
3935                  pr "    fprintf (stderr, \"%%s: failed to parse int '%%s' from token %%s\\n\", __func__, tok, \"%s\");\n" name;
3936                  pr "    return -1;\n";
3937                  pr "  }\n";
3938              | `OptPercent ->
3939                  pr "  if (tok[0] == '\\0')\n";
3940                  pr "    r->%s = -1;\n" name;
3941                  pr "  else if (sscanf (tok, \"%%f\", &r->%s) != 1) {\n" name;
3942                  pr "    fprintf (stderr, \"%%s: failed to parse float '%%s' from token %%s\\n\", __func__, tok, \"%s\");\n" name;
3943                  pr "    return -1;\n";
3944                  pr "  }\n";
3945             );
3946             pr "  tok = next;\n";
3947         ) cols;
3948
3949         pr "  if (tok != NULL) {\n";
3950         pr "    fprintf (stderr, \"%%s: failed: extra tokens at end of string\\n\", __func__);\n";
3951         pr "    return -1;\n";
3952         pr "  }\n";
3953         pr "  return 0;\n";
3954         pr "}\n";
3955         pr "\n";
3956
3957         pr "guestfs_lvm_int_%s_list *\n" typ;
3958         pr "parse_command_line_%ss (void)\n" typ;
3959         pr "{\n";
3960         pr "  char *out, *err;\n";
3961         pr "  char *p, *pend;\n";
3962         pr "  int r, i;\n";
3963         pr "  guestfs_lvm_int_%s_list *ret;\n" typ;
3964         pr "  void *newp;\n";
3965         pr "\n";
3966         pr "  ret = malloc (sizeof *ret);\n";
3967         pr "  if (!ret) {\n";
3968         pr "    reply_with_perror (\"malloc\");\n";
3969         pr "    return NULL;\n";
3970         pr "  }\n";
3971         pr "\n";
3972         pr "  ret->guestfs_lvm_int_%s_list_len = 0;\n" typ;
3973         pr "  ret->guestfs_lvm_int_%s_list_val = NULL;\n" typ;
3974         pr "\n";
3975         pr "  r = command (&out, &err,\n";
3976         pr "           \"/sbin/lvm\", \"%ss\",\n" typ;
3977         pr "           \"-o\", lvm_%s_cols, \"--unbuffered\", \"--noheadings\",\n" typ;
3978         pr "           \"--nosuffix\", \"--separator\", \",\", \"--units\", \"b\", NULL);\n";
3979         pr "  if (r == -1) {\n";
3980         pr "    reply_with_error (\"%%s\", err);\n";
3981         pr "    free (out);\n";
3982         pr "    free (err);\n";
3983         pr "    free (ret);\n";
3984         pr "    return NULL;\n";
3985         pr "  }\n";
3986         pr "\n";
3987         pr "  free (err);\n";
3988         pr "\n";
3989         pr "  /* Tokenize each line of the output. */\n";
3990         pr "  p = out;\n";
3991         pr "  i = 0;\n";
3992         pr "  while (p) {\n";
3993         pr "    pend = strchr (p, '\\n');       /* Get the next line of output. */\n";
3994         pr "    if (pend) {\n";
3995         pr "      *pend = '\\0';\n";
3996         pr "      pend++;\n";
3997         pr "    }\n";
3998         pr "\n";
3999         pr "    while (*p && isspace (*p))      /* Skip any leading whitespace. */\n";
4000         pr "      p++;\n";
4001         pr "\n";
4002         pr "    if (!*p) {                      /* Empty line?  Skip it. */\n";
4003         pr "      p = pend;\n";
4004         pr "      continue;\n";
4005         pr "    }\n";
4006         pr "\n";
4007         pr "    /* Allocate some space to store this next entry. */\n";
4008         pr "    newp = realloc (ret->guestfs_lvm_int_%s_list_val,\n" typ;
4009         pr "                sizeof (guestfs_lvm_int_%s) * (i+1));\n" typ;
4010         pr "    if (newp == NULL) {\n";
4011         pr "      reply_with_perror (\"realloc\");\n";
4012         pr "      free (ret->guestfs_lvm_int_%s_list_val);\n" typ;
4013         pr "      free (ret);\n";
4014         pr "      free (out);\n";
4015         pr "      return NULL;\n";
4016         pr "    }\n";
4017         pr "    ret->guestfs_lvm_int_%s_list_val = newp;\n" typ;
4018         pr "\n";
4019         pr "    /* Tokenize the next entry. */\n";
4020         pr "    r = lvm_tokenize_%s (p, &ret->guestfs_lvm_int_%s_list_val[i]);\n" typ typ;
4021         pr "    if (r == -1) {\n";
4022         pr "      reply_with_error (\"failed to parse output of '%ss' command\");\n" typ;
4023         pr "      free (ret->guestfs_lvm_int_%s_list_val);\n" typ;
4024         pr "      free (ret);\n";
4025         pr "      free (out);\n";
4026         pr "      return NULL;\n";
4027         pr "    }\n";
4028         pr "\n";
4029         pr "    ++i;\n";
4030         pr "    p = pend;\n";
4031         pr "  }\n";
4032         pr "\n";
4033         pr "  ret->guestfs_lvm_int_%s_list_len = i;\n" typ;
4034         pr "\n";
4035         pr "  free (out);\n";
4036         pr "  return ret;\n";
4037         pr "}\n"
4038
4039   ) ["pv", pv_cols; "vg", vg_cols; "lv", lv_cols]
4040
4041 (* Generate the tests. *)
4042 and generate_tests () =
4043   generate_header CStyle GPLv2;
4044
4045   pr "\
4046 #include <stdio.h>
4047 #include <stdlib.h>
4048 #include <string.h>
4049 #include <unistd.h>
4050 #include <sys/types.h>
4051 #include <fcntl.h>
4052
4053 #include \"guestfs.h\"
4054
4055 static guestfs_h *g;
4056 static int suppress_error = 0;
4057
4058 static void print_error (guestfs_h *g, void *data, const char *msg)
4059 {
4060   if (!suppress_error)
4061     fprintf (stderr, \"%%s\\n\", msg);
4062 }
4063
4064 static void print_strings (char * const * const argv)
4065 {
4066   int argc;
4067
4068   for (argc = 0; argv[argc] != NULL; ++argc)
4069     printf (\"\\t%%s\\n\", argv[argc]);
4070 }
4071
4072 /*
4073 static void print_table (char * const * const argv)
4074 {
4075   int i;
4076
4077   for (i = 0; argv[i] != NULL; i += 2)
4078     printf (\"%%s: %%s\\n\", argv[i], argv[i+1]);
4079 }
4080 */
4081
4082 static void no_test_warnings (void)
4083 {
4084 ";
4085
4086   List.iter (
4087     function
4088     | name, _, _, _, [], _, _ ->
4089         pr "  fprintf (stderr, \"warning: \\\"guestfs_%s\\\" has no tests\\n\");\n" name
4090     | name, _, _, _, tests, _, _ -> ()
4091   ) all_functions;
4092
4093   pr "}\n";
4094   pr "\n";
4095
4096   (* Generate the actual tests.  Note that we generate the tests
4097    * in reverse order, deliberately, so that (in general) the
4098    * newest tests run first.  This makes it quicker and easier to
4099    * debug them.
4100    *)
4101   let test_names =
4102     List.map (
4103       fun (name, _, _, _, tests, _, _) ->
4104         mapi (generate_one_test name) tests
4105     ) (List.rev all_functions) in
4106   let test_names = List.concat test_names in
4107   let nr_tests = List.length test_names in
4108
4109   pr "\
4110 int main (int argc, char *argv[])
4111 {
4112   char c = 0;
4113   int failed = 0;
4114   const char *filename;
4115   int fd;
4116   int nr_tests, test_num = 0;
4117
4118   no_test_warnings ();
4119
4120   g = guestfs_create ();
4121   if (g == NULL) {
4122     printf (\"guestfs_create FAILED\\n\");
4123     exit (1);
4124   }
4125
4126   guestfs_set_error_handler (g, print_error, NULL);
4127
4128   guestfs_set_path (g, \"../appliance\");
4129
4130   filename = \"test1.img\";
4131   fd = open (filename, O_WRONLY|O_CREAT|O_NOCTTY|O_NONBLOCK|O_TRUNC, 0666);
4132   if (fd == -1) {
4133     perror (filename);
4134     exit (1);
4135   }
4136   if (lseek (fd, %d, SEEK_SET) == -1) {
4137     perror (\"lseek\");
4138     close (fd);
4139     unlink (filename);
4140     exit (1);
4141   }
4142   if (write (fd, &c, 1) == -1) {
4143     perror (\"write\");
4144     close (fd);
4145     unlink (filename);
4146     exit (1);
4147   }
4148   if (close (fd) == -1) {
4149     perror (filename);
4150     unlink (filename);
4151     exit (1);
4152   }
4153   if (guestfs_add_drive (g, filename) == -1) {
4154     printf (\"guestfs_add_drive %%s FAILED\\n\", filename);
4155     exit (1);
4156   }
4157
4158   filename = \"test2.img\";
4159   fd = open (filename, O_WRONLY|O_CREAT|O_NOCTTY|O_NONBLOCK|O_TRUNC, 0666);
4160   if (fd == -1) {
4161     perror (filename);
4162     exit (1);
4163   }
4164   if (lseek (fd, %d, SEEK_SET) == -1) {
4165     perror (\"lseek\");
4166     close (fd);
4167     unlink (filename);
4168     exit (1);
4169   }
4170   if (write (fd, &c, 1) == -1) {
4171     perror (\"write\");
4172     close (fd);
4173     unlink (filename);
4174     exit (1);
4175   }
4176   if (close (fd) == -1) {
4177     perror (filename);
4178     unlink (filename);
4179     exit (1);
4180   }
4181   if (guestfs_add_drive (g, filename) == -1) {
4182     printf (\"guestfs_add_drive %%s FAILED\\n\", filename);
4183     exit (1);
4184   }
4185
4186   filename = \"test3.img\";
4187   fd = open (filename, O_WRONLY|O_CREAT|O_NOCTTY|O_NONBLOCK|O_TRUNC, 0666);
4188   if (fd == -1) {
4189     perror (filename);
4190     exit (1);
4191   }
4192   if (lseek (fd, %d, SEEK_SET) == -1) {
4193     perror (\"lseek\");
4194     close (fd);
4195     unlink (filename);
4196     exit (1);
4197   }
4198   if (write (fd, &c, 1) == -1) {
4199     perror (\"write\");
4200     close (fd);
4201     unlink (filename);
4202     exit (1);
4203   }
4204   if (close (fd) == -1) {
4205     perror (filename);
4206     unlink (filename);
4207     exit (1);
4208   }
4209   if (guestfs_add_drive (g, filename) == -1) {
4210     printf (\"guestfs_add_drive %%s FAILED\\n\", filename);
4211     exit (1);
4212   }
4213
4214   if (guestfs_add_drive_ro (g, \"../images/test.sqsh\") == -1) {
4215     printf (\"guestfs_add_drive_ro ../images/test.sqsh FAILED\\n\");
4216     exit (1);
4217   }
4218
4219   if (guestfs_launch (g) == -1) {
4220     printf (\"guestfs_launch FAILED\\n\");
4221     exit (1);
4222   }
4223
4224   /* Set a timeout in case qemu hangs during launch (RHBZ#505329). */
4225   alarm (600);
4226
4227   if (guestfs_wait_ready (g) == -1) {
4228     printf (\"guestfs_wait_ready FAILED\\n\");
4229     exit (1);
4230   }
4231
4232   /* Cancel previous alarm. */
4233   alarm (0);
4234
4235   nr_tests = %d;
4236
4237 " (500 * 1024 * 1024) (50 * 1024 * 1024) (10 * 1024 * 1024) nr_tests;
4238
4239   iteri (
4240     fun i test_name ->
4241       pr "  test_num++;\n";
4242       pr "  printf (\"%%3d/%%3d %s\\n\", test_num, nr_tests);\n" test_name;
4243       pr "  if (%s () == -1) {\n" test_name;
4244       pr "    printf (\"%s FAILED\\n\");\n" test_name;
4245       pr "    failed++;\n";
4246       pr "  }\n";
4247   ) test_names;
4248   pr "\n";
4249
4250   pr "  guestfs_close (g);\n";
4251   pr "  unlink (\"test1.img\");\n";
4252   pr "  unlink (\"test2.img\");\n";
4253   pr "  unlink (\"test3.img\");\n";
4254   pr "\n";
4255
4256   pr "  if (failed > 0) {\n";
4257   pr "    printf (\"***** %%d / %%d tests FAILED *****\\n\", failed, nr_tests);\n";
4258   pr "    exit (1);\n";
4259   pr "  }\n";
4260   pr "\n";
4261
4262   pr "  exit (0);\n";
4263   pr "}\n"
4264
4265 and generate_one_test name i (init, prereq, test) =
4266   let test_name = sprintf "test_%s_%d" name i in
4267
4268   pr "\
4269 static int %s_skip (void)
4270 {
4271   const char *str;
4272
4273   str = getenv (\"TEST_ONLY\");
4274   if (str)
4275     return strstr (str, \"%s\") == NULL;
4276   str = getenv (\"SKIP_%s\");
4277   if (str && strcmp (str, \"1\") == 0) return 1;
4278   str = getenv (\"SKIP_TEST_%s\");
4279   if (str && strcmp (str, \"1\") == 0) return 1;
4280   return 0;
4281 }
4282
4283 " test_name name (String.uppercase test_name) (String.uppercase name);
4284
4285   (match prereq with
4286    | Disabled | Always -> ()
4287    | If code | Unless code ->
4288        pr "static int %s_prereq (void)\n" test_name;
4289        pr "{\n";
4290        pr "  %s\n" code;
4291        pr "}\n";
4292        pr "\n";
4293   );
4294
4295   pr "\
4296 static int %s (void)
4297 {
4298   if (%s_skip ()) {
4299     printf (\"%%s skipped (reason: environment variable set)\\n\", \"%s\");
4300     return 0;
4301   }
4302
4303 " test_name test_name test_name;
4304
4305   (match prereq with
4306    | Disabled ->
4307        pr "  printf (\"%%s skipped (reason: test disabled in generator)\\n\", \"%s\");\n" test_name
4308    | If _ ->
4309        pr "  if (! %s_prereq ()) {\n" test_name;
4310        pr "    printf (\"%%s skipped (reason: test prerequisite)\\n\", \"%s\");\n" test_name;
4311        pr "    return 0;\n";
4312        pr "  }\n";
4313        pr "\n";
4314        generate_one_test_body name i test_name init test;
4315    | Unless _ ->
4316        pr "  if (%s_prereq ()) {\n" test_name;
4317        pr "    printf (\"%%s skipped (reason: test prerequisite)\\n\", \"%s\");\n" test_name;
4318        pr "    return 0;\n";
4319        pr "  }\n";
4320        pr "\n";
4321        generate_one_test_body name i test_name init test;
4322    | Always ->
4323        generate_one_test_body name i test_name init test
4324   );
4325
4326   pr "  return 0;\n";
4327   pr "}\n";
4328   pr "\n";
4329   test_name