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