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