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_download>
 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_state
 524
 525  int guestfs_get_state (guestfs_h *handle);
 526
 527 This returns the current state as an opaque integer.  This is
 528 only useful for printing debug and internal error messages.
 529
 530 For more information on states, see L<guestfs(3)>.
 531
 532 On error this function returns -1.
 533
 534 =head2 guestfs_get_verbose
 535
 536  int guestfs_get_verbose (guestfs_h *handle);
 537
 538 This returns the verbose messages flag.
 539
 540 This function returns a C truth value on success or -1 on error.
 541
 542 =head2 guestfs_is_busy
 543
 544  int guestfs_is_busy (guestfs_h *handle);
 545
 546 This returns true iff this handle is busy processing a command
 547 (in the C<BUSY> state).
 548
 549 For more information on states, see L<guestfs(3)>.
 550
 551 This function returns a C truth value on success or -1 on error.
 552
 553 =head2 guestfs_is_config
 554
 555  int guestfs_is_config (guestfs_h *handle);
 556
 557 This returns true iff this handle is being configured
 558 (in the C<CONFIG> state).
 559
 560 For more information on states, see L<guestfs(3)>.
 561
 562 This function returns a C truth value on success or -1 on error.
 563
 564 =head2 guestfs_is_dir
 565
 566  int guestfs_is_dir (guestfs_h *handle,
 567                 const char *path);
 568
 569 This returns C<true> if and only if there is a directory
 570 with the given C<path> name.  Note that it returns false for
 571 other objects like files.
 572
 573 See also C<guestfs_stat>.
 574
 575 This function returns a C truth value on success or -1 on error.
 576
 577 =head2 guestfs_is_file
 578
 579  int guestfs_is_file (guestfs_h *handle,
 580                 const char *path);
 581
 582 This returns C<true> if and only if there is a file
 583 with the given C<path> name.  Note that it returns false for
 584 other objects like directories.
 585
 586 See also C<guestfs_stat>.
 587
 588 This function returns a C truth value on success or -1 on error.
 589
 590 =head2 guestfs_is_launching
 591
 592  int guestfs_is_launching (guestfs_h *handle);
 593
 594 This returns true iff this handle is launching the subprocess
 595 (in the C<LAUNCHING> state).
 596
 597 For more information on states, see L<guestfs(3)>.
 598
 599 This function returns a C truth value on success or -1 on error.
 600
 601 =head2 guestfs_is_ready
 602
 603  int guestfs_is_ready (guestfs_h *handle);
 604
 605 This returns true iff this handle is ready to accept commands
 606 (in the C<READY> state).
 607
 608 For more information on states, see L<guestfs(3)>.
 609
 610 This function returns a C truth value on success or -1 on error.
 611
 612 =head2 guestfs_kill_subprocess
 613
 614  int guestfs_kill_subprocess (guestfs_h *handle);
 615
 616 This kills the qemu subprocess.  You should never need to call this.
 617
 618 This function returns 0 on success or -1 on error.
 619
 620 =head2 guestfs_launch
 621
 622  int guestfs_launch (guestfs_h *handle);
 623
 624 Internally libguestfs is implemented by running a virtual machine
 625 using L<qemu(1)>.
 626
 627 You should call this after configuring the handle
 628 (eg. adding drives) but before performing any actions.
 629
 630 This function returns 0 on success or -1 on error.
 631
 632 =head2 guestfs_list_devices
 633
 634  char **guestfs_list_devices (guestfs_h *handle);
 635
 636 List all the block devices.
 637
 638 The full block device names are returned, eg. C</dev/sda>
 639
 640 This function returns a NULL-terminated array of strings
 641 (like L<environ(3)>), or NULL if there was an error.
 642 I<The caller must free the strings and the array after use>.
 643
 644 =head2 guestfs_list_partitions
 645
 646  char **guestfs_list_partitions (guestfs_h *handle);
 647
 648 List all the partitions detected on all block devices.
 649
 650 The full partition device names are returned, eg. C</dev/sda1>
 651
 652 This does not return logical volumes.  For that you will need to
 653 call C<guestfs_lvs>.
 654
 655 This function returns a NULL-terminated array of strings
 656 (like L<environ(3)>), or NULL if there was an error.
 657 I<The caller must free the strings and the array after use>.
 658
 659 =head2 guestfs_ll
 660
 661  char *guestfs_ll (guestfs_h *handle,
 662                 const char *directory);
 663
 664 List the files in C<directory> (relative to the root directory,
 665 there is no cwd) in the format of 'ls -la'.
 666
 667 This command is mostly useful for interactive sessions.  It
 668 is I<not> intended that you try to parse the output string.
 669
 670 This function returns a string, or NULL on error.
 671 I<The caller must free the returned string after use>.
 672
 673 =head2 guestfs_ls
 674
 675  char **guestfs_ls (guestfs_h *handle,
 676                 const char *directory);
 677
 678 List the files in C<directory> (relative to the root directory,
 679 there is no cwd).  The '.' and '..' entries are not returned, but
 680 hidden files are shown.
 681
 682 This command is mostly useful for interactive sessions.  Programs
 683 should probably use C<guestfs_readdir> instead.
 684
 685 This function returns a NULL-terminated array of strings
 686 (like L<environ(3)>), or NULL if there was an error.
 687 I<The caller must free the strings and the array after use>.
 688
 689 =head2 guestfs_lstat
 690
 691  struct guestfs_stat *guestfs_lstat (guestfs_h *handle,
 692                 const char *path);
 693
 694 Returns file information for the given C<path>.
 695
 696 This is the same as C<guestfs_stat> except that if C<path>
 697 is a symbolic link, then the link is stat-ed, not the file it
 698 refers to.
 699
 700 This is the same as the C<lstat(2)> system call.
 701
 702 This function returns a C<struct guestfs_stat *>
 703 (see L<stat(2)> and E<lt>guestfs-structs.hE<gt>),
 704 or NULL if there was an error.
 705 I<The caller must call C<free> after use>.
 706
 707 =head2 guestfs_lvcreate
 708
 709  int guestfs_lvcreate (guestfs_h *handle,
 710                 const char *logvol,
 711                 const char *volgroup,
 712                 int mbytes);
 713
 714 This creates an LVM volume group called C<logvol>
 715 on the volume group C<volgroup>, with C<size> megabytes.
 716
 717 This function returns 0 on success or -1 on error.
 718
 719 =head2 guestfs_lvm_remove_all
 720
 721  int guestfs_lvm_remove_all (guestfs_h *handle);
 722
 723 This command removes all LVM logical volumes, volume groups
 724 and physical volumes.
 725
 726 This function returns 0 on success or -1 on error.
 727
 728 B<This command is dangerous.  Without careful use you
 729 can easily destroy all your data>.
 730
 731 =head2 guestfs_lvs
 732
 733  char **guestfs_lvs (guestfs_h *handle);
 734
 735 List all the logical volumes detected.  This is the equivalent
 736 of the L<lvs(8)> command.
 737
 738 This returns a list of the logical volume device names
 739 (eg. C</dev/VolGroup00/LogVol00>).
 740
 741 See also C<guestfs_lvs_full>.
 742
 743 This function returns a NULL-terminated array of strings
 744 (like L<environ(3)>), or NULL if there was an error.
 745 I<The caller must free the strings and the array after use>.
 746
 747 =head2 guestfs_lvs_full
 748
 749  struct guestfs_lvm_lv_list *guestfs_lvs_full (guestfs_h *handle);
 750
 751 List all the logical volumes detected.  This is the equivalent
 752 of the L<lvs(8)> command.  The "full" version includes all fields.
 753
 754 This function returns a C<struct guestfs_lvm_lv_list *>
 755 (see E<lt>guestfs-structs.hE<gt>),
 756 or NULL if there was an error.
 757 I<The caller must call C<guestfs_free_lvm_lv_list> after use>.
 758
 759 =head2 guestfs_mkdir
 760
 761  int guestfs_mkdir (guestfs_h *handle,
 762                 const char *path);
 763
 764 Create a directory named C<path>.
 765
 766 This function returns 0 on success or -1 on error.
 767
 768 =head2 guestfs_mkdir_p
 769
 770  int guestfs_mkdir_p (guestfs_h *handle,
 771                 const char *path);
 772
 773 Create a directory named C<path>, creating any parent directories
 774 as necessary.  This is like the C<mkdir -p> shell command.
 775
 776 This function returns 0 on success or -1 on error.
 777
 778 =head2 guestfs_mkfs
 779
 780  int guestfs_mkfs (guestfs_h *handle,
 781                 const char *fstype,
 782                 const char *device);
 783
 784 This creates a filesystem on C<device> (usually a partition
 785 of LVM logical volume).  The filesystem type is C<fstype>, for
 786 example C<ext3>.
 787
 788 This function returns 0 on success or -1 on error.
 789
 790 =head2 guestfs_mount
 791
 792  int guestfs_mount (guestfs_h *handle,
 793                 const char *device,
 794                 const char *mountpoint);
 795
 796 Mount a guest disk at a position in the filesystem.  Block devices
 797 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
 798 the guest.  If those block devices contain partitions, they will have
 799 the usual names (eg. C</dev/sda1>).  Also LVM C</dev/VG/LV>-style
 800 names can be used.
 801
 802 The rules are the same as for L<mount(2)>:  A filesystem must
 803 first be mounted on C</> before others can be mounted.  Other
 804 filesystems can only be mounted on directories which already
 805 exist.
 806
 807 The mounted filesystem is writable, if we have sufficient permissions
 808 on the underlying device.
 809
 810 The filesystem options C<sync> and C<noatime> are set with this
 811 call, in order to improve reliability.
 812
 813 This function returns 0 on success or -1 on error.
 814
 815 =head2 guestfs_mounts
 816
 817  char **guestfs_mounts (guestfs_h *handle);
 818
 819 This returns the list of currently mounted filesystems.  It returns
 820 the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
 821
 822 Some internal mounts are not shown.
 823
 824 This function returns a NULL-terminated array of strings
 825 (like L<environ(3)>), or NULL if there was an error.
 826 I<The caller must free the strings and the array after use>.
 827
 828 =head2 guestfs_pvcreate
 829
 830  int guestfs_pvcreate (guestfs_h *handle,
 831                 const char *device);
 832
 833 This creates an LVM physical volume on the named C<device>,
 834 where C<device> should usually be a partition name such
 835 as C</dev/sda1>.
 836
 837 This function returns 0 on success or -1 on error.
 838
 839 =head2 guestfs_pvs
 840
 841  char **guestfs_pvs (guestfs_h *handle);
 842
 843 List all the physical volumes detected.  This is the equivalent
 844 of the L<pvs(8)> command.
 845
 846 This returns a list of just the device names that contain
 847 PVs (eg. C</dev/sda2>).
 848
 849 See also C<guestfs_pvs_full>.
 850
 851 This function returns a NULL-terminated array of strings
 852 (like L<environ(3)>), or NULL if there was an error.
 853 I<The caller must free the strings and the array after use>.
 854
 855 =head2 guestfs_pvs_full
 856
 857  struct guestfs_lvm_pv_list *guestfs_pvs_full (guestfs_h *handle);
 858
 859 List all the physical volumes detected.  This is the equivalent
 860 of the L<pvs(8)> command.  The "full" version includes all fields.
 861
 862 This function returns a C<struct guestfs_lvm_pv_list *>
 863 (see E<lt>guestfs-structs.hE<gt>),
 864 or NULL if there was an error.
 865 I<The caller must call C<guestfs_free_lvm_pv_list> after use>.
 866
 867 =head2 guestfs_read_lines
 868
 869  char **guestfs_read_lines (guestfs_h *handle,
 870                 const char *path);
 871
 872 Return the contents of the file named C<path>.
 873
 874 The file contents are returned as a list of lines.  Trailing
 875 C<LF> and C<CRLF> character sequences are I<not> returned.
 876
 877 Note that this function cannot correctly handle binary files
 878 (specifically, files containing C<\0> character which is treated
 879 as end of line).  For those you need to use the C<guestfs_read_file>
 880 function which has a more complex interface.
 881
 882 This function returns a NULL-terminated array of strings
 883 (like L<environ(3)>), or NULL if there was an error.
 884 I<The caller must free the strings and the array after use>.
 885
 886 =head2 guestfs_rm
 887
 888  int guestfs_rm (guestfs_h *handle,
 889                 const char *path);
 890
 891 Remove the single file C<path>.
 892
 893 This function returns 0 on success or -1 on error.
 894
 895 =head2 guestfs_rm_rf
 896
 897  int guestfs_rm_rf (guestfs_h *handle,
 898                 const char *path);
 899
 900 Remove the file or directory C<path>, recursively removing the
 901 contents if its a directory.  This is like the C<rm -rf> shell
 902 command.
 903
 904 This function returns 0 on success or -1 on error.
 905
 906 =head2 guestfs_rmdir
 907
 908  int guestfs_rmdir (guestfs_h *handle,
 909                 const char *path);
 910
 911 Remove the single directory C<path>.
 912
 913 This function returns 0 on success or -1 on error.
 914
 915 =head2 guestfs_set_autosync
 916
 917  int guestfs_set_autosync (guestfs_h *handle,
 918                 int autosync);
 919
 920 If C<autosync> is true, this enables autosync.  Libguestfs will make a
 921 best effort attempt to run C<guestfs_sync> when the handle is closed
 922 (also if the program exits without closing handles).
 923
 924 This function returns 0 on success or -1 on error.
 925
 926 =head2 guestfs_set_path
 927
 928  int guestfs_set_path (guestfs_h *handle,
 929                 const char *path);
 930
 931 Set the path that libguestfs searches for kernel and initrd.img.
 932
 933 The default is C<$libdir/guestfs> unless overridden by setting
 934 C<LIBGUESTFS_PATH> environment variable.
 935
 936 The string C<path> is stashed in the libguestfs handle, so the caller
 937 must make sure it remains valid for the lifetime of the handle.
 938
 939 Setting C<path> to C<NULL> restores the default path.
 940
 941 This function returns 0 on success or -1 on error.
 942
 943 =head2 guestfs_set_verbose
 944
 945  int guestfs_set_verbose (guestfs_h *handle,
 946                 int verbose);
 947
 948 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
 949
 950 Verbose messages are disabled unless the environment variable
 951 C<LIBGUESTFS_DEBUG> is defined and set to C<1>.
 952
 953 This function returns 0 on success or -1 on error.
 954
 955 =head2 guestfs_sfdisk
 956
 957  int guestfs_sfdisk (guestfs_h *handle,
 958                 const char *device,
 959                 int cyls,
 960                 int heads,
 961                 int sectors,
 962                 char * const* const lines);
 963
 964 This is a direct interface to the L<sfdisk(8)> program for creating
 965 partitions on block devices.
 966
 967 C<device> should be a block device, for example C</dev/sda>.
 968
 969 C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads
 970 and sectors on the device, which are passed directly to sfdisk as
 971 the I<-C>, I<-H> and I<-S> parameters.  If you pass C<0> for any
 972 of these, then the corresponding parameter is omitted.  Usually for
 973 'large' disks, you can just pass C<0> for these, but for small
 974 (floppy-sized) disks, sfdisk (or rather, the kernel) cannot work
 975 out the right geometry and you will need to tell it.
 976
 977 C<lines> is a list of lines that we feed to C<sfdisk>.  For more
 978 information refer to the L<sfdisk(8)> manpage.
 979
 980 To create a single partition occupying the whole disk, you would
 981 pass C<lines> as a single element list, when the single element being
 982 the string C<,> (comma).
 983
 984 This function returns 0 on success or -1 on error.
 985
 986 B<This command is dangerous.  Without careful use you
 987 can easily destroy all your data>.
 988
 989 =head2 guestfs_stat
 990
 991  struct guestfs_stat *guestfs_stat (guestfs_h *handle,
 992                 const char *path);
 993
 994 Returns file information for the given C<path>.
 995
 996 This is the same as the C<stat(2)> system call.
 997
 998 This function returns a C<struct guestfs_stat *>
 999 (see L<stat(2)> and E<lt>guestfs-structs.hE<gt>),
1000 or NULL if there was an error.
1001 I<The caller must call C<free> after use>.
1002
1003 =head2 guestfs_statvfs
1004
1005  struct guestfs_statvfs *guestfs_statvfs (guestfs_h *handle,
1006                 const char *path);
1007
1008 Returns file system statistics for any mounted file system.
1009 C<path> should be a file or directory in the mounted file system
1010 (typically it is the mount point itself, but it doesn't need to be).
1011
1012 This is the same as the C<statvfs(2)> system call.
1013
1014 This function returns a C<struct guestfs_statvfs *>
1015 (see L<statvfs(2)> and E<lt>guestfs-structs.hE<gt>),
1016 or NULL if there was an error.
1017 I<The caller must call C<free> after use>.
1018
1019 =head2 guestfs_sync
1020
1021  int guestfs_sync (guestfs_h *handle);
1022
1023 This syncs the disk, so that any writes are flushed through to the
1024 underlying disk image.
1025
1026 You should always call this if you have modified a disk image, before
1027 closing the handle.
1028
1029 This function returns 0 on success or -1 on error.
1030
1031 =head2 guestfs_touch
1032
1033  int guestfs_touch (guestfs_h *handle,
1034                 const char *path);
1035
1036 Touch acts like the L<touch(1)> command.  It can be used to
1037 update the timestamps on a file, or, if the file does not exist,
1038 to create a new zero-length file.
1039
1040 This function returns 0 on success or -1 on error.
1041
1042 =head2 guestfs_tune2fs_l
1043
1044  char **guestfs_tune2fs_l (guestfs_h *handle,
1045                 const char *device);
1046
1047 This returns the contents of the ext2 or ext3 filesystem superblock
1048 on C<device>.
1049
1050 It is the same as running C<tune2fs -l device>.  See L<tune2fs(8)>
1051 manpage for more details.  The list of fields returned isn't
1052 clearly defined, and depends on both the version of C<tune2fs>
1053 that libguestfs was built against, and the filesystem itself.
1054
1055 This function returns a NULL-terminated array of
1056 strings, or NULL if there was an error.
1057 The array of strings will always have length C<2n+1>, where
1058 C<n> keys and values alternate, followed by the trailing NULL entry.
1059 I<The caller must free the strings and the array after use>.
1060
1061 =head2 guestfs_umount
1062
1063  int guestfs_umount (guestfs_h *handle,
1064                 const char *pathordevice);
1065
1066 This unmounts the given filesystem.  The filesystem may be
1067 specified either by its mountpoint (path) or the device which
1068 contains the filesystem.
1069
1070 This function returns 0 on success or -1 on error.
1071
1072 =head2 guestfs_umount_all
1073
1074  int guestfs_umount_all (guestfs_h *handle);
1075
1076 This unmounts all mounted filesystems.
1077
1078 Some internal mounts are not unmounted by this call.
1079
1080 This function returns 0 on success or -1 on error.
1081
1082 =head2 guestfs_vgcreate
1083
1084  int guestfs_vgcreate (guestfs_h *handle,
1085                 const char *volgroup,
1086                 char * const* const physvols);
1087
1088 This creates an LVM volume group called C<volgroup>
1089 from the non-empty list of physical volumes C<physvols>.
1090
1091 This function returns 0 on success or -1 on error.
1092
1093 =head2 guestfs_vgs
1094
1095  char **guestfs_vgs (guestfs_h *handle);
1096
1097 List all the volumes groups detected.  This is the equivalent
1098 of the L<vgs(8)> command.
1099
1100 This returns a list of just the volume group names that were
1101 detected (eg. C<VolGroup00>).
1102
1103 See also C<guestfs_vgs_full>.
1104
1105 This function returns a NULL-terminated array of strings
1106 (like L<environ(3)>), or NULL if there was an error.
1107 I<The caller must free the strings and the array after use>.
1108
1109 =head2 guestfs_vgs_full
1110
1111  struct guestfs_lvm_vg_list *guestfs_vgs_full (guestfs_h *handle);
1112
1113 List all the volumes groups detected.  This is the equivalent
1114 of the L<vgs(8)> command.  The "full" version includes all fields.
1115
1116 This function returns a C<struct guestfs_lvm_vg_list *>
1117 (see E<lt>guestfs-structs.hE<gt>),
1118 or NULL if there was an error.
1119 I<The caller must call C<guestfs_free_lvm_vg_list> after use>.
1120
1121 =head2 guestfs_wait_ready
1122
1123  int guestfs_wait_ready (guestfs_h *handle);
1124
1125 Internally libguestfs is implemented by running a virtual machine
1126 using L<qemu(1)>.
1127
1128 You should call this after C<guestfs_launch> to wait for the launch
1129 to complete.
1130
1131 This function returns 0 on success or -1 on error.
1132
1133 =head2 guestfs_write_file
1134
1135  int guestfs_write_file (guestfs_h *handle,
1136                 const char *path,
1137                 const char *content,
1138                 int size);
1139
1140 This call creates a file called C<path>.  The contents of the
1141 file is the string C<content> (which can contain any 8 bit data),
1142 with length C<size>.
1143
1144 As a special case, if C<size> is C<0>
1145 then the length is calculated using C<strlen> (so in this case
1146 the content cannot contain embedded ASCII NULs).
1147
1148 This function returns 0 on success or -1 on error.
1149
1150 Because of the message protocol, there is a transfer limit
1151 of somewhere between 2MB and 4MB.  To transfer large files you should use
1152 FTP.
1153