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