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