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