Command line argument handling.
[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   ("grub_install", (RErr, [String "root"; String "device"]), 86, [],
1988    [InitBasicFS, Always, TestOutputTrue (
1989       [["grub_install"; "/"; "/dev/sda1"];
1990        ["is_dir"; "/boot"]])],
1991    "install GRUB",
1992    "\
1993 This command installs GRUB (the Grand Unified Bootloader) on
1994 C<device>, with the root directory being C<root>.");
1995
1996   ("cp", (RErr, [String "src"; String "dest"]), 87, [],
1997    [InitBasicFS, Always, TestOutput (
1998       [["write_file"; "/old"; "file content"; "0"];
1999        ["cp"; "/old"; "/new"];
2000        ["cat"; "/new"]], "file content");
2001     InitBasicFS, Always, TestOutputTrue (
2002       [["write_file"; "/old"; "file content"; "0"];
2003        ["cp"; "/old"; "/new"];
2004        ["is_file"; "/old"]]);
2005     InitBasicFS, Always, TestOutput (
2006       [["write_file"; "/old"; "file content"; "0"];
2007        ["mkdir"; "/dir"];
2008        ["cp"; "/old"; "/dir/new"];
2009        ["cat"; "/dir/new"]], "file content")],
2010    "copy a file",
2011    "\
2012 This copies a file from C<src> to C<dest> where C<dest> is
2013 either a destination filename or destination directory.");
2014
2015   ("cp_a", (RErr, [String "src"; String "dest"]), 88, [],
2016    [InitBasicFS, Always, TestOutput (
2017       [["mkdir"; "/olddir"];
2018        ["mkdir"; "/newdir"];
2019        ["write_file"; "/olddir/file"; "file content"; "0"];
2020        ["cp_a"; "/olddir"; "/newdir"];
2021        ["cat"; "/newdir/olddir/file"]], "file content")],
2022    "copy a file or directory recursively",
2023    "\
2024 This copies a file or directory from C<src> to C<dest>
2025 recursively using the C<cp -a> command.");
2026
2027   ("mv", (RErr, [String "src"; String "dest"]), 89, [],
2028    [InitBasicFS, Always, TestOutput (
2029       [["write_file"; "/old"; "file content"; "0"];
2030        ["mv"; "/old"; "/new"];
2031        ["cat"; "/new"]], "file content");
2032     InitBasicFS, Always, TestOutputFalse (
2033       [["write_file"; "/old"; "file content"; "0"];
2034        ["mv"; "/old"; "/new"];
2035        ["is_file"; "/old"]])],
2036    "move a file",
2037    "\
2038 This moves a file from C<src> to C<dest> where C<dest> is
2039 either a destination filename or destination directory.");
2040
2041   ("drop_caches", (RErr, [Int "whattodrop"]), 90, [],
2042    [InitEmpty, Always, TestRun (
2043       [["drop_caches"; "3"]])],
2044    "drop kernel page cache, dentries and inodes",
2045    "\
2046 This instructs the guest kernel to drop its page cache,
2047 and/or dentries and inode caches.  The parameter C<whattodrop>
2048 tells the kernel what precisely to drop, see
2049 L<http://linux-mm.org/Drop_Caches>
2050
2051 Setting C<whattodrop> to 3 should drop everything.
2052
2053 This automatically calls L<sync(2)> before the operation,
2054 so that the maximum guest memory is freed.");
2055
2056   ("dmesg", (RString "kmsgs", []), 91, [],
2057    [InitEmpty, Always, TestRun (
2058       [["dmesg"]])],
2059    "return kernel messages",
2060    "\
2061 This returns the kernel messages (C<dmesg> output) from
2062 the guest kernel.  This is sometimes useful for extended
2063 debugging of problems.
2064
2065 Another way to get the same information is to enable
2066 verbose messages with C<guestfs_set_verbose> or by setting
2067 the environment variable C<LIBGUESTFS_DEBUG=1> before
2068 running the program.");
2069
2070   ("ping_daemon", (RErr, []), 92, [],
2071    [InitEmpty, Always, TestRun (
2072       [["ping_daemon"]])],
2073    "ping the guest daemon",
2074    "\
2075 This is a test probe into the guestfs daemon running inside
2076 the qemu subprocess.  Calling this function checks that the
2077 daemon responds to the ping message, without affecting the daemon
2078 or attached block device(s) in any other way.");
2079
2080   ("equal", (RBool "equality", [String "file1"; String "file2"]), 93, [],
2081    [InitBasicFS, Always, TestOutputTrue (
2082       [["write_file"; "/file1"; "contents of a file"; "0"];
2083        ["cp"; "/file1"; "/file2"];
2084        ["equal"; "/file1"; "/file2"]]);
2085     InitBasicFS, Always, TestOutputFalse (
2086       [["write_file"; "/file1"; "contents of a file"; "0"];
2087        ["write_file"; "/file2"; "contents of another file"; "0"];
2088        ["equal"; "/file1"; "/file2"]]);
2089     InitBasicFS, Always, TestLastFail (
2090       [["equal"; "/file1"; "/file2"]])],
2091    "test if two files have equal contents",
2092    "\
2093 This compares the two files C<file1> and C<file2> and returns
2094 true if their content is exactly equal, or false otherwise.
2095
2096 The external L<cmp(1)> program is used for the comparison.");
2097
2098   ("strings", (RStringList "stringsout", [String "path"]), 94, [ProtocolLimitWarning],
2099    [InitBasicFS, Always, TestOutputList (
2100       [["write_file"; "/new"; "hello\nworld\n"; "0"];
2101        ["strings"; "/new"]], ["hello"; "world"]);
2102     InitBasicFS, Always, TestOutputList (
2103       [["touch"; "/new"];
2104        ["strings"; "/new"]], [])],
2105    "print the printable strings in a file",
2106    "\
2107 This runs the L<strings(1)> command on a file and returns
2108 the list of printable strings found.");
2109
2110   ("strings_e", (RStringList "stringsout", [String "encoding"; String "path"]), 95, [ProtocolLimitWarning],
2111    [InitBasicFS, Always, TestOutputList (
2112       [["write_file"; "/new"; "hello\nworld\n"; "0"];
2113        ["strings_e"; "b"; "/new"]], []);
2114     InitBasicFS, Disabled, TestOutputList (
2115       [["write_file"; "/new"; "\000h\000e\000l\000l\000o\000\n\000w\000o\000r\000l\000d\000\n"; "24"];
2116        ["strings_e"; "b"; "/new"]], ["hello"; "world"])],
2117    "print the printable strings in a file",
2118    "\
2119 This is like the C<guestfs_strings> command, but allows you to
2120 specify the encoding.
2121
2122 See the L<strings(1)> manpage for the full list of encodings.
2123
2124 Commonly useful encodings are C<l> (lower case L) which will
2125 show strings inside Windows/x86 files.
2126
2127 The returned strings are transcoded to UTF-8.");
2128
2129   ("hexdump", (RString "dump", [String "path"]), 96, [ProtocolLimitWarning],
2130    [InitBasicFS, Always, TestOutput (
2131       [["write_file"; "/new"; "hello\nworld\n"; "12"];
2132        ["hexdump"; "/new"]], "00000000  68 65 6c 6c 6f 0a 77 6f  72 6c 64 0a              |hello.world.|\n0000000c\n")],
2133    "dump a file in hexadecimal",
2134    "\
2135 This runs C<hexdump -C> on the given C<path>.  The result is
2136 the human-readable, canonical hex dump of the file.");
2137
2138   ("zerofree", (RErr, [String "device"]), 97, [],
2139    [InitNone, Always, TestOutput (
2140       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
2141        ["mkfs"; "ext3"; "/dev/sda1"];
2142        ["mount"; "/dev/sda1"; "/"];
2143        ["write_file"; "/new"; "test file"; "0"];
2144        ["umount"; "/dev/sda1"];
2145        ["zerofree"; "/dev/sda1"];
2146        ["mount"; "/dev/sda1"; "/"];
2147        ["cat"; "/new"]], "test file")],
2148    "zero unused inodes and disk blocks on ext2/3 filesystem",
2149    "\
2150 This runs the I<zerofree> program on C<device>.  This program
2151 claims to zero unused inodes and disk blocks on an ext2/3
2152 filesystem, thus making it possible to compress the filesystem
2153 more effectively.
2154
2155 You should B<not> run this program if the filesystem is
2156 mounted.
2157
2158 It is possible that using this program can damage the filesystem
2159 or data on the filesystem.");
2160
2161   ("pvresize", (RErr, [String "device"]), 98, [],
2162    [],
2163    "resize an LVM physical volume",
2164    "\
2165 This resizes (expands or shrinks) an existing LVM physical
2166 volume to match the new size of the underlying device.");
2167
2168   ("sfdisk_N", (RErr, [String "device"; Int "n";
2169                        Int "cyls"; Int "heads"; Int "sectors";
2170                        String "line"]), 99, [DangerWillRobinson],
2171    [],
2172    "modify a single partition on a block device",
2173    "\
2174 This runs L<sfdisk(8)> option to modify just the single
2175 partition C<n> (note: C<n> counts from 1).
2176
2177 For other parameters, see C<guestfs_sfdisk>.  You should usually
2178 pass C<0> for the cyls/heads/sectors parameters.");
2179
2180   ("sfdisk_l", (RString "partitions", [String "device"]), 100, [],
2181    [],
2182    "display the partition table",
2183    "\
2184 This displays the partition table on C<device>, in the
2185 human-readable output of the L<sfdisk(8)> command.  It is
2186 not intended to be parsed.");
2187
2188   ("sfdisk_kernel_geometry", (RString "partitions", [String "device"]), 101, [],
2189    [],
2190    "display the kernel geometry",
2191    "\
2192 This displays the kernel's idea of the geometry of C<device>.
2193
2194 The result is in human-readable format, and not designed to
2195 be parsed.");
2196
2197   ("sfdisk_disk_geometry", (RString "partitions", [String "device"]), 102, [],
2198    [],
2199    "display the disk geometry from the partition table",
2200    "\
2201 This displays the disk geometry of C<device> read from the
2202 partition table.  Especially in the case where the underlying
2203 block device has been resized, this can be different from the
2204 kernel's idea of the geometry (see C<guestfs_sfdisk_kernel_geometry>).
2205
2206 The result is in human-readable format, and not designed to
2207 be parsed.");
2208
2209   ("vg_activate_all", (RErr, [Bool "activate"]), 103, [],
2210    [],
2211    "activate or deactivate all volume groups",
2212    "\
2213 This command activates or (if C<activate> is false) deactivates
2214 all logical volumes in all volume groups.
2215 If activated, then they are made known to the
2216 kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
2217 then those devices disappear.
2218
2219 This command is the same as running C<vgchange -a y|n>");
2220
2221   ("vg_activate", (RErr, [Bool "activate"; StringList "volgroups"]), 104, [],
2222    [],
2223    "activate or deactivate some volume groups",
2224    "\
2225 This command activates or (if C<activate> is false) deactivates
2226 all logical volumes in the listed volume groups C<volgroups>.
2227 If activated, then they are made known to the
2228 kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
2229 then those devices disappear.
2230
2231 This command is the same as running C<vgchange -a y|n volgroups...>
2232
2233 Note that if C<volgroups> is an empty list then B<all> volume groups
2234 are activated or deactivated.");
2235
2236   ("lvresize", (RErr, [String "device"; Int "mbytes"]), 105, [],
2237    [InitNone, Always, TestOutput (
2238     [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
2239      ["pvcreate"; "/dev/sda1"];
2240      ["vgcreate"; "VG"; "/dev/sda1"];
2241      ["lvcreate"; "LV"; "VG"; "10"];
2242      ["mkfs"; "ext2"; "/dev/VG/LV"];
2243      ["mount"; "/dev/VG/LV"; "/"];
2244      ["write_file"; "/new"; "test content"; "0"];
2245      ["umount"; "/"];
2246      ["lvresize"; "/dev/VG/LV"; "20"];
2247      ["e2fsck_f"; "/dev/VG/LV"];
2248      ["resize2fs"; "/dev/VG/LV"];
2249      ["mount"; "/dev/VG/LV"; "/"];
2250      ["cat"; "/new"]], "test content")],
2251    "resize an LVM logical volume",
2252    "\
2253 This resizes (expands or shrinks) an existing LVM logical
2254 volume to C<mbytes>.  When reducing, data in the reduced part
2255 is lost.");
2256
2257   ("resize2fs", (RErr, [String "device"]), 106, [],
2258    [], (* lvresize tests this *)
2259    "resize an ext2/ext3 filesystem",
2260    "\
2261 This resizes an ext2 or ext3 filesystem to match the size of
2262 the underlying device.
2263
2264 I<Note:> It is sometimes required that you run C<guestfs_e2fsck_f>
2265 on the C<device> before calling this command.  For unknown reasons
2266 C<resize2fs> sometimes gives an error about this and sometimes not.
2267 In any case, it is always safe to call C<guestfs_e2fsck_f> before
2268 calling this function.");
2269
2270   ("find", (RStringList "names", [String "directory"]), 107, [],
2271    [InitBasicFS, Always, TestOutputList (
2272       [["find"; "/"]], ["lost+found"]);
2273     InitBasicFS, Always, TestOutputList (
2274       [["touch"; "/a"];
2275        ["mkdir"; "/b"];
2276        ["touch"; "/b/c"];
2277        ["find"; "/"]], ["a"; "b"; "b/c"; "lost+found"]);
2278     InitBasicFS, Always, TestOutputList (
2279       [["mkdir_p"; "/a/b/c"];
2280        ["touch"; "/a/b/c/d"];
2281        ["find"; "/a/b/"]], ["c"; "c/d"])],
2282    "find all files and directories",
2283    "\
2284 This command lists out all files and directories, recursively,
2285 starting at C<directory>.  It is essentially equivalent to
2286 running the shell command C<find directory -print> but some
2287 post-processing happens on the output, described below.
2288
2289 This returns a list of strings I<without any prefix>.  Thus
2290 if the directory structure was:
2291
2292  /tmp/a
2293  /tmp/b
2294  /tmp/c/d
2295
2296 then the returned list from C<guestfs_find> C</tmp> would be
2297 4 elements:
2298
2299  a
2300  b
2301  c
2302  c/d
2303
2304 If C<directory> is not a directory, then this command returns
2305 an error.
2306
2307 The returned list is sorted.");
2308
2309   ("e2fsck_f", (RErr, [String "device"]), 108, [],
2310    [], (* lvresize tests this *)
2311    "check an ext2/ext3 filesystem",
2312    "\
2313 This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3
2314 filesystem checker on C<device>, noninteractively (C<-p>),
2315 even if the filesystem appears to be clean (C<-f>).
2316
2317 This command is only needed because of C<guestfs_resize2fs>
2318 (q.v.).  Normally you should use C<guestfs_fsck>.");
2319
2320   ("sleep", (RErr, [Int "secs"]), 109, [],
2321    [InitNone, Always, TestRun (
2322     [["sleep"; "1"]])],
2323    "sleep for some seconds",
2324    "\
2325 Sleep for C<secs> seconds.");
2326
2327   ("ntfs_3g_probe", (RInt "status", [Bool "rw"; String "device"]), 110, [],
2328    [InitNone, Always, TestOutputInt (
2329       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
2330        ["mkfs"; "ntfs"; "/dev/sda1"];
2331        ["ntfs_3g_probe"; "true"; "/dev/sda1"]], 0);
2332     InitNone, Always, TestOutputInt (
2333       [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","];
2334        ["mkfs"; "ext2"; "/dev/sda1"];
2335        ["ntfs_3g_probe"; "true"; "/dev/sda1"]], 12)],
2336    "probe NTFS volume",
2337    "\
2338 This command runs the L<ntfs-3g.probe(8)> command which probes
2339 an NTFS C<device> for mountability.  (Not all NTFS volumes can
2340 be mounted read-write, and some cannot be mounted at all).
2341
2342 C<rw> is a boolean flag.  Set it to true if you want to test
2343 if the volume can be mounted read-write.  Set it to false if
2344 you want to test if the volume can be mounted read-only.
2345
2346 The return value is an integer which C<0> if the operation
2347 would succeed, or some non-zero value documented in the
2348 L<ntfs-3g.probe(8)> manual page.");
2349
2350   ("sh", (RString "output", [String "command"]), 111, [],
2351    [], (* XXX needs tests *)
2352    "run a command via the shell",
2353    "\
2354 This call runs a command from the guest filesystem via the
2355 guest's C</bin/sh>.
2356
2357 This is like C<guestfs_command>, but passes the command to:
2358
2359  /bin/sh -c \"command\"
2360
2361 Depending on the guest's shell, this usually results in
2362 wildcards being expanded, shell expressions being interpolated
2363 and so on.
2364
2365 All the provisos about C<guestfs_command> apply to this call.");
2366
2367   ("sh_lines", (RStringList "lines", [String "command"]), 112, [],
2368    [], (* XXX needs tests *)
2369    "run a command via the shell returning lines",
2370    "\
2371 This is the same as C<guestfs_sh>, but splits the result
2372 into a list of lines.
2373
2374 See also: C<guestfs_command_lines>");
2375
2376   ("glob_expand", (RStringList "paths", [String "pattern"]), 113, [],
2377    [InitBasicFS, Always, TestOutputList (
2378       [["mkdir_p"; "/a/b/c"];
2379        ["touch"; "/a/b/c/d"];
2380        ["touch"; "/a/b/c/e"];
2381        ["glob_expand"; "/a/b/c/*"]], ["/a/b/c/d"; "/a/b/c/e"]);
2382     InitBasicFS, Always, TestOutputList (
2383       [["mkdir_p"; "/a/b/c"];
2384        ["touch"; "/a/b/c/d"];
2385        ["touch"; "/a/b/c/e"];
2386        ["glob_expand"; "/a/*/c/*"]], ["/a/b/c/d"; "/a/b/c/e"]);
2387     InitBasicFS, Always, TestOutputList (
2388       [["mkdir_p"; "/a/b/c"];
2389        ["touch"; "/a/b/c/d"];
2390        ["touch"; "/a/b/c/e"];
2391        ["glob_expand"; "/a/*/x/*"]], [])],
2392    "expand a wildcard path",
2393    "\
2394 This command searches for all the pathnames matching
2395 C<pattern> according to the wildcard expansion rules
2396 used by the shell.
2397
2398 If no paths match, then this returns an empty list
2399 (note: not an error).
2400
2401 It is just a wrapper around the C L<glob(3)> function
2402 with flags C<GLOB_MARK|GLOB_BRACE>.
2403 See that manual page for more details.");
2404
2405 ]
2406
2407 let all_functions = non_daemon_functions @ daemon_functions
2408
2409 (* In some places we want the functions to be displayed sorted
2410  * alphabetically, so this is useful:
2411  *)
2412 let all_functions_sorted =
2413   List.sort (fun (n1,_,_,_,_,_,_) (n2,_,_,_,_,_,_) ->
2414                compare n1 n2) all_functions
2415
2416 (* Column names and types from LVM PVs/VGs/LVs. *)
2417 let pv_cols = [
2418   "pv_name", `String;
2419   "pv_uuid", `UUID;
2420   "pv_fmt", `String;
2421   "pv_size", `Bytes;
2422   "dev_size", `Bytes;
2423   "pv_free", `Bytes;
2424   "pv_used", `Bytes;
2425   "pv_attr", `String (* XXX *);
2426   "pv_pe_count", `Int;
2427   "pv_pe_alloc_count", `Int;
2428   "pv_tags", `String;
2429   "pe_start", `Bytes;
2430   "pv_mda_count", `Int;
2431   "pv_mda_free", `Bytes;
2432 (* Not in Fedora 10:
2433   "pv_mda_size", `Bytes;
2434 *)
2435 ]
2436 let vg_cols = [
2437   "vg_name", `String;
2438   "vg_uuid", `UUID;
2439   "vg_fmt", `String;
2440   "vg_attr", `String (* XXX *);
2441   "vg_size", `Bytes;
2442   "vg_free", `Bytes;
2443   "vg_sysid", `String;
2444   "vg_extent_size", `Bytes;
2445   "vg_extent_count", `Int;
2446   "vg_free_count", `Int;
2447   "max_lv", `Int;
2448   "max_pv", `Int;
2449   "pv_count", `Int;
2450   "lv_count", `Int;
2451   "snap_count", `Int;
2452   "vg_seqno", `Int;
2453   "vg_tags", `String;
2454   "vg_mda_count", `Int;
2455   "vg_mda_free", `Bytes;
2456 (* Not in Fedora 10:
2457   "vg_mda_size", `Bytes;
2458 *)
2459 ]
2460 let lv_cols = [
2461   "lv_name", `String;
2462   "lv_uuid", `UUID;
2463   "lv_attr", `String (* XXX *);
2464   "lv_major", `Int;
2465   "lv_minor", `Int;
2466   "lv_kernel_major", `Int;
2467   "lv_kernel_minor", `Int;
2468   "lv_size", `Bytes;
2469   "seg_count", `Int;
2470   "origin", `String;
2471   "snap_percent", `OptPercent;
2472   "copy_percent", `OptPercent;
2473   "move_pv", `String;
2474   "lv_tags", `String;
2475   "mirror_log", `String;
2476   "modules", `String;
2477 ]
2478
2479 (* Column names and types from stat structures.
2480  * NB. Can't use things like 'st_atime' because glibc header files
2481  * define some of these as macros.  Ugh.
2482  *)
2483 let stat_cols = [
2484   "dev", `Int;
2485   "ino", `Int;
2486   "mode", `Int;
2487   "nlink", `Int;
2488   "uid", `Int;
2489   "gid", `Int;
2490   "rdev", `Int;
2491   "size", `Int;
2492   "blksize", `Int;
2493   "blocks", `Int;
2494   "atime", `Int;
2495   "mtime", `Int;
2496   "ctime", `Int;
2497 ]
2498 let statvfs_cols = [
2499   "bsize", `Int;
2500   "frsize", `Int;
2501   "blocks", `Int;
2502   "bfree", `Int;
2503   "bavail", `Int;
2504   "files", `Int;
2505   "ffree", `Int;
2506   "favail", `Int;
2507   "fsid", `Int;
2508   "flag", `Int;
2509   "namemax", `Int;
2510 ]
2511
2512 (* Used for testing language bindings. *)
2513 type callt =
2514   | CallString of string
2515   | CallOptString of string option
2516   | CallStringList of string list
2517   | CallInt of int
2518   | CallBool of bool
2519
2520 (* Useful functions.
2521  * Note we don't want to use any external OCaml libraries which
2522  * makes this a bit harder than it should be.
2523  *)
2524 let failwithf fs = ksprintf failwith fs
2525
2526 let replace_char s c1 c2 =
2527   let s2 = String.copy s in
2528   let r = ref false in
2529   for i = 0 to String.length s2 - 1 do
2530     if String.unsafe_get s2 i = c1 then (
2531       String.unsafe_set s2 i c2;
2532       r := true
2533     )
2534   done;
2535   if not !r then s else s2
2536
2537 let isspace c =
2538   c = ' '
2539   (* || c = '\f' *) || c = '\n' || c = '\r' || c = '\t' (* || c = '\v' *)
2540
2541 let triml ?(test = isspace) str =
2542   let i = ref 0 in
2543   let n = ref (String.length str) in
2544   while !n > 0 && test str.[!i]; do
2545     decr n;
2546     incr i
2547   done;
2548   if !i = 0 then str
2549   else String.sub str !i !n
2550
2551 let trimr ?(test = isspace) str =
2552   let n = ref (String.length str) in
2553   while !n > 0 && test str.[!n-1]; do
2554     decr n
2555   done;
2556   if !n = String.length str then str
2557   else String.sub str 0 !n
2558
2559 let trim ?(test = isspace) str =
2560   trimr ~test (triml ~test str)
2561
2562 let rec find s sub =
2563   let len = String.length s in
2564   let sublen = String.length sub in
2565   let rec loop i =
2566     if i <= len-sublen then (
2567       let rec loop2 j =
2568         if j < sublen then (
2569           if s.[i+j] = sub.[j] then loop2 (j+1)
2570           else -1
2571         ) else
2572           i (* found *)
2573       in
2574       let r = loop2 0 in
2575       if r = -1 then loop (i+1) else r
2576     ) else
2577       -1 (* not found *)
2578   in
2579   loop 0
2580
2581 let rec replace_str s s1 s2 =
2582   let len = String.length s in
2583   let sublen = String.length s1 in
2584   let i = find s s1 in
2585   if i = -1 then s
2586   else (
2587     let s' = String.sub s 0 i in
2588     let s'' = String.sub s (i+sublen) (len-i-sublen) in
2589     s' ^ s2 ^ replace_str s'' s1 s2
2590   )
2591
2592 let rec string_split sep str =
2593   let len = String.length str in
2594   let seplen = String.length sep in
2595   let i = find str sep in
2596   if i = -1 then [str]
2597   else (
2598     let s' = String.sub str 0 i in
2599     let s'' = String.sub str (i+seplen) (len-i-seplen) in
2600     s' :: string_split sep s''
2601   )
2602
2603 let files_equal n1 n2 =
2604   let cmd = sprintf "cmp -s %s %s" (Filename.quote n1) (Filename.quote n2) in
2605   match Sys.command cmd with
2606   | 0 -> true
2607   | 1 -> false
2608   | i -> failwithf "%s: failed with error code %d" cmd i
2609
2610 let rec find_map f = function
2611   | [] -> raise Not_found
2612   | x :: xs ->
2613       match f x with
2614       | Some y -> y
2615       | None -> find_map f xs
2616
2617 let iteri f xs =
2618   let rec loop i = function
2619     | [] -> ()
2620     | x :: xs -> f i x; loop (i+1) xs
2621   in
2622   loop 0 xs
2623
2624 let mapi f xs =
2625   let rec loop i = function
2626     | [] -> []
2627     | x :: xs -> let r = f i x in r :: loop (i+1) xs
2628   in
2629   loop 0 xs
2630
2631 let name_of_argt = function
2632   | String n | OptString n | StringList n | Bool n | Int n
2633   | FileIn n | FileOut n -> n
2634
2635 let seq_of_test = function
2636   | TestRun s | TestOutput (s, _) | TestOutputList (s, _)
2637   | TestOutputListOfDevices (s, _)
2638   | TestOutputInt (s, _) | TestOutputTrue s | TestOutputFalse s
2639   | TestOutputLength (s, _) | TestOutputStruct (s, _)
2640   | TestLastFail s -> s
2641
2642 (* Check function names etc. for consistency. *)
2643 let check_functions () =
2644   let contains_uppercase str =
2645     let len = String.length str in
2646     let rec loop i =
2647       if i >= len then false
2648       else (
2649         let c = str.[i] in
2650         if c >= 'A' && c <= 'Z' then true
2651         else loop (i+1)
2652       )
2653     in
2654     loop 0
2655   in
2656
2657   (* Check function names. *)
2658   List.iter (
2659     fun (name, _, _, _, _, _, _) ->
2660       if String.length name >= 7 && String.sub name 0 7 = "guestfs" then
2661         failwithf "function name %s does not need 'guestfs' prefix" name;
2662       if name = "" then
2663         failwithf "function name is empty";
2664       if name.[0] < 'a' || name.[0] > 'z' then
2665         failwithf "function name %s must start with lowercase a-z" name;
2666       if String.contains name '-' then
2667         failwithf "function name %s should not contain '-', use '_' instead."
2668           name
2669   ) all_functions;
2670
2671   (* Check function parameter/return names. *)
2672   List.iter (
2673     fun (name, style, _, _, _, _, _) ->
2674       let check_arg_ret_name n =
2675         if contains_uppercase n then
2676           failwithf "%s param/ret %s should not contain uppercase chars"
2677             name n;
2678         if String.contains n '-' || String.contains n '_' then
2679           failwithf "%s param/ret %s should not contain '-' or '_'"
2680             name n;
2681         if n = "value" then
2682           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;
2683         if n = "int" || n = "char" || n = "short" || n = "long" then
2684           failwithf "%s has a param/ret which conflicts with a C type (eg. 'int', 'char' etc.)" name;
2685         if n = "i" then
2686           failwithf "%s has a param/ret called 'i', which will cause some conflicts in the generated code" name;
2687         if n = "argv" || n = "args" then
2688           failwithf "%s has a param/ret called 'argv' or 'args', which will cause some conflicts in the generated code" name
2689       in
2690
2691       (match fst style with
2692        | RErr -> ()
2693        | RInt n | RInt64 n | RBool n | RConstString n | RString n
2694        | RStringList n | RPVList n | RVGList n | RLVList n
2695        | RStat n | RStatVFS n
2696        | RHashtable n ->
2697            check_arg_ret_name n
2698        | RIntBool (n,m) ->
2699            check_arg_ret_name n;
2700            check_arg_ret_name m
2701       );
2702       List.iter (fun arg -> check_arg_ret_name (name_of_argt arg)) (snd style)
2703   ) all_functions;
2704
2705   (* Check short descriptions. *)
2706   List.iter (
2707     fun (name, _, _, _, _, shortdesc, _) ->
2708       if shortdesc.[0] <> Char.lowercase shortdesc.[0] then
2709         failwithf "short description of %s should begin with lowercase." name;
2710       let c = shortdesc.[String.length shortdesc-1] in
2711       if c = '\n' || c = '.' then
2712         failwithf "short description of %s should not end with . or \\n." name
2713   ) all_functions;
2714
2715   (* Check long dscriptions. *)
2716   List.iter (
2717     fun (name, _, _, _, _, _, longdesc) ->
2718       if longdesc.[String.length longdesc-1] = '\n' then
2719         failwithf "long description of %s should not end with \\n." name
2720   ) all_functions;
2721
2722   (* Check proc_nrs. *)
2723   List.iter (
2724     fun (name, _, proc_nr, _, _, _, _) ->
2725       if proc_nr <= 0 then
2726         failwithf "daemon function %s should have proc_nr > 0" name
2727   ) daemon_functions;
2728
2729   List.iter (
2730     fun (name, _, proc_nr, _, _, _, _) ->
2731       if proc_nr <> -1 then
2732         failwithf "non-daemon function %s should have proc_nr -1" name
2733   ) non_daemon_functions;
2734
2735   let proc_nrs =
2736     List.map (fun (name, _, proc_nr, _, _, _, _) -> name, proc_nr)
2737       daemon_functions in
2738   let proc_nrs =
2739     List.sort (fun (_,nr1) (_,nr2) -> compare nr1 nr2) proc_nrs in
2740   let rec loop = function
2741     | [] -> ()
2742     | [_] -> ()
2743     | (name1,nr1) :: ((name2,nr2) :: _ as rest) when nr1 < nr2 ->
2744         loop rest
2745     | (name1,nr1) :: (name2,nr2) :: _ ->
2746         failwithf "%s and %s have conflicting procedure numbers (%d, %d)"
2747           name1 name2 nr1 nr2
2748   in
2749   loop proc_nrs;
2750
2751   (* Check tests. *)
2752   List.iter (
2753     function
2754       (* Ignore functions that have no tests.  We generate a
2755        * warning when the user does 'make check' instead.
2756        *)
2757     | name, _, _, _, [], _, _ -> ()
2758     | name, _, _, _, tests, _, _ ->
2759         let funcs =
2760           List.map (
2761             fun (_, _, test) ->
2762               match seq_of_test test with
2763               | [] ->
2764                   failwithf "%s has a test containing an empty sequence" name
2765               | cmds -> List.map List.hd cmds
2766           ) tests in
2767         let funcs = List.flatten funcs in
2768
2769         let tested = List.mem name funcs in
2770
2771         if not tested then
2772           failwithf "function %s has tests but does not test itself" name
2773   ) all_functions
2774
2775 (* 'pr' prints to the current output file. *)
2776 let chan = ref stdout
2777 let pr fs = ksprintf (output_string !chan) fs
2778
2779 (* Generate a header block in a number of standard styles. *)
2780 type comment_style = CStyle | HashStyle | OCamlStyle | HaskellStyle
2781 type license = GPLv2 | LGPLv2
2782
2783 let generate_header comment license =
2784   let c = match comment with
2785     | CStyle ->     pr "/* "; " *"
2786     | HashStyle ->  pr "# ";  "#"
2787     | OCamlStyle -> pr "(* "; " *"
2788     | HaskellStyle -> pr "{- "; "  " in
2789   pr "libguestfs generated file\n";
2790   pr "%s WARNING: THIS FILE IS GENERATED BY 'src/generator.ml'.\n" c;
2791   pr "%s ANY CHANGES YOU MAKE TO THIS FILE WILL BE LOST.\n" c;
2792   pr "%s\n" c;
2793   pr "%s Copyright (C) 2009 Red Hat Inc.\n" c;
2794   pr "%s\n" c;
2795   (match license with
2796    | GPLv2 ->
2797        pr "%s This program is free software; you can redistribute it and/or modify\n" c;
2798        pr "%s it under the terms of the GNU General Public License as published by\n" c;
2799        pr "%s the Free Software Foundation; either version 2 of the License, or\n" c;
2800        pr "%s (at your option) any later version.\n" c;
2801        pr "%s\n" c;
2802        pr "%s This program is distributed in the hope that it will be useful,\n" c;
2803        pr "%s but WITHOUT ANY WARRANTY; without even the implied warranty of\n" c;
2804        pr "%s MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\n" c;
2805        pr "%s GNU General Public License for more details.\n" c;
2806        pr "%s\n" c;
2807        pr "%s You should have received a copy of the GNU General Public License along\n" c;
2808        pr "%s with this program; if not, write to the Free Software Foundation, Inc.,\n" c;
2809        pr "%s 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.\n" c;
2810
2811    | LGPLv2 ->
2812        pr "%s This library is free software; you can redistribute it and/or\n" c;
2813        pr "%s modify it under the terms of the GNU Lesser General Public\n" c;
2814        pr "%s License as published by the Free Software Foundation; either\n" c;
2815        pr "%s version 2 of the License, or (at your option) any later version.\n" c;
2816        pr "%s\n" c;
2817        pr "%s This library is distributed in the hope that it will be useful,\n" c;
2818        pr "%s but WITHOUT ANY WARRANTY; without even the implied warranty of\n" c;
2819        pr "%s MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU\n" c;
2820        pr "%s Lesser General Public License for more details.\n" c;
2821        pr "%s\n" c;
2822        pr "%s You should have received a copy of the GNU Lesser General Public\n" c;
2823        pr "%s License along with this library; if not, write to the Free Software\n" c;
2824        pr "%s Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA\n" c;
2825   );
2826   (match comment with
2827    | CStyle -> pr " */\n"
2828    | HashStyle -> ()
2829    | OCamlStyle -> pr " *)\n"
2830    | HaskellStyle -> pr "-}\n"
2831   );
2832   pr "\n"
2833
2834 (* Start of main code generation functions below this line. *)
2835
2836 (* Generate the pod documentation for the C API. *)
2837 let rec generate_actions_pod () =
2838   List.iter (
2839     fun (shortname, style, _, flags, _, _, longdesc) ->
2840       if not (List.mem NotInDocs flags) then (
2841         let name = "guestfs_" ^ shortname in
2842         pr "=head2 %s\n\n" name;
2843         pr " ";
2844         generate_prototype ~extern:false ~handle:"handle" name style;
2845         pr "\n\n";
2846         pr "%s\n\n" longdesc;
2847         (match fst style with
2848          | RErr ->
2849              pr "This function returns 0 on success or -1 on error.\n\n"
2850          | RInt _ ->
2851              pr "On error this function returns -1.\n\n"
2852          | RInt64 _ ->
2853              pr "On error this function returns -1.\n\n"
2854          | RBool _ ->
2855              pr "This function returns a C truth value on success or -1 on error.\n\n"
2856          | RConstString _ ->
2857              pr "This function returns a string, or NULL on error.
2858 The string is owned by the guest handle and must I<not> be freed.\n\n"
2859          | RString _ ->
2860              pr "This function returns a string, or NULL on error.
2861 I<The caller must free the returned string after use>.\n\n"
2862          | RStringList _ ->
2863              pr "This function returns a NULL-terminated array of strings
2864 (like L<environ(3)>), or NULL if there was an error.
2865 I<The caller must free the strings and the array after use>.\n\n"
2866          | RIntBool _ ->
2867              pr "This function returns a C<struct guestfs_int_bool *>,
2868 or NULL if there was an error.
2869 I<The caller must call C<guestfs_free_int_bool> after use>.\n\n"
2870          | RPVList _ ->
2871              pr "This function returns a C<struct guestfs_lvm_pv_list *>
2872 (see E<lt>guestfs-structs.hE<gt>),
2873 or NULL if there was an error.
2874 I<The caller must call C<guestfs_free_lvm_pv_list> after use>.\n\n"
2875          | RVGList _ ->
2876              pr "This function returns a C<struct guestfs_lvm_vg_list *>
2877 (see E<lt>guestfs-structs.hE<gt>),
2878 or NULL if there was an error.
2879 I<The caller must call C<guestfs_free_lvm_vg_list> after use>.\n\n"
2880          | RLVList _ ->
2881              pr "This function returns a C<struct guestfs_lvm_lv_list *>
2882 (see E<lt>guestfs-structs.hE<gt>),
2883 or NULL if there was an error.
2884 I<The caller must call C<guestfs_free_lvm_lv_list> after use>.\n\n"
2885          | RStat _ ->
2886              pr "This function returns a C<struct guestfs_stat *>
2887 (see L<stat(2)> and E<lt>guestfs-structs.hE<gt>),
2888 or NULL if there was an error.
2889 I<The caller must call C<free> after use>.\n\n"
2890          | RStatVFS _ ->
2891              pr "This function returns a C<struct guestfs_statvfs *>
2892 (see L<statvfs(2)> and E<lt>guestfs-structs.hE<gt>),
2893 or NULL if there was an error.
2894 I<The caller must call C<free> after use>.\n\n"
2895          | RHashtable _ ->
2896              pr "This function returns a NULL-terminated array of
2897 strings, or NULL if there was an error.
2898 The array of strings will always have length C<2n+1>, where
2899 C<n> keys and values alternate, followed by the trailing NULL entry.
2900 I<The caller must free the strings and the array after use>.\n\n"
2901         );
2902         if List.mem ProtocolLimitWarning flags then
2903           pr "%s\n\n" protocol_limit_warning;
2904         if List.mem DangerWillRobinson flags then
2905           pr "%s\n\n" danger_will_robinson
2906       )
2907   ) all_functions_sorted
2908
2909 and generate_structs_pod () =
2910   (* LVM structs documentation. *)
2911   List.iter (
2912     fun (typ, cols) ->
2913       pr "=head2 guestfs_lvm_%s\n" typ;
2914       pr "\n";
2915       pr " struct guestfs_lvm_%s {\n" typ;
2916       List.iter (
2917         function
2918         | name, `String -> pr "  char *%s;\n" name
2919         | name, `UUID ->
2920             pr "  /* The next field is NOT nul-terminated, be careful when printing it: */\n";
2921             pr "  char %s[32];\n" name
2922         | name, `Bytes -> pr "  uint64_t %s;\n" name
2923         | name, `Int -> pr "  int64_t %s;\n" name
2924         | name, `OptPercent ->
2925             pr "  /* The next field is [0..100] or -1 meaning 'not present': */\n";
2926             pr "  float %s;\n" name
2927       ) cols;
2928       pr " \n";
2929       pr " struct guestfs_lvm_%s_list {\n" typ;
2930       pr "   uint32_t len; /* Number of elements in list. */\n";
2931       pr "   struct guestfs_lvm_%s *val; /* Elements. */\n" typ;
2932       pr " };\n";
2933       pr " \n";
2934       pr " void guestfs_free_lvm_%s_list (struct guestfs_free_lvm_%s_list *);\n"
2935         typ typ;
2936       pr "\n"
2937   ) ["pv", pv_cols; "vg", vg_cols; "lv", lv_cols]
2938
2939 (* Generate the protocol (XDR) file, 'guestfs_protocol.x' and
2940  * indirectly 'guestfs_protocol.h' and 'guestfs_protocol.c'.
2941  *
2942  * We have to use an underscore instead of a dash because otherwise
2943  * rpcgen generates incorrect code.
2944  *
2945  * This header is NOT exported to clients, but see also generate_structs_h.
2946  *)
2947 and generate_xdr () =
2948   generate_header CStyle LGPLv2;
2949
2950   (* This has to be defined to get around a limitation in Sun's rpcgen. *)
2951   pr "typedef string str<>;\n";
2952   pr "\n";
2953
2954   (* LVM internal structures. *)
2955   List.iter (
2956     function
2957     | typ, cols ->
2958         pr "struct guestfs_lvm_int_%s {\n" typ;
2959         List.iter (function
2960                    | name, `String -> pr "  string %s<>;\n" name
2961                    | name, `UUID -> pr "  opaque %s[32];\n" name
2962                    | name, `Bytes -> pr "  hyper %s;\n" name
2963                    | name, `Int -> pr "  hyper %s;\n" name
2964                    | name, `OptPercent -> pr "  float %s;\n" name
2965                   ) cols;
2966         pr "};\n";
2967         pr "\n";
2968         pr "typedef struct guestfs_lvm_int_%s guestfs_lvm_int_%s_list<>;\n" typ typ;
2969         pr "\n";
2970   ) ["pv", pv_cols; "vg", vg_cols; "lv", lv_cols];
2971
2972   (* Stat internal structures. *)
2973   List.iter (
2974     function
2975     | typ, cols ->
2976         pr "struct guestfs_int_%s {\n" typ;
2977         List.iter (function
2978                    | name, `Int -> pr "  hyper %s;\n" name
2979                   ) cols;
2980         pr "};\n";
2981         pr "\n";
2982   ) ["stat", stat_cols; "statvfs", statvfs_cols];
2983
2984   List.iter (
2985     fun (shortname, style, _, _, _, _, _) ->
2986       let name = "guestfs_" ^ shortname in
2987
2988       (match snd style with
2989        | [] -> ()
2990        | args ->
2991            pr "struct %s_args {\n" name;
2992            List.iter (
2993              function
2994              | String n -> pr "  string %s<>;\n" n
2995              | OptString n -> pr "  str *%s;\n" n
2996              | StringList n -> pr "  str %s<>;\n" n
2997              | Bool n -> pr "  bool %s;\n" n
2998              | Int n -> pr "  int %s;\n" n
2999              | FileIn _ | FileOut _ -> ()
3000            ) args;
3001            pr "};\n\n"
3002       );
3003       (match fst style with
3004        | RErr -> ()
3005        | RInt n ->
3006            pr "struct %s_ret {\n" name;
3007            pr "  int %s;\n" n;
3008            pr "};\n\n"
3009        | RInt64 n ->
3010            pr "struct %s_ret {\n" name;
3011            pr "  hyper %s;\n" n;
3012            pr "};\n\n"
3013        | RBool n ->
3014            pr "struct %s_ret {\n" name;
3015            pr "  bool %s;\n" n;
3016            pr "};\n\n"
3017        | RConstString _ ->
3018            failwithf "RConstString cannot be returned from a daemon function"
3019        | RString n ->
3020            pr "struct %s_ret {\n" name;
3021            pr "  string %s<>;\n" n;
3022            pr "};\n\n"
3023        | RStringList n ->
3024            pr "struct %s_ret {\n" name;
3025            pr "  str %s<>;\n" n;
3026            pr "};\n\n"
3027        | RIntBool (n,m) ->
3028            pr "struct %s_ret {\n" name;
3029            pr "  int %s;\n" n;
3030            pr "  bool %s;\n" m;
3031            pr "};\n\n"
3032        | RPVList n ->
3033            pr "struct %s_ret {\n" name;
3034            pr "  guestfs_lvm_int_pv_list %s;\n" n;
3035            pr "};\n\n"
3036        | RVGList n ->
3037            pr "struct %s_ret {\n" name;
3038            pr "  guestfs_lvm_int_vg_list %s;\n" n;
3039            pr "};\n\n"
3040        | RLVList n ->
3041            pr "struct %s_ret {\n" name;
3042            pr "  guestfs_lvm_int_lv_list %s;\n" n;
3043            pr "};\n\n"
3044        | RStat n ->
3045            pr "struct %s_ret {\n" name;
3046            pr "  guestfs_int_stat %s;\n" n;
3047            pr "};\n\n"
3048        | RStatVFS n ->
3049            pr "struct %s_ret {\n" name;
3050            pr "  guestfs_int_statvfs %s;\n" n;
3051            pr "};\n\n"
3052        | RHashtable n ->
3053            pr "struct %s_ret {\n" name;
3054            pr "  str %s<>;\n" n;
3055            pr "};\n\n"
3056       );
3057   ) daemon_functions;
3058
3059   (* Table of procedure numbers. *)
3060   pr "enum guestfs_procedure {\n";
3061   List.iter (
3062     fun (shortname, _, proc_nr, _, _, _, _) ->
3063       pr "  GUESTFS_PROC_%s = %d,\n" (String.uppercase shortname) proc_nr
3064   ) daemon_functions;
3065   pr "  GUESTFS_PROC_NR_PROCS\n";
3066   pr "};\n";
3067   pr "\n";
3068
3069   (* Having to choose a maximum message size is annoying for several
3070    * reasons (it limits what we can do in the API), but it (a) makes
3071    * the protocol a lot simpler, and (b) provides a bound on the size
3072    * of the daemon which operates in limited memory space.  For large
3073    * file transfers you should use FTP.
3074    *)
3075   pr "const GUESTFS_MESSAGE_MAX = %d;\n" (4 * 1024 * 1024);
3076   pr "\n";
3077
3078   (* Message header, etc. *)
3079   pr "\
3080 /* The communication protocol is now documented in the guestfs(3)
3081  * manpage.
3082  */
3083
3084 const GUESTFS_PROGRAM = 0x2000F5F5;
3085 const GUESTFS_PROTOCOL_VERSION = 1;
3086
3087 /* These constants must be larger than any possible message length. */
3088 const GUESTFS_LAUNCH_FLAG = 0xf5f55ff5;
3089 const GUESTFS_CANCEL_FLAG = 0xffffeeee;
3090
3091 enum guestfs_message_direction {
3092   GUESTFS_DIRECTION_CALL = 0,        /* client -> daemon */
3093   GUESTFS_DIRECTION_REPLY = 1        /* daemon -> client */
3094 };
3095
3096 enum guestfs_message_status {
3097   GUESTFS_STATUS_OK = 0,
3098   GUESTFS_STATUS_ERROR = 1
3099 };
3100
3101 const GUESTFS_ERROR_LEN = 256;
3102
3103 struct guestfs_message_error {
3104   string error_message<GUESTFS_ERROR_LEN>;
3105 };
3106
3107 struct guestfs_message_header {
3108   unsigned prog;                     /* GUESTFS_PROGRAM */
3109   unsigned vers;                     /* GUESTFS_PROTOCOL_VERSION */
3110   guestfs_procedure proc;            /* GUESTFS_PROC_x */
3111   guestfs_message_direction direction;
3112   unsigned serial;                   /* message serial number */
3113   guestfs_message_status status;
3114 };
3115
3116 const GUESTFS_MAX_CHUNK_SIZE = 8192;
3117
3118 struct guestfs_chunk {
3119   int cancel;                        /* if non-zero, transfer is cancelled */
3120   /* data size is 0 bytes if the transfer has finished successfully */
3121   opaque data<GUESTFS_MAX_CHUNK_SIZE>;
3122 };
3123 "
3124
3125 (* Generate the guestfs-structs.h file. *)
3126 and generate_structs_h () =
3127   generate_header CStyle LGPLv2;
3128
3129   (* This is a public exported header file containing various
3130    * structures.  The structures are carefully written to have
3131    * exactly the same in-memory format as the XDR structures that
3132    * we use on the wire to the daemon.  The reason for creating
3133    * copies of these structures here is just so we don't have to
3134    * export the whole of guestfs_protocol.h (which includes much
3135    * unrelated and XDR-dependent stuff that we don't want to be
3136    * public, or required by clients).
3137    *
3138    * To reiterate, we will pass these structures to and from the
3139    * client with a simple assignment or memcpy, so the format
3140    * must be identical to what rpcgen / the RFC defines.
3141    *)
3142
3143   (* guestfs_int_bool structure. *)
3144   pr "struct guestfs_int_bool {\n";
3145   pr "  int32_t i;\n";
3146   pr "  int32_t b;\n";
3147   pr "};\n";
3148   pr "\n";
3149
3150   (* LVM public structures. *)
3151   List.iter (
3152     function
3153     | typ, cols ->
3154         pr "struct guestfs_lvm_%s {\n" typ;
3155         List.iter (
3156           function
3157           | name, `String -> pr "  char *%s;\n" name
3158           | name, `UUID -> pr "  char %s[32]; /* this is NOT nul-terminated, be careful when printing */\n" name
3159           | name, `Bytes -> pr "  uint64_t %s;\n" name
3160           | name, `Int -> pr "  int64_t %s;\n" name
3161           | name, `OptPercent -> pr "  float %s; /* [0..100] or -1 */\n" name
3162         ) cols;
3163         pr "};\n";
3164         pr "\n";
3165         pr "struct guestfs_lvm_%s_list {\n" typ;
3166         pr "  uint32_t len;\n";
3167         pr "  struct guestfs_lvm_%s *val;\n" typ;
3168         pr "};\n";
3169         pr "\n"
3170   ) ["pv", pv_cols; "vg", vg_cols; "lv", lv_cols];
3171
3172   (* Stat structures. *)
3173   List.iter (
3174     function
3175     | typ, cols ->
3176         pr "struct guestfs_%s {\n" typ;
3177         List.iter (
3178           function
3179           | name, `Int -> pr "  int64_t %s;\n" name
3180         ) cols;
3181         pr "};\n";
3182         pr "\n"
3183   ) ["stat", stat_cols; "statvfs", statvfs_cols]
3184
3185 (* Generate the guestfs-actions.h file. *)
3186 and generate_actions_h () =
3187   generate_header CStyle LGPLv2;
3188   List.iter (
3189     fun (shortname, style, _, _, _, _, _) ->
3190       let name = "guestfs_" ^ shortname in
3191       generate_prototype ~single_line:true ~newline:true ~handle:"handle"
3192         name style
3193   ) all_functions
3194
3195 (* Generate the client-side dispatch stubs. *)
3196 and generate_client_actions () =
3197   generate_header CStyle LGPLv2;
3198
3199   pr "\
3200 #include <stdio.h>
3201 #include <stdlib.h>
3202
3203 #include \"guestfs.h\"
3204 #include \"guestfs_protocol.h\"
3205
3206 #define error guestfs_error
3207 #define perrorf guestfs_perrorf
3208 #define safe_malloc guestfs_safe_malloc
3209 #define safe_realloc guestfs_safe_realloc
3210 #define safe_strdup guestfs_safe_strdup
3211 #define safe_memdup guestfs_safe_memdup
3212
3213 /* Check the return message from a call for validity. */
3214 static int
3215 check_reply_header (guestfs_h *g,
3216                     const struct guestfs_message_header *hdr,
3217                     int proc_nr, int serial)
3218 {
3219   if (hdr->prog != GUESTFS_PROGRAM) {
3220     error (g, \"wrong program (%%d/%%d)\", hdr->prog, GUESTFS_PROGRAM);
3221     return -1;
3222   }
3223   if (hdr->vers != GUESTFS_PROTOCOL_VERSION) {
3224     error (g, \"wrong protocol version (%%d/%%d)\",
3225            hdr->vers, GUESTFS_PROTOCOL_VERSION);
3226     return -1;
3227   }
3228   if (hdr->direction != GUESTFS_DIRECTION_REPLY) {
3229     error (g, \"unexpected message direction (%%d/%%d)\",
3230            hdr->direction, GUESTFS_DIRECTION_REPLY);
3231     return -1;
3232   }
3233   if (hdr->proc != proc_nr) {
3234     error (g, \"unexpected procedure number (%%d/%%d)\", hdr->proc, proc_nr);
3235     return -1;
3236   }
3237   if (hdr->serial != serial) {
3238     error (g, \"unexpected serial (%%d/%%d)\", hdr->serial, serial);
3239     return -1;
3240   }
3241
3242   return 0;
3243 }
3244
3245 /* Check we are in the right state to run a high-level action. */
3246 static int
3247 check_state (guestfs_h *g, const char *caller)
3248 {
3249   if (!guestfs_is_ready (g)) {
3250     if (guestfs_is_config (g))
3251       error (g, \"%%s: call launch() before using this function\",
3252         caller);
3253     else if (guestfs_is_launching (g))
3254       error (g, \"%%s: call wait_ready() before using this function\",
3255         caller);
3256     else
3257       error (g, \"%%s called from the wrong state, %%d != READY\",
3258         caller, guestfs_get_state (g));
3259     return -1;
3260   }
3261   return 0;
3262 }
3263
3264 ";
3265
3266   (* Client-side stubs for each function. *)
3267   List.iter (
3268     fun (shortname, style, _, _, _, _, _) ->
3269       let name = "guestfs_" ^ shortname in
3270
3271       (* Generate the context struct which stores the high-level
3272        * state between callback functions.
3273        *)
3274       pr "struct %s_ctx {\n" shortname;
3275       pr "  /* This flag is set by the callbacks, so we know we've done\n";
3276       pr "   * the callbacks as expected, and in the right sequence.\n";
3277       pr "   * 0 = not called, 1 = reply_cb called.\n";
3278       pr "   */\n";
3279       pr "  int cb_sequence;\n";
3280       pr "  struct guestfs_message_header hdr;\n";
3281       pr "  struct guestfs_message_error err;\n";
3282       (match fst style with
3283        | RErr -> ()
3284        | RConstString _ ->
3285            failwithf "RConstString cannot be returned from a daemon function"
3286        | RInt _ | RInt64 _
3287        | RBool _ | RString _ | RStringList _
3288        | RIntBool _
3289        | RPVList _ | RVGList _ | RLVList _
3290        | RStat _ | RStatVFS _
3291        | RHashtable _ ->
3292            pr "  struct %s_ret ret;\n" name
3293       );
3294       pr "};\n";
3295       pr "\n";
3296
3297       (* Generate the reply callback function. *)
3298       pr "static void %s_reply_cb (guestfs_h *g, void *data, XDR *xdr)\n" shortname;
3299       pr "{\n";
3300       pr "  guestfs_main_loop *ml = guestfs_get_main_loop (g);\n";
3301       pr "  struct %s_ctx *ctx = (struct %s_ctx *) data;\n" shortname shortname;
3302       pr "\n";
3303       pr "  /* This should definitely not happen. */\n";
3304       pr "  if (ctx->cb_sequence != 0) {\n";
3305       pr "    ctx->cb_sequence = 9999;\n";
3306       pr "    error (g, \"%%s: internal error: reply callback called twice\", \"%s\");\n" name;
3307       pr "    return;\n";
3308       pr "  }\n";
3309       pr "\n";
3310       pr "  ml->main_loop_quit (ml, g);\n";
3311       pr "\n";
3312       pr "  if (!xdr_guestfs_message_header (xdr, &ctx->hdr)) {\n";
3313       pr "    error (g, \"%%s: failed to parse reply header\", \"%s\");\n" name;
3314       pr "    return;\n";
3315       pr "  }\n";
3316       pr "  if (ctx->hdr.status == GUESTFS_STATUS_ERROR) {\n";
3317       pr "    if (!xdr_guestfs_message_error (xdr, &ctx->err)) {\n";
3318       pr "      error (g, \"%%s: failed to parse reply error\", \"%s\");\n"
3319         name;
3320       pr "      return;\n";
3321       pr "    }\n";
3322       pr "    goto done;\n";
3323       pr "  }\n";
3324
3325       (match fst style with
3326        | RErr -> ()
3327        | RConstString _ ->
3328            failwithf "RConstString cannot be returned from a daemon function"
3329        | RInt _ | RInt64 _
3330        | RBool _ | RString _ | RStringList _
3331        | RIntBool _
3332        | RPVList _ | RVGList _ | RLVList _
3333        | RStat _ | RStatVFS _
3334        | RHashtable _ ->
3335             pr "  if (!xdr_%s_ret (xdr, &ctx->ret)) {\n" name;
3336             pr "    error (g, \"%%s: failed to parse reply\", \"%s\");\n" name;
3337             pr "    return;\n";
3338             pr "  }\n";
3339       );
3340
3341       pr " done:\n";
3342       pr "  ctx->cb_sequence = 1;\n";
3343       pr "}\n\n";
3344
3345       (* Generate the action stub. *)
3346       generate_prototype ~extern:false ~semicolon:false ~newline:true
3347         ~handle:"g" name style;
3348
3349       let error_code =
3350         match fst style with
3351         | RErr | RInt _ | RInt64 _ | RBool _ -> "-1"
3352         | RConstString _ ->
3353             failwithf "RConstString cannot be returned from a daemon function"
3354         | RString _ | RStringList _ | RIntBool _
3355         | RPVList _ | RVGList _ | RLVList _
3356         | RStat _ | RStatVFS _
3357         | RHashtable _ ->
3358             "NULL" in
3359
3360       pr "{\n";
3361
3362       (match snd style with
3363        | [] -> ()
3364        | _ -> pr "  struct %s_args args;\n" name
3365       );
3366
3367       pr "  struct %s_ctx ctx;\n" shortname;
3368       pr "  guestfs_main_loop *ml = guestfs_get_main_loop (g);\n";
3369       pr "  int serial;\n";
3370       pr "\n";
3371       pr "  if (check_state (g, \"%s\") == -1) return %s;\n" name error_code;
3372       pr "  guestfs_set_busy (g);\n";
3373       pr "\n";
3374       pr "  memset (&ctx, 0, sizeof ctx);\n";
3375       pr "\n";
3376
3377       (* Send the main header and arguments. *)
3378       (match snd style with
3379        | [] ->
3380            pr "  serial = guestfs__send_sync (g, GUESTFS_PROC_%s, NULL, NULL);\n"
3381              (String.uppercase shortname)
3382        | args ->
3383            List.iter (
3384              function
3385              | String n ->
3386                  pr "  args.%s = (char *) %s;\n" n n
3387              | OptString n ->
3388                  pr "  args.%s = %s ? (char **) &%s : NULL;\n" n n n
3389              | StringList n ->
3390                  pr "  args.%s.%s_val = (char **) %s;\n" n n n;
3391                  pr "  for (args.%s.%s_len = 0; %s[args.%s.%s_len]; args.%s.%s_len++) ;\n" n n n n n n n;
3392              | Bool n ->
3393                  pr "  args.%s = %s;\n" n n
3394              | Int n ->
3395                  pr "  args.%s = %s;\n" n n
3396              | FileIn _ | FileOut _ -> ()
3397            ) args;
3398            pr "  serial = guestfs__send_sync (g, GUESTFS_PROC_%s,\n"
3399              (String.uppercase shortname);
3400            pr "        (xdrproc_t) xdr_%s_args, (char *) &args);\n"
3401              name;
3402       );
3403       pr "  if (serial == -1) {\n";
3404       pr "    guestfs_end_busy (g);\n";
3405       pr "    return %s;\n" error_code;
3406       pr "  }\n";
3407       pr "\n";
3408
3409       (* Send any additional files (FileIn) requested. *)
3410       let need_read_reply_label = ref false in
3411       List.iter (
3412         function
3413         | FileIn n ->
3414             pr "  {\n";
3415             pr "    int r;\n";
3416             pr "\n";
3417             pr "    r = guestfs__send_file_sync (g, %s);\n" n;
3418             pr "    if (r == -1) {\n";
3419             pr "      guestfs_end_busy (g);\n";
3420             pr "      return %s;\n" error_code;
3421             pr "    }\n";
3422             pr "    if (r == -2) /* daemon cancelled */\n";
3423             pr "      goto read_reply;\n";
3424             need_read_reply_label := true;
3425             pr "  }\n";
3426             pr "\n";
3427         | _ -> ()
3428       ) (snd style);
3429
3430       (* Wait for the reply from the remote end. *)
3431       if !need_read_reply_label then pr " read_reply:\n";
3432       pr "  guestfs__switch_to_receiving (g);\n";
3433       pr "  ctx.cb_sequence = 0;\n";
3434       pr "  guestfs_set_reply_callback (g, %s_reply_cb, &ctx);\n" shortname;
3435       pr "  (void) ml->main_loop_run (ml, g);\n";
3436       pr "  guestfs_set_reply_callback (g, NULL, NULL);\n";
3437       pr "  if (ctx.cb_sequence != 1) {\n";
3438       pr "    error (g, \"%%s reply failed, see earlier error messages\", \"%s\");\n" name;
3439       pr "    guestfs_end_busy (g);\n";
3440       pr "    return %s;\n" error_code;
3441       pr "  }\n";
3442       pr "\n";
3443
3444       pr "  if (check_reply_header (g, &ctx.hdr, GUESTFS_PROC_%s, serial) == -1) {\n"
3445         (String.uppercase shortname);
3446       pr "    guestfs_end_busy (g);\n";
3447       pr "    return %s;\n" error_code;
3448       pr "  }\n";
3449       pr "\n";
3450
3451       pr "  if (ctx.hdr.status == GUESTFS_STATUS_ERROR) {\n";
3452       pr "    error (g, \"%%s\", ctx.err.error_message);\n";
3453       pr "    free (ctx.err.error_message);\n";
3454       pr "    guestfs_end_busy (g);\n";
3455       pr "    return %s;\n" error_code;
3456       pr "  }\n";
3457       pr "\n";
3458
3459       (* Expecting to receive further files (FileOut)? *)
3460       List.iter (
3461         function
3462         | FileOut n ->
3463             pr "  if (guestfs__receive_file_sync (g, %s) == -1) {\n" n;
3464             pr "    guestfs_end_busy (g);\n";
3465             pr "    return %s;\n" error_code;
3466             pr "  }\n";
3467             pr "\n";
3468         | _ -> ()
3469       ) (snd style);
3470
3471       pr "  guestfs_end_busy (g);\n";
3472
3473       (match fst style with
3474        | RErr -> pr "  return 0;\n"
3475        | RInt n | RInt64 n | RBool n ->
3476            pr "  return ctx.ret.%s;\n" n
3477        | RConstString _ ->
3478            failwithf "RConstString cannot be returned from a daemon function"
3479        | RString n ->
3480            pr "  return ctx.ret.%s; /* caller will free */\n" n
3481        | RStringList n | RHashtable n ->
3482            pr "  /* caller will free this, but we need to add a NULL entry */\n";
3483            pr "  ctx.ret.%s.%s_val =\n" n n;
3484            pr "    safe_realloc (g, ctx.ret.%s.%s_val,\n" n n;
3485            pr "                  sizeof (char *) * (ctx.ret.%s.%s_len + 1));\n"
3486              n n;
3487            pr "  ctx.ret.%s.%s_val[ctx.ret.%s.%s_len] = NULL;\n" n n n n;
3488            pr "  return ctx.ret.%s.%s_val;\n" n n
3489        | RIntBool _ ->
3490            pr "  /* caller with free this */\n";
3491            pr "  return safe_memdup (g, &ctx.ret, sizeof (ctx.ret));\n"
3492        | RPVList n | RVGList n | RLVList n
3493        | RStat n | RStatVFS n ->
3494            pr "  /* caller will free this */\n";
3495            pr "  return safe_memdup (g, &ctx.ret.%s, sizeof (ctx.ret.%s));\n" n n
3496       );
3497
3498       pr "}\n\n"
3499   ) daemon_functions
3500
3501 (* Generate daemon/actions.h. *)
3502 and generate_daemon_actions_h () =
3503   generate_header CStyle GPLv2;
3504
3505   pr "#include \"../src/guestfs_protocol.h\"\n";
3506   pr "\n";
3507
3508   List.iter (
3509     fun (name, style, _, _, _, _, _) ->
3510         generate_prototype
3511           ~single_line:true ~newline:true ~in_daemon:true ~prefix:"do_"
3512           name style;
3513   ) daemon_functions
3514
3515 (* Generate the server-side stubs. *)
3516 and generate_daemon_actions () =
3517   generate_header CStyle GPLv2;
3518
3519   pr "#include <config.h>\n";
3520   pr "\n";
3521   pr "#include <stdio.h>\n";
3522   pr "#include <stdlib.h>\n";
3523   pr "#include <string.h>\n";
3524   pr "#include <inttypes.h>\n";
3525   pr "#include <ctype.h>\n";
3526   pr "#include <rpc/types.h>\n";
3527   pr "#include <rpc/xdr.h>\n";
3528   pr "\n";
3529   pr "#include \"daemon.h\"\n";
3530   pr "#include \"../src/guestfs_protocol.h\"\n";
3531   pr "#include \"actions.h\"\n";
3532   pr "\n";
3533
3534   List.iter (
3535     fun (name, style, _, _, _, _, _) ->
3536       (* Generate server-side stubs. *)
3537       pr "static void %s_stub (XDR *xdr_in)\n" name;
3538       pr "{\n";
3539       let error_code =
3540         match fst style with
3541         | RErr | RInt _ -> pr "  int r;\n"; "-1"
3542         | RInt64 _ -> pr "  int64_t r;\n"; "-1"
3543         | RBool _ -> pr "  int r;\n"; "-1"
3544         | RConstString _ ->
3545             failwithf "RConstString cannot be returned from a daemon function"
3546         | RString _ -> pr "  char *r;\n"; "NULL"
3547         | RStringList _ | RHashtable _ -> pr "  char **r;\n"; "NULL"
3548         | RIntBool _ -> pr "  guestfs_%s_ret *r;\n" name; "NULL"
3549         | RPVList _ -> pr "  guestfs_lvm_int_pv_list *r;\n"; "NULL"
3550         | RVGList _ -> pr "  guestfs_lvm_int_vg_list *r;\n"; "NULL"
3551         | RLVList _ -> pr "  guestfs_lvm_int_lv_list *r;\n"; "NULL"
3552         | RStat _ -> pr "  guestfs_int_stat *r;\n"; "NULL"
3553         | RStatVFS _ -> pr "  guestfs_int_statvfs *r;\n"; "NULL" in
3554
3555       (match snd style with
3556        | [] -> ()
3557        | args ->
3558            pr "  struct guestfs_%s_args args;\n" name;
3559            List.iter (
3560              function
3561                (* Note we allow the string to be writable, in order to
3562                 * allow device name translation.  This is safe because
3563                 * we can modify the string (passed from RPC).
3564                 *)
3565              | String n
3566              | OptString n -> pr "  char *%s;\n" n
3567              | StringList n -> pr "  char **%s;\n" n
3568              | Bool n -> pr "  int %s;\n" n
3569              | Int n -> pr "  int %s;\n" n
3570              | FileIn _ | FileOut _ -> ()
3571            ) args
3572       );
3573       pr "\n";
3574
3575       (match snd style with
3576        | [] -> ()
3577        | args ->
3578            pr "  memset (&args, 0, sizeof args);\n";
3579            pr "\n";
3580            pr "  if (!xdr_guestfs_%s_args (xdr_in, &args)) {\n" name;
3581            pr "    reply_with_error (\"%%s: daemon failed to decode procedure arguments\", \"%s\");\n" name;
3582            pr "    return;\n";
3583            pr "  }\n";
3584            List.iter (
3585              function
3586              | String n -> pr "  %s = args.%s;\n" n n
3587              | OptString n -> pr "  %s = args.%s ? *args.%s : NULL;\n" n n n
3588              | StringList n ->
3589                  pr "  %s = realloc (args.%s.%s_val,\n" n n n;
3590                  pr "                sizeof (char *) * (args.%s.%s_len+1));\n" n n;
3591                  pr "  if (%s == NULL) {\n" n;
3592                  pr "    reply_with_perror (\"realloc\");\n";
3593                  pr "    goto done;\n";
3594                  pr "  }\n";
3595                  pr "  %s[args.%s.%s_len] = NULL;\n" n n n;
3596                  pr "  args.%s.%s_val = %s;\n" n n n;
3597              | Bool n -> pr "  %s = args.%s;\n" n n
3598              | Int n -> pr "  %s = args.%s;\n" n n
3599              | FileIn _ | FileOut _ -> ()
3600            ) args;
3601            pr "\n"
3602       );
3603
3604       (* Don't want to call the impl with any FileIn or FileOut
3605        * parameters, since these go "outside" the RPC protocol.
3606        *)
3607       let argsnofile =
3608         List.filter (function FileIn _ | FileOut _ -> false | _ -> true)
3609           (snd style) in
3610       pr "  r = do_%s " name;
3611       generate_call_args argsnofile;
3612       pr ";\n";
3613
3614       pr "  if (r == %s)\n" error_code;
3615       pr "    /* do_%s has already called reply_with_error */\n" name;
3616       pr "    goto done;\n";
3617       pr "\n";
3618
3619       (* If there are any FileOut parameters, then the impl must
3620        * send its own reply.
3621        *)
3622       let no_reply =
3623         List.exists (function FileOut _ -> true | _ -> false) (snd style) in
3624       if no_reply then
3625         pr "  /* do_%s has already sent a reply */\n" name
3626       else (
3627         match fst style with
3628         | RErr -> pr "  reply (NULL, NULL);\n"
3629         | RInt n | RInt64 n | RBool n ->
3630             pr "  struct guestfs_%s_ret ret;\n" name;
3631             pr "  ret.%s = r;\n" n;
3632             pr "  reply ((xdrproc_t) &xdr_guestfs_%s_ret, (char *) &ret);\n"
3633               name
3634         | RConstString _ ->
3635             failwithf "RConstString cannot be returned from a daemon function"
3636         | RString n ->
3637             pr "  struct guestfs_%s_ret ret;\n" name;
3638             pr "  ret.%s = r;\n" n;
3639             pr "  reply ((xdrproc_t) &xdr_guestfs_%s_ret, (char *) &ret);\n"
3640               name;
3641             pr "  free (r);\n"
3642         | RStringList n | RHashtable n ->
3643             pr "  struct guestfs_%s_ret ret;\n" name;
3644             pr "  ret.%s.%s_len = count_strings (r);\n" n n;
3645             pr "  ret.%s.%s_val = r;\n" n n;
3646             pr "  reply ((xdrproc_t) &xdr_guestfs_%s_ret, (char *) &ret);\n"
3647               name;
3648             pr "  free_strings (r);\n"
3649         | RIntBool _ ->
3650             pr "  reply ((xdrproc_t) xdr_guestfs_%s_ret, (char *) r);\n"
3651               name;
3652             pr "  xdr_free ((xdrproc_t) xdr_guestfs_%s_ret, (char *) r);\n" name
3653         | RPVList n | RVGList n | RLVList n
3654         | RStat n | RStatVFS n ->
3655             pr "  struct guestfs_%s_ret ret;\n" name;
3656             pr "  ret.%s = *r;\n" n;
3657             pr "  reply ((xdrproc_t) xdr_guestfs_%s_ret, (char *) &ret);\n"
3658               name;
3659             pr "  xdr_free ((xdrproc_t) xdr_guestfs_%s_ret, (char *) &ret);\n"
3660               name
3661       );
3662