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