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