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