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