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