guestfs-actions.pod

   1 =head2 guestfs_add_cdrom
   2
   3  int guestfs_add_cdrom (guestfs_h *handle,
   4                 const char *filename);
   5
   6 This function adds a virtual CD-ROM disk image to the guest.
   7
   8 This is equivalent to the qemu parameter C<-cdrom filename>.
   9
  10 This function returns 0 on success or -1 on error.
  11
  12 =head2 guestfs_add_drive
  13
  14  int guestfs_add_drive (guestfs_h *handle,
  15                 const char *filename);
  16
  17 This function adds a virtual machine disk image C<filename> to the
  18 guest.  The first time you call this function, the disk appears as IDE
  19 disk 0 (C</dev/sda>) in the guest, the second time as C</dev/sdb>, and
  20 so on.
  21
  22 You don't necessarily need to be root when using libguestfs.  However
  23 you obviously do need sufficient permissions to access the filename
  24 for whatever operations you want to perform (ie. read access if you
  25 just want to read the image or write access if you want to modify the
  26 image).
  27
  28 This is equivalent to the qemu parameter C<-drive file=filename>.
  29
  30 This function returns 0 on success or -1 on error.
  31
  32 =head2 guestfs_aug_close
  33
  34  int guestfs_aug_close (guestfs_h *handle);
  35
  36 Close the current Augeas handle and free up any resources
  37 used by it.  After calling this, you have to call
  38 C<guestfs_aug_init> again before you can use any other
  39 Augeas functions.
  40
  41 This function returns 0 on success or -1 on error.
  42
  43 =head2 guestfs_aug_defnode
  44
  45  struct guestfs_int_bool *guestfs_aug_defnode (guestfs_h *handle,
  46                 const char *name,
  47                 const char *expr,
  48                 const char *val);
  49
  50 Defines a variable C<name> whose value is the result of
  51 evaluating C<expr>.
  52
  53 If C<expr> evaluates to an empty nodeset, a node is created,
  54 equivalent to calling C<guestfs_aug_set> C<expr>, C<value>.
  55 C<name> will be the nodeset containing that single node.
  56
  57 On success this returns a pair containing the
  58 number of nodes in the nodeset, and a boolean flag
  59 if a node was created.
  60
  61 This function returns a C<struct guestfs_int_bool *>,
  62 or NULL if there was an error.
  63 I<The caller must call C<guestfs_free_int_bool> after use>.
  64
  65 =head2 guestfs_aug_defvar
  66
  67  int guestfs_aug_defvar (guestfs_h *handle,
  68                 const char *name,
  69                 const char *expr);
  70
  71 Defines an Augeas variable C<name> whose value is the result
  72 of evaluating C<expr>.  If C<expr> is NULL, then C<name> is
  73 undefined.
  74
  75 On success this returns the number of nodes in C<expr>, or
  76 C<0> if C<expr> evaluates to something which is not a nodeset.
  77
  78 On error this function returns -1.
  79
  80 =head2 guestfs_aug_get
  81
  82  char *guestfs_aug_get (guestfs_h *handle,
  83                 const char *path);
  84
  85 Look up the value associated with C<path>.  If C<path>
  86 matches exactly one node, the C<value> is returned.
  87
  88 This function returns a string, or NULL on error.
  89 I<The caller must free the returned string after use>.
  90
  91 =head2 guestfs_aug_init
  92
  93  int guestfs_aug_init (guestfs_h *handle,
  94                 const char *root,
  95                 int flags);
  96
  97 Create a new Augeas handle for editing configuration files.
  98 If there was any previous Augeas handle associated with this
  99 guestfs session, then it is closed.
 100
 101 You must call this before using any other C<guestfs_aug_*>
 102 commands.
 103
 104 C<root> is the filesystem root.  C<root> must not be NULL,
 105 use C</> instead.
 106
 107 The flags are the same as the flags defined in
 108 E<lt>augeas.hE<gt>, the logical I<or> of the following
 109 integers:
 110
 111 =over 4
 112
 113 =item C<AUG_SAVE_BACKUP> = 1
 114
 115 Keep the original file with a C<.augsave> extension.
 116
 117 =item C<AUG_SAVE_NEWFILE> = 2
 118
 119 Save changes into a file with extension C<.augnew>, and
 120 do not overwrite original.  Overrides C<AUG_SAVE_BACKUP>.
 121
 122 =item C<AUG_TYPE_CHECK> = 4
 123
 124 Typecheck lenses (can be expensive).
 125
 126 =item C<AUG_NO_STDINC> = 8
 127
 128 Do not use standard load path for modules.
 129
 130 =item C<AUG_SAVE_NOOP> = 16
 131
 132 Make save a no-op, just record what would have been changed.
 133
 134 =item C<AUG_NO_LOAD> = 32
 135
 136 Do not load the tree in C<guestfs_aug_init>.
 137
 138 =back
 139
 140 To close the handle, you can call C<guestfs_aug_close>.
 141
 142 To find out more about Augeas, see L<http://augeas.net/>.
 143
 144 This function returns 0 on success or -1 on error.
 145
 146 =head2 guestfs_aug_insert
 147
 148  int guestfs_aug_insert (guestfs_h *handle,
 149                 const char *path,
 150                 const char *label,
 151                 int before);
 152
 153 Create a new sibling C<label> for C<path>, inserting it into
 154 the tree before or after C<path> (depending on the boolean
 155 flag C<before>).
 156
 157 C<path> must match exactly one existing node in the tree, and
 158 C<label> must be a label, ie. not contain C</>, C<*> or end
 159 with a bracketed index C<[N]>.
 160
 161 This function returns 0 on success or -1 on error.
 162
 163 =head2 guestfs_aug_load
 164
 165  int guestfs_aug_load (guestfs_h *handle);
 166
 167 Load files into the tree.
 168
 169 See C<aug_load> in the Augeas documentation for the full gory
 170 details.
 171
 172 This function returns 0 on success or -1 on error.
 173
 174 =head2 guestfs_aug_ls
 175
 176  char **guestfs_aug_ls (guestfs_h *handle,
 177                 const char *path);
 178
 179 This is just a shortcut for listing C<guestfs_aug_match>
 180 C<path/*> and sorting the resulting nodes into alphabetical order.
 181
 182 This function returns a NULL-terminated array of strings
 183 (like L<environ(3)>), or NULL if there was an error.
 184 I<The caller must free the strings and the array after use>.
 185
 186 =head2 guestfs_aug_match
 187
 188  char **guestfs_aug_match (guestfs_h *handle,
 189                 const char *path);
 190
 191 Returns a list of paths which match the path expression C<path>.
 192 The returned paths are sufficiently qualified so that they match
 193 exactly one node in the current tree.
 194
 195 This function returns a NULL-terminated array of strings
 196 (like L<environ(3)>), or NULL if there was an error.
 197 I<The caller must free the strings and the array after use>.
 198
 199 =head2 guestfs_aug_mv
 200
 201  int guestfs_aug_mv (guestfs_h *handle,
 202                 const char *src,
 203                 const char *dest);
 204
 205 Move the node C<src> to C<dest>.  C<src> must match exactly
 206 one node.  C<dest> is overwritten if it exists.
 207
 208 This function returns 0 on success or -1 on error.
 209
 210 =head2 guestfs_aug_rm
 211
 212  int guestfs_aug_rm (guestfs_h *handle,
 213                 const char *path);
 214
 215 Remove C<path> and all of its children.
 216
 217 On success this returns the number of entries which were removed.
 218
 219 On error this function returns -1.
 220
 221 =head2 guestfs_aug_save
 222
 223  int guestfs_aug_save (guestfs_h *handle);
 224
 225 This writes all pending changes to disk.
 226
 227 The flags which were passed to C<guestfs_aug_init> affect exactly
 228 how files are saved.
 229
 230 This function returns 0 on success or -1 on error.
 231
 232 =head2 guestfs_aug_set
 233
 234  int guestfs_aug_set (guestfs_h *handle,
 235                 const char *path,
 236                 const char *val);
 237
 238 Set the value associated with C<path> to C<value>.
 239
 240 This function returns 0 on success or -1 on error.
 241
 242 =head2 guestfs_blockdev_flushbufs
 243
 244  int guestfs_blockdev_flushbufs (guestfs_h *handle,
 245                 const char *device);
 246
 247 This tells the kernel to flush internal buffers associated
 248 with C<device>.
 249
 250 This uses the L<blockdev(8)> command.
 251
 252 This function returns 0 on success or -1 on error.
 253
 254 =head2 guestfs_blockdev_getbsz
 255
 256  int guestfs_blockdev_getbsz (guestfs_h *handle,
 257                 const char *device);
 258
 259 This returns the block size of a device.
 260
 261 (Note this is different from both I<size in blocks> and
 262 I<filesystem block size>).
 263
 264 This uses the L<blockdev(8)> command.
 265
 266 On error this function returns -1.
 267
 268 =head2 guestfs_blockdev_getro
 269
 270  int guestfs_blockdev_getro (guestfs_h *handle,
 271                 const char *device);
 272
 273 Returns a boolean indicating if the block device is read-only
 274 (true if read-only, false if not).
 275
 276 This uses the L<blockdev(8)> command.
 277
 278 This function returns a C truth value on success or -1 on error.
 279
 280 =head2 guestfs_blockdev_getsize64
 281
 282  int64_t guestfs_blockdev_getsize64 (guestfs_h *handle,
 283                 const char *device);
 284
 285 This returns the size of the device in bytes.
 286
 287 See also C<guestfs_blockdev_getsz>.
 288
 289 This uses the L<blockdev(8)> command.
 290
 291 On error this function returns -1.
 292
 293 =head2 guestfs_blockdev_getss
 294
 295  int guestfs_blockdev_getss (guestfs_h *handle,
 296                 const char *device);
 297
 298 This returns the size of sectors on a block device.
 299 Usually 512, but can be larger for modern devices.
 300
 301 (Note, this is not the size in sectors, use C<guestfs_blockdev_getsz>
 302 for that).
 303
 304 This uses the L<blockdev(8)> command.
 305
 306 On error this function returns -1.
 307
 308 =head2 guestfs_blockdev_getsz
 309
 310  int64_t guestfs_blockdev_getsz (guestfs_h *handle,
 311                 const char *device);
 312
 313 This returns the size of the device in units of 512-byte sectors
 314 (even if the sectorsize isn't 512 bytes ... weird).
 315
 316 See also C<guestfs_blockdev_getss> for the real sector size of
 317 the device, and C<guestfs_blockdev_getsize64> for the more
 318 useful I<size in bytes>.
 319
 320 This uses the L<blockdev(8)> command.
 321
 322 On error this function returns -1.
 323
 324 =head2 guestfs_blockdev_rereadpt
 325
 326  int guestfs_blockdev_rereadpt (guestfs_h *handle,
 327                 const char *device);
 328
 329 Reread the partition table on C<device>.
 330
 331 This uses the L<blockdev(8)> command.
 332
 333 This function returns 0 on success or -1 on error.
 334
 335 =head2 guestfs_blockdev_setbsz
 336
 337  int guestfs_blockdev_setbsz (guestfs_h *handle,
 338                 const char *device,
 339                 int blocksize);
 340
 341 This sets the block size of a device.
 342
 343 (Note this is different from both I<size in blocks> and
 344 I<filesystem block size>).
 345
 346 This uses the L<blockdev(8)> command.
 347
 348 This function returns 0 on success or -1 on error.
 349
 350 =head2 guestfs_blockdev_setro
 351
 352  int guestfs_blockdev_setro (guestfs_h *handle,
 353                 const char *device);
 354
 355 Sets the block device named C<device> to read-only.
 356
 357 This uses the L<blockdev(8)> command.
 358
 359 This function returns 0 on success or -1 on error.
 360
 361 =head2 guestfs_blockdev_setrw
 362
 363  int guestfs_blockdev_setrw (guestfs_h *handle,
 364                 const char *device);
 365
 366 Sets the block device named C<device> to read-write.
 367
 368 This uses the L<blockdev(8)> command.
 369
 370 This function returns 0 on success or -1 on error.
 371
 372 =head2 guestfs_cat
 373
 374  char *guestfs_cat (guestfs_h *handle,
 375                 const char *path);
 376
 377 Return the contents of the file named C<path>.
 378
 379 Note that this function cannot correctly handle binary files
 380 (specifically, files containing C<\0> character which is treated
 381 as end of string).  For those you need to use the C<guestfs_read_file>
 382 function which has a more complex interface.
 383
 384 This function returns a string, or NULL on error.
 385 I<The caller must free the returned string after use>.
 386
 387 Because of the message protocol, there is a transfer limit
 388 of somewhere between 2MB and 4MB.  To transfer large files you should use
 389 FTP.
 390
 391 =head2 guestfs_chmod
 392
 393  int guestfs_chmod (guestfs_h *handle,
 394                 int mode,
 395                 const char *path);
 396
 397 Change the mode (permissions) of C<path> to C<mode>.  Only
 398 numeric modes are supported.
 399
 400 This function returns 0 on success or -1 on error.
 401
 402 =head2 guestfs_chown
 403
 404  int guestfs_chown (guestfs_h *handle,
 405                 int owner,
 406                 int group,
 407                 const char *path);
 408
 409 Change the file owner to C<owner> and group to C<group>.
 410
 411 Only numeric uid and gid are supported.  If you want to use
 412 names, you will need to locate and parse the password file
 413 yourself (Augeas support makes this relatively easy).
 414
 415 This function returns 0 on success or -1 on error.
 416
 417 =head2 guestfs_command
 418
 419  char *guestfs_command (guestfs_h *handle,
 420                 char * const* const arguments);
 421
 422 This call runs a command from the guest filesystem.  The
 423 filesystem must be mounted, and must contain a compatible
 424 operating system (ie. something Linux, with the same
 425 or compatible processor architecture).
 426
 427 The single parameter is an argv-style list of arguments.
 428 The first element is the name of the program to run.
 429 Subsequent elements are parameters.  The list must be
 430 non-empty (ie. must contain a program name).
 431
 432 The C<$PATH> environment variable will contain at least
 433 C</usr/bin> and C</bin>.  If you require a program from
 434 another location, you should provide the full path in the
 435 first parameter.
 436
 437 Shared libraries and data files required by the program
 438 must be available on filesystems which are mounted in the
 439 correct places.  It is the caller's responsibility to ensure
 440 all filesystems that are needed are mounted at the right
 441 locations.
 442
 443 This function returns a string, or NULL on error.
 444 I<The caller must free the returned string after use>.
 445
 446 =head2 guestfs_command_lines
 447
 448  char **guestfs_command_lines (guestfs_h *handle,
 449                 char * const* const arguments);
 450
 451 This is the same as C<guestfs_command>, but splits the
 452 result into a list of lines.
 453
 454 This function returns a NULL-terminated array of strings
 455 (like L<environ(3)>), or NULL if there was an error.
 456 I<The caller must free the strings and the array after use>.
 457
 458 =head2 guestfs_config
 459
 460  int guestfs_config (guestfs_h *handle,
 461                 const char *qemuparam,
 462                 const char *qemuvalue);
 463
 464 This can be used to add arbitrary qemu command line parameters
 465 of the form C<-param value>.  Actually it's not quite arbitrary - we
 466 prevent you from setting some parameters which would interfere with
 467 parameters that we use.
 468
 469 The first character of C<param> string must be a C<-> (dash).
 470
 471 C<value> can be NULL.
 472
 473 This function returns 0 on success or -1 on error.
 474
 475 =head2 guestfs_exists
 476
 477  int guestfs_exists (guestfs_h *handle,
 478                 const char *path);
 479
 480 This returns C<true> if and only if there is a file, directory
 481 (or anything) with the given C<path> name.
 482
 483 See also C<guestfs_is_file>, C<guestfs_is_dir>, C<guestfs_stat>.
 484
 485 This function returns a C truth value on success or -1 on error.
 486
 487 =head2 guestfs_file
 488
 489  char *guestfs_file (guestfs_h *handle,
 490                 const char *path);
 491
 492 This call uses the standard L<file(1)> command to determine
 493 the type or contents of the file.  This also works on devices,
 494 for example to find out whether a partition contains a filesystem.
 495
 496 The exact command which runs is C<file -bsL path>.  Note in
 497 particular that the filename is not prepended to the output
 498 (the C<-b> option).
 499
 500 This function returns a string, or NULL on error.
 501 I<The caller must free the returned string after use>.
 502
 503 =head2 guestfs_get_autosync
 504
 505  int guestfs_get_autosync (guestfs_h *handle);
 506
 507 Get the autosync flag.
 508
 509 This function returns a C truth value on success or -1 on error.
 510
 511 =head2 guestfs_get_path
 512
 513  const char *guestfs_get_path (guestfs_h *handle);
 514
 515 Return the current search path.
 516
 517 This is always non-NULL.  If it wasn't set already, then this will
 518 return the default path.
 519
 520 This function returns a string, or NULL on error.
 521 The string is owned by the guest handle and must I<not> be freed.
 522
 523 =head2 guestfs_get_verbose
 524
 525  int guestfs_get_verbose (guestfs_h *handle);
 526
 527 This returns the verbose messages flag.
 528
 529 This function returns a C truth value on success or -1 on error.
 530
 531 =head2 guestfs_is_dir
 532
 533  int guestfs_is_dir (guestfs_h *handle,
 534                 const char *path);
 535
 536 This returns C<true> if and only if there is a directory
 537 with the given C<path> name.  Note that it returns false for
 538 other objects like files.
 539
 540 See also C<guestfs_stat>.
 541
 542 This function returns a C truth value on success or -1 on error.
 543
 544 =head2 guestfs_is_file
 545
 546  int guestfs_is_file (guestfs_h *handle,
 547                 const char *path);
 548
 549 This returns C<true> if and only if there is a file
 550 with the given C<path> name.  Note that it returns false for
 551 other objects like directories.
 552
 553 See also C<guestfs_stat>.
 554
 555 This function returns a C truth value on success or -1 on error.
 556
 557 =head2 guestfs_kill_subprocess
 558
 559  int guestfs_kill_subprocess (guestfs_h *handle);
 560
 561 This kills the qemu subprocess.  You should never need to call this.
 562
 563 This function returns 0 on success or -1 on error.
 564
 565 =head2 guestfs_launch
 566
 567  int guestfs_launch (guestfs_h *handle);
 568
 569 Internally libguestfs is implemented by running a virtual machine
 570 using L<qemu(1)>.
 571
 572 You should call this after configuring the handle
 573 (eg. adding drives) but before performing any actions.
 574
 575 This function returns 0 on success or -1 on error.
 576
 577 =head2 guestfs_list_devices
 578
 579  char **guestfs_list_devices (guestfs_h *handle);
 580
 581 List all the block devices.
 582
 583 The full block device names are returned, eg. C</dev/sda>
 584
 585 This function returns a NULL-terminated array of strings
 586 (like L<environ(3)>), or NULL if there was an error.
 587 I<The caller must free the strings and the array after use>.
 588
 589 =head2 guestfs_list_partitions
 590
 591  char **guestfs_list_partitions (guestfs_h *handle);
 592
 593 List all the partitions detected on all block devices.
 594
 595 The full partition device names are returned, eg. C</dev/sda1>
 596
 597 This does not return logical volumes.  For that you will need to
 598 call C<guestfs_lvs>.
 599
 600 This function returns a NULL-terminated array of strings
 601 (like L<environ(3)>), or NULL if there was an error.
 602 I<The caller must free the strings and the array after use>.
 603
 604 =head2 guestfs_ll
 605
 606  char *guestfs_ll (guestfs_h *handle,
 607                 const char *directory);
 608
 609 List the files in C<directory> (relative to the root directory,
 610 there is no cwd) in the format of 'ls -la'.
 611
 612 This command is mostly useful for interactive sessions.  It
 613 is I<not> intended that you try to parse the output string.
 614
 615 This function returns a string, or NULL on error.
 616 I<The caller must free the returned string after use>.
 617
 618 =head2 guestfs_ls
 619
 620  char **guestfs_ls (guestfs_h *handle,
 621                 const char *directory);
 622
 623 List the files in C<directory> (relative to the root directory,
 624 there is no cwd).  The '.' and '..' entries are not returned, but
 625 hidden files are shown.
 626
 627 This command is mostly useful for interactive sessions.  Programs
 628 should probably use C<guestfs_readdir> instead.
 629
 630 This function returns a NULL-terminated array of strings
 631 (like L<environ(3)>), or NULL if there was an error.
 632 I<The caller must free the strings and the array after use>.
 633
 634 =head2 guestfs_lstat
 635
 636  struct guestfs_stat *guestfs_lstat (guestfs_h *handle,
 637                 const char *path);
 638
 639 Returns file information for the given C<path>.
 640
 641 This is the same as C<guestfs_stat> except that if C<path>
 642 is a symbolic link, then the link is stat-ed, not the file it
 643 refers to.
 644
 645 This is the same as the C<lstat(2)> system call.
 646
 647 This function returns a C<struct guestfs_stat *>
 648 (see L<stat(2)> and E<lt>guestfs-structs.hE<gt>),
 649 or NULL if there was an error.
 650 I<The caller must call C<free> after use>.
 651
 652 =head2 guestfs_lvcreate
 653
 654  int guestfs_lvcreate (guestfs_h *handle,
 655                 const char *logvol,
 656                 const char *volgroup,
 657                 int mbytes);
 658
 659 This creates an LVM volume group called C<logvol>
 660 on the volume group C<volgroup>, with C<size> megabytes.
 661
 662 This function returns 0 on success or -1 on error.
 663
 664 =head2 guestfs_lvm_remove_all
 665
 666  int guestfs_lvm_remove_all (guestfs_h *handle);
 667
 668 This command removes all LVM logical volumes, volume groups
 669 and physical volumes.
 670
 671 This function returns 0 on success or -1 on error.
 672
 673 B<This command is dangerous.  Without careful use you
 674 can easily destroy all your data>.
 675
 676 =head2 guestfs_lvs
 677
 678  char **guestfs_lvs (guestfs_h *handle);
 679
 680 List all the logical volumes detected.  This is the equivalent
 681 of the L<lvs(8)> command.
 682
 683 This returns a list of the logical volume device names
 684 (eg. C</dev/VolGroup00/LogVol00>).
 685
 686 See also C<guestfs_lvs_full>.
 687
 688 This function returns a NULL-terminated array of strings
 689 (like L<environ(3)>), or NULL if there was an error.
 690 I<The caller must free the strings and the array after use>.
 691
 692 =head2 guestfs_lvs_full
 693
 694  struct guestfs_lvm_lv_list *guestfs_lvs_full (guestfs_h *handle);
 695
 696 List all the logical volumes detected.  This is the equivalent
 697 of the L<lvs(8)> command.  The "full" version includes all fields.
 698
 699 This function returns a C<struct guestfs_lvm_lv_list *>
 700 (see E<lt>guestfs-structs.hE<gt>),
 701 or NULL if there was an error.
 702 I<The caller must call C<guestfs_free_lvm_lv_list> after use>.
 703
 704 =head2 guestfs_mkdir
 705
 706  int guestfs_mkdir (guestfs_h *handle,
 707                 const char *path);
 708
 709 Create a directory named C<path>.
 710
 711 This function returns 0 on success or -1 on error.
 712
 713 =head2 guestfs_mkdir_p
 714
 715  int guestfs_mkdir_p (guestfs_h *handle,
 716                 const char *path);
 717
 718 Create a directory named C<path>, creating any parent directories
 719 as necessary.  This is like the C<mkdir -p> shell command.
 720
 721 This function returns 0 on success or -1 on error.
 722
 723 =head2 guestfs_mkfs
 724
 725  int guestfs_mkfs (guestfs_h *handle,
 726                 const char *fstype,
 727                 const char *device);
 728
 729 This creates a filesystem on C<device> (usually a partition
 730 of LVM logical volume).  The filesystem type is C<fstype>, for
 731 example C<ext3>.
 732
 733 This function returns 0 on success or -1 on error.
 734
 735 =head2 guestfs_mount
 736
 737  int guestfs_mount (guestfs_h *handle,
 738                 const char *device,
 739                 const char *mountpoint);
 740
 741 Mount a guest disk at a position in the filesystem.  Block devices
 742 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
 743 the guest.  If those block devices contain partitions, they will have
 744 the usual names (eg. C</dev/sda1>).  Also LVM C</dev/VG/LV>-style
 745 names can be used.
 746
 747 The rules are the same as for L<mount(2)>:  A filesystem must
 748 first be mounted on C</> before others can be mounted.  Other
 749 filesystems can only be mounted on directories which already
 750 exist.
 751
 752 The mounted filesystem is writable, if we have sufficient permissions
 753 on the underlying device.
 754
 755 The filesystem options C<sync> and C<noatime> are set with this
 756 call, in order to improve reliability.
 757
 758 This function returns 0 on success or -1 on error.
 759
 760 =head2 guestfs_mounts
 761
 762  char **guestfs_mounts (guestfs_h *handle);
 763
 764 This returns the list of currently mounted filesystems.  It returns
 765 the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
 766
 767 Some internal mounts are not shown.
 768
 769 This function returns a NULL-terminated array of strings
 770 (like L<environ(3)>), or NULL if there was an error.
 771 I<The caller must free the strings and the array after use>.
 772
 773 =head2 guestfs_pvcreate
 774
 775  int guestfs_pvcreate (guestfs_h *handle,
 776                 const char *device);
 777
 778 This creates an LVM physical volume on the named C<device>,
 779 where C<device> should usually be a partition name such
 780 as C</dev/sda1>.
 781
 782 This function returns 0 on success or -1 on error.
 783
 784 =head2 guestfs_pvs
 785
 786  char **guestfs_pvs (guestfs_h *handle);
 787
 788 List all the physical volumes detected.  This is the equivalent
 789 of the L<pvs(8)> command.
 790
 791 This returns a list of just the device names that contain
 792 PVs (eg. C</dev/sda2>).
 793
 794 See also C<guestfs_pvs_full>.
 795
 796 This function returns a NULL-terminated array of strings
 797 (like L<environ(3)>), or NULL if there was an error.
 798 I<The caller must free the strings and the array after use>.
 799
 800 =head2 guestfs_pvs_full
 801
 802  struct guestfs_lvm_pv_list *guestfs_pvs_full (guestfs_h *handle);
 803
 804 List all the physical volumes detected.  This is the equivalent
 805 of the L<pvs(8)> command.  The "full" version includes all fields.
 806
 807 This function returns a C<struct guestfs_lvm_pv_list *>
 808 (see E<lt>guestfs-structs.hE<gt>),
 809 or NULL if there was an error.
 810 I<The caller must call C<guestfs_free_lvm_pv_list> after use>.
 811
 812 =head2 guestfs_read_lines
 813
 814  char **guestfs_read_lines (guestfs_h *handle,
 815                 const char *path);
 816
 817 Return the contents of the file named C<path>.
 818
 819 The file contents are returned as a list of lines.  Trailing
 820 C<LF> and C<CRLF> character sequences are I<not> returned.
 821
 822 Note that this function cannot correctly handle binary files
 823 (specifically, files containing C<\0> character which is treated
 824 as end of line).  For those you need to use the C<guestfs_read_file>
 825 function which has a more complex interface.
 826
 827 This function returns a NULL-terminated array of strings
 828 (like L<environ(3)>), or NULL if there was an error.
 829 I<The caller must free the strings and the array after use>.
 830
 831 =head2 guestfs_rm
 832
 833  int guestfs_rm (guestfs_h *handle,
 834                 const char *path);
 835
 836 Remove the single file C<path>.
 837
 838 This function returns 0 on success or -1 on error.
 839
 840 =head2 guestfs_rm_rf
 841
 842  int guestfs_rm_rf (guestfs_h *handle,
 843                 const char *path);
 844
 845 Remove the file or directory C<path>, recursively removing the
 846 contents if its a directory.  This is like the C<rm -rf> shell
 847 command.
 848
 849 This function returns 0 on success or -1 on error.
 850
 851 =head2 guestfs_rmdir
 852
 853  int guestfs_rmdir (guestfs_h *handle,
 854                 const char *path);
 855
 856 Remove the single directory C<path>.
 857
 858 This function returns 0 on success or -1 on error.
 859
 860 =head2 guestfs_set_autosync
 861
 862  int guestfs_set_autosync (guestfs_h *handle,
 863                 int autosync);
 864
 865 If C<autosync> is true, this enables autosync.  Libguestfs will make a
 866 best effort attempt to run C<guestfs_sync> when the handle is closed
 867 (also if the program exits without closing handles).
 868
 869 This function returns 0 on success or -1 on error.
 870
 871 =head2 guestfs_set_path
 872
 873  int guestfs_set_path (guestfs_h *handle,
 874                 const char *path);
 875
 876 Set the path that libguestfs searches for kernel and initrd.img.
 877
 878 The default is C<$libdir/guestfs> unless overridden by setting
 879 C<LIBGUESTFS_PATH> environment variable.
 880
 881 The string C<path> is stashed in the libguestfs handle, so the caller
 882 must make sure it remains valid for the lifetime of the handle.
 883
 884 Setting C<path> to C<NULL> restores the default path.
 885
 886 This function returns 0 on success or -1 on error.
 887
 888 =head2 guestfs_set_verbose
 889
 890  int guestfs_set_verbose (guestfs_h *handle,
 891                 int verbose);
 892
 893 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
 894
 895 Verbose messages are disabled unless the environment variable
 896 C<LIBGUESTFS_DEBUG> is defined and set to C<1>.
 897
 898 This function returns 0 on success or -1 on error.
 899
 900 =head2 guestfs_sfdisk
 901
 902  int guestfs_sfdisk (guestfs_h *handle,
 903                 const char *device,
 904                 int cyls,
 905                 int heads,
 906                 int sectors,
 907                 char * const* const lines);
 908
 909 This is a direct interface to the L<sfdisk(8)> program for creating
 910 partitions on block devices.
 911
 912 C<device> should be a block device, for example C</dev/sda>.
 913
 914 C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads
 915 and sectors on the device, which are passed directly to sfdisk as
 916 the I<-C>, I<-H> and I<-S> parameters.  If you pass C<0> for any
 917 of these, then the corresponding parameter is omitted.  Usually for
 918 'large' disks, you can just pass C<0> for these, but for small
 919 (floppy-sized) disks, sfdisk (or rather, the kernel) cannot work
 920 out the right geometry and you will need to tell it.
 921
 922 C<lines> is a list of lines that we feed to C<sfdisk>.  For more
 923 information refer to the L<sfdisk(8)> manpage.
 924
 925 To create a single partition occupying the whole disk, you would
 926 pass C<lines> as a single element list, when the single element being
 927 the string C<,> (comma).
 928
 929 This function returns 0 on success or -1 on error.
 930
 931 B<This command is dangerous.  Without careful use you
 932 can easily destroy all your data>.
 933
 934 =head2 guestfs_stat
 935
 936  struct guestfs_stat *guestfs_stat (guestfs_h *handle,
 937                 const char *path);
 938
 939 Returns file information for the given C<path>.
 940
 941 This is the same as the C<stat(2)> system call.
 942
 943 This function returns a C<struct guestfs_stat *>
 944 (see L<stat(2)> and E<lt>guestfs-structs.hE<gt>),
 945 or NULL if there was an error.
 946 I<The caller must call C<free> after use>.
 947
 948 =head2 guestfs_statvfs
 949
 950  struct guestfs_statvfs *guestfs_statvfs (guestfs_h *handle,
 951                 const char *path);
 952
 953 Returns file system statistics for any mounted file system.
 954 C<path> should be a file or directory in the mounted file system
 955 (typically it is the mount point itself, but it doesn't need to be).
 956
 957 This is the same as the C<statvfs(2)> system call.
 958
 959 This function returns a C<struct guestfs_statvfs *>
 960 (see L<statvfs(2)> and E<lt>guestfs-structs.hE<gt>),
 961 or NULL if there was an error.
 962 I<The caller must call C<free> after use>.
 963
 964 =head2 guestfs_sync
 965
 966  int guestfs_sync (guestfs_h *handle);
 967
 968 This syncs the disk, so that any writes are flushed through to the
 969 underlying disk image.
 970
 971 You should always call this if you have modified a disk image, before
 972 closing the handle.
 973
 974 This function returns 0 on success or -1 on error.
 975
 976 =head2 guestfs_touch
 977
 978  int guestfs_touch (guestfs_h *handle,
 979                 const char *path);
 980
 981 Touch acts like the L<touch(1)> command.  It can be used to
 982 update the timestamps on a file, or, if the file does not exist,
 983 to create a new zero-length file.
 984
 985 This function returns 0 on success or -1 on error.
 986
 987 =head2 guestfs_tune2fs_l
 988
 989  char **guestfs_tune2fs_l (guestfs_h *handle,
 990                 const char *device);
 991
 992 This returns the contents of the ext2 or ext3 filesystem superblock
 993 on C<device>.
 994
 995 It is the same as running C<tune2fs -l device>.  See L<tune2fs(8)>
 996 manpage for more details.  The list of fields returned isn't
 997 clearly defined, and depends on both the version of C<tune2fs>
 998 that libguestfs was built against, and the filesystem itself.
 999
1000 This function returns a NULL-terminated array of
1001 strings, or NULL if there was an error.
1002 The array of strings will always have length C<2n+1>, where
1003 C<n> keys and values alternate, followed by the trailing NULL entry.
1004 I<The caller must free the strings and the array after use>.
1005
1006 =head2 guestfs_umount
1007
1008  int guestfs_umount (guestfs_h *handle,
1009                 const char *pathordevice);
1010
1011 This unmounts the given filesystem.  The filesystem may be
1012 specified either by its mountpoint (path) or the device which
1013 contains the filesystem.
1014
1015 This function returns 0 on success or -1 on error.
1016
1017 =head2 guestfs_umount_all
1018
1019  int guestfs_umount_all (guestfs_h *handle);
1020
1021 This unmounts all mounted filesystems.
1022
1023 Some internal mounts are not unmounted by this call.
1024
1025 This function returns 0 on success or -1 on error.
1026
1027 =head2 guestfs_vgcreate
1028
1029  int guestfs_vgcreate (guestfs_h *handle,
1030                 const char *volgroup,
1031                 char * const* const physvols);
1032
1033 This creates an LVM volume group called C<volgroup>
1034 from the non-empty list of physical volumes C<physvols>.
1035
1036 This function returns 0 on success or -1 on error.
1037
1038 =head2 guestfs_vgs
1039
1040  char **guestfs_vgs (guestfs_h *handle);
1041
1042 List all the volumes groups detected.  This is the equivalent
1043 of the L<vgs(8)> command.
1044
1045 This returns a list of just the volume group names that were
1046 detected (eg. C<VolGroup00>).
1047
1048 See also C<guestfs_vgs_full>.
1049
1050 This function returns a NULL-terminated array of strings
1051 (like L<environ(3)>), or NULL if there was an error.
1052 I<The caller must free the strings and the array after use>.
1053
1054 =head2 guestfs_vgs_full
1055
1056  struct guestfs_lvm_vg_list *guestfs_vgs_full (guestfs_h *handle);
1057
1058 List all the volumes groups detected.  This is the equivalent
1059 of the L<vgs(8)> command.  The "full" version includes all fields.
1060
1061 This function returns a C<struct guestfs_lvm_vg_list *>
1062 (see E<lt>guestfs-structs.hE<gt>),
1063 or NULL if there was an error.
1064 I<The caller must call C<guestfs_free_lvm_vg_list> after use>.
1065
1066 =head2 guestfs_wait_ready
1067
1068  int guestfs_wait_ready (guestfs_h *handle);
1069
1070 Internally libguestfs is implemented by running a virtual machine
1071 using L<qemu(1)>.
1072
1073 You should call this after C<guestfs_launch> to wait for the launch
1074 to complete.
1075
1076 This function returns 0 on success or -1 on error.
1077
1078 =head2 guestfs_write_file
1079
1080  int guestfs_write_file (guestfs_h *handle,
1081                 const char *path,
1082                 const char *content,
1083                 int size);
1084
1085 This call creates a file called C<path>.  The contents of the
1086 file is the string C<content> (which can contain any 8 bit data),
1087 with length C<size>.
1088
1089 As a special case, if C<size> is C<0>
1090 then the length is calculated using C<strlen> (so in this case
1091 the content cannot contain embedded ASCII NULs).
1092
1093 This function returns 0 on success or -1 on error.
1094
1095 Because of the message protocol, there is a transfer limit
1096 of somewhere between 2MB and 4MB.  To transfer large files you should use
1097 FTP.
1098