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_checksum
 392
 393  char *guestfs_checksum (guestfs_h *handle,
 394                 const char *csumtype,
 395                 const char *path);
 396
 397 This call computes the MD5, SHAx or CRC checksum of the
 398 file named C<path>.
 399
 400 The type of checksum to compute is given by the C<csumtype>
 401 parameter which must have one of the following values:
 402
 403 =over 4
 404
 405 =item C<crc>
 406
 407 Compute the cyclic redundancy check (CRC) specified by POSIX
 408 for the C<cksum> command.
 409
 410 =item C<md5>
 411
 412 Compute the MD5 hash (using the C<md5sum> program).
 413
 414 =item C<sha1>
 415
 416 Compute the SHA1 hash (using the C<sha1sum> program).
 417
 418 =item C<sha224>
 419
 420 Compute the SHA224 hash (using the C<sha224sum> program).
 421
 422 =item C<sha256>
 423
 424 Compute the SHA256 hash (using the C<sha256sum> program).
 425
 426 =item C<sha384>
 427
 428 Compute the SHA384 hash (using the C<sha384sum> program).
 429
 430 =item C<sha512>
 431
 432 Compute the SHA512 hash (using the C<sha512sum> program).
 433
 434 =back
 435
 436 The checksum is returned as a printable string.
 437
 438 This function returns a string, or NULL on error.
 439 I<The caller must free the returned string after use>.
 440
 441 =head2 guestfs_chmod
 442
 443  int guestfs_chmod (guestfs_h *handle,
 444                 int mode,
 445                 const char *path);
 446
 447 Change the mode (permissions) of C<path> to C<mode>.  Only
 448 numeric modes are supported.
 449
 450 This function returns 0 on success or -1 on error.
 451
 452 =head2 guestfs_chown
 453
 454  int guestfs_chown (guestfs_h *handle,
 455                 int owner,
 456                 int group,
 457                 const char *path);
 458
 459 Change the file owner to C<owner> and group to C<group>.
 460
 461 Only numeric uid and gid are supported.  If you want to use
 462 names, you will need to locate and parse the password file
 463 yourself (Augeas support makes this relatively easy).
 464
 465 This function returns 0 on success or -1 on error.
 466
 467 =head2 guestfs_command
 468
 469  char *guestfs_command (guestfs_h *handle,
 470                 char * const* const arguments);
 471
 472 This call runs a command from the guest filesystem.  The
 473 filesystem must be mounted, and must contain a compatible
 474 operating system (ie. something Linux, with the same
 475 or compatible processor architecture).
 476
 477 The single parameter is an argv-style list of arguments.
 478 The first element is the name of the program to run.
 479 Subsequent elements are parameters.  The list must be
 480 non-empty (ie. must contain a program name).
 481
 482 The C<$PATH> environment variable will contain at least
 483 C</usr/bin> and C</bin>.  If you require a program from
 484 another location, you should provide the full path in the
 485 first parameter.
 486
 487 Shared libraries and data files required by the program
 488 must be available on filesystems which are mounted in the
 489 correct places.  It is the caller's responsibility to ensure
 490 all filesystems that are needed are mounted at the right
 491 locations.
 492
 493 This function returns a string, or NULL on error.
 494 I<The caller must free the returned string after use>.
 495
 496 =head2 guestfs_command_lines
 497
 498  char **guestfs_command_lines (guestfs_h *handle,
 499                 char * const* const arguments);
 500
 501 This is the same as C<guestfs_command>, but splits the
 502 result into a list of lines.
 503
 504 This function returns a NULL-terminated array of strings
 505 (like L<environ(3)>), or NULL if there was an error.
 506 I<The caller must free the strings and the array after use>.
 507
 508 =head2 guestfs_config
 509
 510  int guestfs_config (guestfs_h *handle,
 511                 const char *qemuparam,
 512                 const char *qemuvalue);
 513
 514 This can be used to add arbitrary qemu command line parameters
 515 of the form C<-param value>.  Actually it's not quite arbitrary - we
 516 prevent you from setting some parameters which would interfere with
 517 parameters that we use.
 518
 519 The first character of C<param> string must be a C<-> (dash).
 520
 521 C<value> can be NULL.
 522
 523 This function returns 0 on success or -1 on error.
 524
 525 =head2 guestfs_debug
 526
 527  char *guestfs_debug (guestfs_h *handle,
 528                 const char *subcmd,
 529                 char * const* const extraargs);
 530
 531 The C<guestfs_debug> command exposes some internals of
 532 C<guestfsd> (the guestfs daemon) that runs inside the
 533 qemu subprocess.
 534
 535 There is no comprehensive help for this command.  You have
 536 to look at the file C<daemon/debug.c> in the libguestfs source
 537 to find out what you can do.
 538
 539 This function returns a string, or NULL on error.
 540 I<The caller must free the returned string after use>.
 541
 542 =head2 guestfs_download
 543
 544  int guestfs_download (guestfs_h *handle,
 545                 const char *remotefilename,
 546                 const char *filename);
 547
 548 Download file C<remotefilename> and save it as C<filename>
 549 on the local machine.
 550
 551 C<filename> can also be a named pipe.
 552
 553 See also C<guestfs_upload>, C<guestfs_cat>.
 554
 555 This function returns 0 on success or -1 on error.
 556
 557 =head2 guestfs_exists
 558
 559  int guestfs_exists (guestfs_h *handle,
 560                 const char *path);
 561
 562 This returns C<true> if and only if there is a file, directory
 563 (or anything) with the given C<path> name.
 564
 565 See also C<guestfs_is_file>, C<guestfs_is_dir>, C<guestfs_stat>.
 566
 567 This function returns a C truth value on success or -1 on error.
 568
 569 =head2 guestfs_file
 570
 571  char *guestfs_file (guestfs_h *handle,
 572                 const char *path);
 573
 574 This call uses the standard L<file(1)> command to determine
 575 the type or contents of the file.  This also works on devices,
 576 for example to find out whether a partition contains a filesystem.
 577
 578 The exact command which runs is C<file -bsL path>.  Note in
 579 particular that the filename is not prepended to the output
 580 (the C<-b> option).
 581
 582 This function returns a string, or NULL on error.
 583 I<The caller must free the returned string after use>.
 584
 585 =head2 guestfs_fsck
 586
 587  int guestfs_fsck (guestfs_h *handle,
 588                 const char *fstype,
 589                 const char *device);
 590
 591 This runs the filesystem checker (fsck) on C<device> which
 592 should have filesystem type C<fstype>.
 593
 594 The returned integer is the status.  See L<fsck(8)> for the
 595 list of status codes from C<fsck>, and note that multiple
 596 status codes can be summed together.
 597
 598 It is entirely equivalent to running C<fsck -a -t fstype device>.
 599 Note that checking or repairing NTFS volumes is not supported
 600 (by linux-ntfs).
 601
 602 On error this function returns -1.
 603
 604 =head2 guestfs_get_autosync
 605
 606  int guestfs_get_autosync (guestfs_h *handle);
 607
 608 Get the autosync flag.
 609
 610 This function returns a C truth value on success or -1 on error.
 611
 612 =head2 guestfs_get_e2label
 613
 614  char *guestfs_get_e2label (guestfs_h *handle,
 615                 const char *device);
 616
 617 This returns the ext2/3/4 filesystem label of the filesystem on
 618 C<device>.
 619
 620 This function returns a string, or NULL on error.
 621 I<The caller must free the returned string after use>.
 622
 623 =head2 guestfs_get_e2uuid
 624
 625  char *guestfs_get_e2uuid (guestfs_h *handle,
 626                 const char *device);
 627
 628 This returns the ext2/3/4 filesystem UUID of the filesystem on
 629 C<device>.
 630
 631 This function returns a string, or NULL on error.
 632 I<The caller must free the returned string after use>.
 633
 634 =head2 guestfs_get_path
 635
 636  const char *guestfs_get_path (guestfs_h *handle);
 637
 638 Return the current search path.
 639
 640 This is always non-NULL.  If it wasn't set already, then this will
 641 return the default path.
 642
 643 This function returns a string, or NULL on error.
 644 The string is owned by the guest handle and must I<not> be freed.
 645
 646 =head2 guestfs_get_qemu
 647
 648  const char *guestfs_get_qemu (guestfs_h *handle);
 649
 650 Return the current qemu binary.
 651
 652 This is always non-NULL.  If it wasn't set already, then this will
 653 return the default qemu binary name.
 654
 655 This function returns a string, or NULL on error.
 656 The string is owned by the guest handle and must I<not> be freed.
 657
 658 =head2 guestfs_get_state
 659
 660  int guestfs_get_state (guestfs_h *handle);
 661
 662 This returns the current state as an opaque integer.  This is
 663 only useful for printing debug and internal error messages.
 664
 665 For more information on states, see L<guestfs(3)>.
 666
 667 On error this function returns -1.
 668
 669 =head2 guestfs_get_verbose
 670
 671  int guestfs_get_verbose (guestfs_h *handle);
 672
 673 This returns the verbose messages flag.
 674
 675 This function returns a C truth value on success or -1 on error.
 676
 677 =head2 guestfs_is_busy
 678
 679  int guestfs_is_busy (guestfs_h *handle);
 680
 681 This returns true iff this handle is busy processing a command
 682 (in the C<BUSY> state).
 683
 684 For more information on states, see L<guestfs(3)>.
 685
 686 This function returns a C truth value on success or -1 on error.
 687
 688 =head2 guestfs_is_config
 689
 690  int guestfs_is_config (guestfs_h *handle);
 691
 692 This returns true iff this handle is being configured
 693 (in the C<CONFIG> state).
 694
 695 For more information on states, see L<guestfs(3)>.
 696
 697 This function returns a C truth value on success or -1 on error.
 698
 699 =head2 guestfs_is_dir
 700
 701  int guestfs_is_dir (guestfs_h *handle,
 702                 const char *path);
 703
 704 This returns C<true> if and only if there is a directory
 705 with the given C<path> name.  Note that it returns false for
 706 other objects like files.
 707
 708 See also C<guestfs_stat>.
 709
 710 This function returns a C truth value on success or -1 on error.
 711
 712 =head2 guestfs_is_file
 713
 714  int guestfs_is_file (guestfs_h *handle,
 715                 const char *path);
 716
 717 This returns C<true> if and only if there is a file
 718 with the given C<path> name.  Note that it returns false for
 719 other objects like directories.
 720
 721 See also C<guestfs_stat>.
 722
 723 This function returns a C truth value on success or -1 on error.
 724
 725 =head2 guestfs_is_launching
 726
 727  int guestfs_is_launching (guestfs_h *handle);
 728
 729 This returns true iff this handle is launching the subprocess
 730 (in the C<LAUNCHING> state).
 731
 732 For more information on states, see L<guestfs(3)>.
 733
 734 This function returns a C truth value on success or -1 on error.
 735
 736 =head2 guestfs_is_ready
 737
 738  int guestfs_is_ready (guestfs_h *handle);
 739
 740 This returns true iff this handle is ready to accept commands
 741 (in the C<READY> state).
 742
 743 For more information on states, see L<guestfs(3)>.
 744
 745 This function returns a C truth value on success or -1 on error.
 746
 747 =head2 guestfs_kill_subprocess
 748
 749  int guestfs_kill_subprocess (guestfs_h *handle);
 750
 751 This kills the qemu subprocess.  You should never need to call this.
 752
 753 This function returns 0 on success or -1 on error.
 754
 755 =head2 guestfs_launch
 756
 757  int guestfs_launch (guestfs_h *handle);
 758
 759 Internally libguestfs is implemented by running a virtual machine
 760 using L<qemu(1)>.
 761
 762 You should call this after configuring the handle
 763 (eg. adding drives) but before performing any actions.
 764
 765 This function returns 0 on success or -1 on error.
 766
 767 =head2 guestfs_list_devices
 768
 769  char **guestfs_list_devices (guestfs_h *handle);
 770
 771 List all the block devices.
 772
 773 The full block device names are returned, eg. C</dev/sda>
 774
 775 This function returns a NULL-terminated array of strings
 776 (like L<environ(3)>), or NULL if there was an error.
 777 I<The caller must free the strings and the array after use>.
 778
 779 =head2 guestfs_list_partitions
 780
 781  char **guestfs_list_partitions (guestfs_h *handle);
 782
 783 List all the partitions detected on all block devices.
 784
 785 The full partition device names are returned, eg. C</dev/sda1>
 786
 787 This does not return logical volumes.  For that you will need to
 788 call C<guestfs_lvs>.
 789
 790 This function returns a NULL-terminated array of strings
 791 (like L<environ(3)>), or NULL if there was an error.
 792 I<The caller must free the strings and the array after use>.
 793
 794 =head2 guestfs_ll
 795
 796  char *guestfs_ll (guestfs_h *handle,
 797                 const char *directory);
 798
 799 List the files in C<directory> (relative to the root directory,
 800 there is no cwd) in the format of 'ls -la'.
 801
 802 This command is mostly useful for interactive sessions.  It
 803 is I<not> intended that you try to parse the output string.
 804
 805 This function returns a string, or NULL on error.
 806 I<The caller must free the returned string after use>.
 807
 808 =head2 guestfs_ls
 809
 810  char **guestfs_ls (guestfs_h *handle,
 811                 const char *directory);
 812
 813 List the files in C<directory> (relative to the root directory,
 814 there is no cwd).  The '.' and '..' entries are not returned, but
 815 hidden files are shown.
 816
 817 This command is mostly useful for interactive sessions.  Programs
 818 should probably use C<guestfs_readdir> instead.
 819
 820 This function returns a NULL-terminated array of strings
 821 (like L<environ(3)>), or NULL if there was an error.
 822 I<The caller must free the strings and the array after use>.
 823
 824 =head2 guestfs_lstat
 825
 826  struct guestfs_stat *guestfs_lstat (guestfs_h *handle,
 827                 const char *path);
 828
 829 Returns file information for the given C<path>.
 830
 831 This is the same as C<guestfs_stat> except that if C<path>
 832 is a symbolic link, then the link is stat-ed, not the file it
 833 refers to.
 834
 835 This is the same as the C<lstat(2)> system call.
 836
 837 This function returns a C<struct guestfs_stat *>
 838 (see L<stat(2)> and E<lt>guestfs-structs.hE<gt>),
 839 or NULL if there was an error.
 840 I<The caller must call C<free> after use>.
 841
 842 =head2 guestfs_lvcreate
 843
 844  int guestfs_lvcreate (guestfs_h *handle,
 845                 const char *logvol,
 846                 const char *volgroup,
 847                 int mbytes);
 848
 849 This creates an LVM volume group called C<logvol>
 850 on the volume group C<volgroup>, with C<size> megabytes.
 851
 852 This function returns 0 on success or -1 on error.
 853
 854 =head2 guestfs_lvm_remove_all
 855
 856  int guestfs_lvm_remove_all (guestfs_h *handle);
 857
 858 This command removes all LVM logical volumes, volume groups
 859 and physical volumes.
 860
 861 This function returns 0 on success or -1 on error.
 862
 863 B<This command is dangerous.  Without careful use you
 864 can easily destroy all your data>.
 865
 866 =head2 guestfs_lvremove
 867
 868  int guestfs_lvremove (guestfs_h *handle,
 869                 const char *device);
 870
 871 Remove an LVM logical volume C<device>, where C<device> is
 872 the path to the LV, such as C</dev/VG/LV>.
 873
 874 You can also remove all LVs in a volume group by specifying
 875 the VG name, C</dev/VG>.
 876
 877 This function returns 0 on success or -1 on error.
 878
 879 =head2 guestfs_lvs
 880
 881  char **guestfs_lvs (guestfs_h *handle);
 882
 883 List all the logical volumes detected.  This is the equivalent
 884 of the L<lvs(8)> command.
 885
 886 This returns a list of the logical volume device names
 887 (eg. C</dev/VolGroup00/LogVol00>).
 888
 889 See also C<guestfs_lvs_full>.
 890
 891 This function returns a NULL-terminated array of strings
 892 (like L<environ(3)>), or NULL if there was an error.
 893 I<The caller must free the strings and the array after use>.
 894
 895 =head2 guestfs_lvs_full
 896
 897  struct guestfs_lvm_lv_list *guestfs_lvs_full (guestfs_h *handle);
 898
 899 List all the logical volumes detected.  This is the equivalent
 900 of the L<lvs(8)> command.  The "full" version includes all fields.
 901
 902 This function returns a C<struct guestfs_lvm_lv_list *>
 903 (see E<lt>guestfs-structs.hE<gt>),
 904 or NULL if there was an error.
 905 I<The caller must call C<guestfs_free_lvm_lv_list> after use>.
 906
 907 =head2 guestfs_mkdir
 908
 909  int guestfs_mkdir (guestfs_h *handle,
 910                 const char *path);
 911
 912 Create a directory named C<path>.
 913
 914 This function returns 0 on success or -1 on error.
 915
 916 =head2 guestfs_mkdir_p
 917
 918  int guestfs_mkdir_p (guestfs_h *handle,
 919                 const char *path);
 920
 921 Create a directory named C<path>, creating any parent directories
 922 as necessary.  This is like the C<mkdir -p> shell command.
 923
 924 This function returns 0 on success or -1 on error.
 925
 926 =head2 guestfs_mkfs
 927
 928  int guestfs_mkfs (guestfs_h *handle,
 929                 const char *fstype,
 930                 const char *device);
 931
 932 This creates a filesystem on C<device> (usually a partition
 933 of LVM logical volume).  The filesystem type is C<fstype>, for
 934 example C<ext3>.
 935
 936 This function returns 0 on success or -1 on error.
 937
 938 =head2 guestfs_mount
 939
 940  int guestfs_mount (guestfs_h *handle,
 941                 const char *device,
 942                 const char *mountpoint);
 943
 944 Mount a guest disk at a position in the filesystem.  Block devices
 945 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
 946 the guest.  If those block devices contain partitions, they will have
 947 the usual names (eg. C</dev/sda1>).  Also LVM C</dev/VG/LV>-style
 948 names can be used.
 949
 950 The rules are the same as for L<mount(2)>:  A filesystem must
 951 first be mounted on C</> before others can be mounted.  Other
 952 filesystems can only be mounted on directories which already
 953 exist.
 954
 955 The mounted filesystem is writable, if we have sufficient permissions
 956 on the underlying device.
 957
 958 The filesystem options C<sync> and C<noatime> are set with this
 959 call, in order to improve reliability.
 960
 961 This function returns 0 on success or -1 on error.
 962
 963 =head2 guestfs_mount_options
 964
 965  int guestfs_mount_options (guestfs_h *handle,
 966                 const char *options,
 967                 const char *device,
 968                 const char *mountpoint);
 969
 970 This is the same as the C<guestfs_mount> command, but it
 971 allows you to set the mount options as for the
 972 L<mount(8)> I<-o> flag.
 973
 974 This function returns 0 on success or -1 on error.
 975
 976 =head2 guestfs_mount_ro
 977
 978  int guestfs_mount_ro (guestfs_h *handle,
 979                 const char *device,
 980                 const char *mountpoint);
 981
 982 This is the same as the C<guestfs_mount> command, but it
 983 mounts the filesystem with the read-only (I<-o ro>) flag.
 984
 985 This function returns 0 on success or -1 on error.
 986
 987 =head2 guestfs_mount_vfs
 988
 989  int guestfs_mount_vfs (guestfs_h *handle,
 990                 const char *options,
 991                 const char *vfstype,
 992                 const char *device,
 993                 const char *mountpoint);
 994
 995 This is the same as the C<guestfs_mount> command, but it
 996 allows you to set both the mount options and the vfstype
 997 as for the L<mount(8)> I<-o> and I<-t> flags.
 998
 999 This function returns 0 on success or -1 on error.
1000
1001 =head2 guestfs_mounts
1002
1003  char **guestfs_mounts (guestfs_h *handle);
1004
1005 This returns the list of currently mounted filesystems.  It returns
1006 the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
1007
1008 Some internal mounts are not shown.
1009
1010 This function returns a NULL-terminated array of strings
1011 (like L<environ(3)>), or NULL if there was an error.
1012 I<The caller must free the strings and the array after use>.
1013
1014 =head2 guestfs_pvcreate
1015
1016  int guestfs_pvcreate (guestfs_h *handle,
1017                 const char *device);
1018
1019 This creates an LVM physical volume on the named C<device>,
1020 where C<device> should usually be a partition name such
1021 as C</dev/sda1>.
1022
1023 This function returns 0 on success or -1 on error.
1024
1025 =head2 guestfs_pvremove
1026
1027  int guestfs_pvremove (guestfs_h *handle,
1028                 const char *device);
1029
1030 This wipes a physical volume C<device> so that LVM will no longer
1031 recognise it.
1032
1033 The implementation uses the C<pvremove> command which refuses to
1034 wipe physical volumes that contain any volume groups, so you have
1035 to remove those first.
1036
1037 This function returns 0 on success or -1 on error.
1038
1039 =head2 guestfs_pvs
1040
1041  char **guestfs_pvs (guestfs_h *handle);
1042
1043 List all the physical volumes detected.  This is the equivalent
1044 of the L<pvs(8)> command.
1045
1046 This returns a list of just the device names that contain
1047 PVs (eg. C</dev/sda2>).
1048
1049 See also C<guestfs_pvs_full>.
1050
1051 This function returns a NULL-terminated array of strings
1052 (like L<environ(3)>), or NULL if there was an error.
1053 I<The caller must free the strings and the array after use>.
1054
1055 =head2 guestfs_pvs_full
1056
1057  struct guestfs_lvm_pv_list *guestfs_pvs_full (guestfs_h *handle);
1058
1059 List all the physical volumes detected.  This is the equivalent
1060 of the L<pvs(8)> command.  The "full" version includes all fields.
1061
1062 This function returns a C<struct guestfs_lvm_pv_list *>
1063 (see E<lt>guestfs-structs.hE<gt>),
1064 or NULL if there was an error.
1065 I<The caller must call C<guestfs_free_lvm_pv_list> after use>.
1066
1067 =head2 guestfs_read_lines
1068
1069  char **guestfs_read_lines (guestfs_h *handle,
1070                 const char *path);
1071
1072 Return the contents of the file named C<path>.
1073
1074 The file contents are returned as a list of lines.  Trailing
1075 C<LF> and C<CRLF> character sequences are I<not> returned.
1076
1077 Note that this function cannot correctly handle binary files
1078 (specifically, files containing C<\0> character which is treated
1079 as end of line).  For those you need to use the C<guestfs_read_file>
1080 function which has a more complex interface.
1081
1082 This function returns a NULL-terminated array of strings
1083 (like L<environ(3)>), or NULL if there was an error.
1084 I<The caller must free the strings and the array after use>.
1085
1086 =head2 guestfs_rm
1087
1088  int guestfs_rm (guestfs_h *handle,
1089                 const char *path);
1090
1091 Remove the single file C<path>.
1092
1093 This function returns 0 on success or -1 on error.
1094
1095 =head2 guestfs_rm_rf
1096
1097  int guestfs_rm_rf (guestfs_h *handle,
1098                 const char *path);
1099
1100 Remove the file or directory C<path>, recursively removing the
1101 contents if its a directory.  This is like the C<rm -rf> shell
1102 command.
1103
1104 This function returns 0 on success or -1 on error.
1105
1106 =head2 guestfs_rmdir
1107
1108  int guestfs_rmdir (guestfs_h *handle,
1109                 const char *path);
1110
1111 Remove the single directory C<path>.
1112
1113 This function returns 0 on success or -1 on error.
1114
1115 =head2 guestfs_set_autosync
1116
1117  int guestfs_set_autosync (guestfs_h *handle,
1118                 int autosync);
1119
1120 If C<autosync> is true, this enables autosync.  Libguestfs will make a
1121 best effort attempt to run C<guestfs_umount_all> followed by
1122 C<guestfs_sync> when the handle is closed
1123 (also if the program exits without closing handles).
1124
1125 This is disabled by default (except in guestfish where it is
1126 enabled by default).
1127
1128 This function returns 0 on success or -1 on error.
1129
1130 =head2 guestfs_set_busy
1131
1132  int guestfs_set_busy (guestfs_h *handle);
1133
1134 This sets the state to C<BUSY>.  This is only used when implementing
1135 actions using the low-level API.
1136
1137 For more information on states, see L<guestfs(3)>.
1138
1139 This function returns 0 on success or -1 on error.
1140
1141 =head2 guestfs_set_e2label
1142
1143  int guestfs_set_e2label (guestfs_h *handle,
1144                 const char *device,
1145                 const char *label);
1146
1147 This sets the ext2/3/4 filesystem label of the filesystem on
1148 C<device> to C<label>.  Filesystem labels are limited to
1149 16 characters.
1150
1151 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2label>
1152 to return the existing label on a filesystem.
1153
1154 This function returns 0 on success or -1 on error.
1155
1156 =head2 guestfs_set_e2uuid
1157
1158  int guestfs_set_e2uuid (guestfs_h *handle,
1159                 const char *device,
1160                 const char *uuid);
1161
1162 This sets the ext2/3/4 filesystem UUID of the filesystem on
1163 C<device> to C<uuid>.  The format of the UUID and alternatives
1164 such as C<clear>, C<random> and C<time> are described in the
1165 L<tune2fs(8)> manpage.
1166
1167 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2uuid>
1168 to return the existing UUID of a filesystem.
1169
1170 This function returns 0 on success or -1 on error.
1171
1172 =head2 guestfs_set_path
1173
1174  int guestfs_set_path (guestfs_h *handle,
1175                 const char *path);
1176
1177 Set the path that libguestfs searches for kernel and initrd.img.
1178
1179 The default is C<$libdir/guestfs> unless overridden by setting
1180 C<LIBGUESTFS_PATH> environment variable.
1181
1182 The string C<path> is stashed in the libguestfs handle, so the caller
1183 must make sure it remains valid for the lifetime of the handle.
1184
1185 Setting C<path> to C<NULL> restores the default path.
1186
1187 This function returns 0 on success or -1 on error.
1188
1189 =head2 guestfs_set_qemu
1190
1191  int guestfs_set_qemu (guestfs_h *handle,
1192                 const char *qemu);
1193
1194 Set the qemu binary that we will use.
1195
1196 The default is chosen when the library was compiled by the
1197 configure script.
1198
1199 You can also override this by setting the C<LIBGUESTFS_QEMU>
1200 environment variable.
1201
1202 The string C<qemu> is stashed in the libguestfs handle, so the caller
1203 must make sure it remains valid for the lifetime of the handle.
1204
1205 Setting C<qemu> to C<NULL> restores the default qemu binary.
1206
1207 This function returns 0 on success or -1 on error.
1208
1209 =head2 guestfs_set_ready
1210
1211  int guestfs_set_ready (guestfs_h *handle);
1212
1213 This sets the state to C<READY>.  This is only used when implementing
1214 actions using the low-level API.
1215
1216 For more information on states, see L<guestfs(3)>.
1217
1218 This function returns 0 on success or -1 on error.
1219
1220 =head2 guestfs_set_verbose
1221
1222  int guestfs_set_verbose (guestfs_h *handle,
1223                 int verbose);
1224
1225 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
1226
1227 Verbose messages are disabled unless the environment variable
1228 C<LIBGUESTFS_DEBUG> is defined and set to C<1>.
1229
1230 This function returns 0 on success or -1 on error.
1231
1232 =head2 guestfs_sfdisk
1233
1234  int guestfs_sfdisk (guestfs_h *handle,
1235                 const char *device,
1236                 int cyls,
1237                 int heads,
1238                 int sectors,
1239                 char * const* const lines);
1240
1241 This is a direct interface to the L<sfdisk(8)> program for creating
1242 partitions on block devices.
1243
1244 C<device> should be a block device, for example C</dev/sda>.
1245
1246 C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads
1247 and sectors on the device, which are passed directly to sfdisk as
1248 the I<-C>, I<-H> and I<-S> parameters.  If you pass C<0> for any
1249 of these, then the corresponding parameter is omitted.  Usually for
1250 'large' disks, you can just pass C<0> for these, but for small
1251 (floppy-sized) disks, sfdisk (or rather, the kernel) cannot work
1252 out the right geometry and you will need to tell it.
1253
1254 C<lines> is a list of lines that we feed to C<sfdisk>.  For more
1255 information refer to the L<sfdisk(8)> manpage.
1256
1257 To create a single partition occupying the whole disk, you would
1258 pass C<lines> as a single element list, when the single element being
1259 the string C<,> (comma).
1260
1261 This function returns 0 on success or -1 on error.
1262
1263 B<This command is dangerous.  Without careful use you
1264 can easily destroy all your data>.
1265
1266 =head2 guestfs_stat
1267
1268  struct guestfs_stat *guestfs_stat (guestfs_h *handle,
1269                 const char *path);
1270
1271 Returns file information for the given C<path>.
1272
1273 This is the same as the C<stat(2)> system call.
1274
1275 This function returns a C<struct guestfs_stat *>
1276 (see L<stat(2)> and E<lt>guestfs-structs.hE<gt>),
1277 or NULL if there was an error.
1278 I<The caller must call C<free> after use>.
1279
1280 =head2 guestfs_statvfs
1281
1282  struct guestfs_statvfs *guestfs_statvfs (guestfs_h *handle,
1283                 const char *path);
1284
1285 Returns file system statistics for any mounted file system.
1286 C<path> should be a file or directory in the mounted file system
1287 (typically it is the mount point itself, but it doesn't need to be).
1288
1289 This is the same as the C<statvfs(2)> system call.
1290
1291 This function returns a C<struct guestfs_statvfs *>
1292 (see L<statvfs(2)> and E<lt>guestfs-structs.hE<gt>),
1293 or NULL if there was an error.
1294 I<The caller must call C<free> after use>.
1295
1296 =head2 guestfs_sync
1297
1298  int guestfs_sync (guestfs_h *handle);
1299
1300 This syncs the disk, so that any writes are flushed through to the
1301 underlying disk image.
1302
1303 You should always call this if you have modified a disk image, before
1304 closing the handle.
1305
1306 This function returns 0 on success or -1 on error.
1307
1308 =head2 guestfs_tar_in
1309
1310  int guestfs_tar_in (guestfs_h *handle,
1311                 const char *tarfile,
1312                 const char *directory);
1313
1314 This command uploads and unpacks local file C<tarfile> (an
1315 I<uncompressed> tar file) into C<directory>.
1316
1317 To upload a compressed tarball, use C<guestfs_tgz_in>.
1318
1319 This function returns 0 on success or -1 on error.
1320
1321 =head2 guestfs_tar_out
1322
1323  int guestfs_tar_out (guestfs_h *handle,
1324                 const char *directory,
1325                 const char *tarfile);
1326
1327 This command packs the contents of C<directory> and downloads
1328 it to local file C<tarfile>.
1329
1330 To download a compressed tarball, use C<guestfs_tgz_out>.
1331
1332 This function returns 0 on success or -1 on error.
1333
1334 =head2 guestfs_tgz_in
1335
1336  int guestfs_tgz_in (guestfs_h *handle,
1337                 const char *tarball,
1338                 const char *directory);
1339
1340 This command uploads and unpacks local file C<tarball> (a
1341 I<gzip compressed> tar file) into C<directory>.
1342
1343 To upload an uncompressed tarball, use C<guestfs_tar_in>.
1344
1345 This function returns 0 on success or -1 on error.
1346
1347 =head2 guestfs_tgz_out
1348
1349  int guestfs_tgz_out (guestfs_h *handle,
1350                 const char *directory,
1351                 const char *tarball);
1352
1353 This command packs the contents of C<directory> and downloads
1354 it to local file C<tarball>.
1355
1356 To download an uncompressed tarball, use C<guestfs_tar_out>.
1357
1358 This function returns 0 on success or -1 on error.
1359
1360 =head2 guestfs_touch
1361
1362  int guestfs_touch (guestfs_h *handle,
1363                 const char *path);
1364
1365 Touch acts like the L<touch(1)> command.  It can be used to
1366 update the timestamps on a file, or, if the file does not exist,
1367 to create a new zero-length file.
1368
1369 This function returns 0 on success or -1 on error.
1370
1371 =head2 guestfs_tune2fs_l
1372
1373  char **guestfs_tune2fs_l (guestfs_h *handle,
1374                 const char *device);
1375
1376 This returns the contents of the ext2, ext3 or ext4 filesystem
1377 superblock on C<device>.
1378
1379 It is the same as running C<tune2fs -l device>.  See L<tune2fs(8)>
1380 manpage for more details.  The list of fields returned isn't
1381 clearly defined, and depends on both the version of C<tune2fs>
1382 that libguestfs was built against, and the filesystem itself.
1383
1384 This function returns a NULL-terminated array of
1385 strings, or NULL if there was an error.
1386 The array of strings will always have length C<2n+1>, where
1387 C<n> keys and values alternate, followed by the trailing NULL entry.
1388 I<The caller must free the strings and the array after use>.
1389
1390 =head2 guestfs_umount
1391
1392  int guestfs_umount (guestfs_h *handle,
1393                 const char *pathordevice);
1394
1395 This unmounts the given filesystem.  The filesystem may be
1396 specified either by its mountpoint (path) or the device which
1397 contains the filesystem.
1398
1399 This function returns 0 on success or -1 on error.
1400
1401 =head2 guestfs_umount_all
1402
1403  int guestfs_umount_all (guestfs_h *handle);
1404
1405 This unmounts all mounted filesystems.
1406
1407 Some internal mounts are not unmounted by this call.
1408
1409 This function returns 0 on success or -1 on error.
1410
1411 =head2 guestfs_upload
1412
1413  int guestfs_upload (guestfs_h *handle,
1414                 const char *filename,
1415                 const char *remotefilename);
1416
1417 Upload local file C<filename> to C<remotefilename> on the
1418 filesystem.
1419
1420 C<filename> can also be a named pipe.
1421
1422 See also C<guestfs_download>.
1423
1424 This function returns 0 on success or -1 on error.
1425
1426 =head2 guestfs_vgcreate
1427
1428  int guestfs_vgcreate (guestfs_h *handle,
1429                 const char *volgroup,
1430                 char * const* const physvols);
1431
1432 This creates an LVM volume group called C<volgroup>
1433 from the non-empty list of physical volumes C<physvols>.
1434
1435 This function returns 0 on success or -1 on error.
1436
1437 =head2 guestfs_vgremove
1438
1439  int guestfs_vgremove (guestfs_h *handle,
1440                 const char *vgname);
1441
1442 Remove an LVM volume group C<vgname>, (for example C<VG>).
1443
1444 This also forcibly removes all logical volumes in the volume
1445 group (if any).
1446
1447 This function returns 0 on success or -1 on error.
1448
1449 =head2 guestfs_vgs
1450
1451  char **guestfs_vgs (guestfs_h *handle);
1452
1453 List all the volumes groups detected.  This is the equivalent
1454 of the L<vgs(8)> command.
1455
1456 This returns a list of just the volume group names that were
1457 detected (eg. C<VolGroup00>).
1458
1459 See also C<guestfs_vgs_full>.
1460
1461 This function returns a NULL-terminated array of strings
1462 (like L<environ(3)>), or NULL if there was an error.
1463 I<The caller must free the strings and the array after use>.
1464
1465 =head2 guestfs_vgs_full
1466
1467  struct guestfs_lvm_vg_list *guestfs_vgs_full (guestfs_h *handle);
1468
1469 List all the volumes groups detected.  This is the equivalent
1470 of the L<vgs(8)> command.  The "full" version includes all fields.
1471
1472 This function returns a C<struct guestfs_lvm_vg_list *>
1473 (see E<lt>guestfs-structs.hE<gt>),
1474 or NULL if there was an error.
1475 I<The caller must call C<guestfs_free_lvm_vg_list> after use>.
1476
1477 =head2 guestfs_wait_ready
1478
1479  int guestfs_wait_ready (guestfs_h *handle);
1480
1481 Internally libguestfs is implemented by running a virtual machine
1482 using L<qemu(1)>.
1483
1484 You should call this after C<guestfs_launch> to wait for the launch
1485 to complete.
1486
1487 This function returns 0 on success or -1 on error.
1488
1489 =head2 guestfs_write_file
1490
1491  int guestfs_write_file (guestfs_h *handle,
1492                 const char *path,
1493                 const char *content,
1494                 int size);
1495
1496 This call creates a file called C<path>.  The contents of the
1497 file is the string C<content> (which can contain any 8 bit data),
1498 with length C<size>.
1499
1500 As a special case, if C<size> is C<0>
1501 then the length is calculated using C<strlen> (so in this case
1502 the content cannot contain embedded ASCII NULs).
1503
1504 This function returns 0 on success or -1 on error.
1505
1506 Because of the message protocol, there is a transfer limit
1507 of somewhere between 2MB and 4MB.  To transfer large files you should use
1508 FTP.
1509
1510 =head2 guestfs_zero
1511
1512  int guestfs_zero (guestfs_h *handle,
1513                 const char *device);
1514
1515 This command writes zeroes over the first few blocks of C<device>.
1516
1517 How many blocks are zeroed isn't specified (but it's I<not> enough
1518 to securely wipe the device).  It should be sufficient to remove
1519 any partition tables, filesystem superblocks and so on.
1520
1521 This function returns 0 on success or -1 on error.
1522