Generated code for lvresize, resize2fs.
[libguestfs.git] / 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 return value is anything printed to I<stdout> by
483 the command.
484
485 If the command returns a non-zero exit status, then
486 this function returns an error message.  The error message
487 string is the content of I<stderr> from the command.
488
489 The C<$PATH> environment variable will contain at least
490 C</usr/bin> and C</bin>.  If you require a program from
491 another location, you should provide the full path in the
492 first parameter.
493
494 Shared libraries and data files required by the program
495 must be available on filesystems which are mounted in the
496 correct places.  It is the caller's responsibility to ensure
497 all filesystems that are needed are mounted at the right
498 locations.
499
500 This function returns a string, or NULL on error.
501 I<The caller must free the returned string after use>.
502
503 Because of the message protocol, there is a transfer limit 
504 of somewhere between 2MB and 4MB.  To transfer large files you should use
505 FTP.
506
507 =head2 guestfs_command_lines
508
509  char **guestfs_command_lines (guestfs_h *handle,
510                 char * const* const arguments);
511
512 This is the same as C<guestfs_command>, but splits the
513 result into a list of lines.
514
515 This function returns a NULL-terminated array of strings
516 (like L<environ(3)>), or NULL if there was an error.
517 I<The caller must free the strings and the array after use>.
518
519 Because of the message protocol, there is a transfer limit 
520 of somewhere between 2MB and 4MB.  To transfer large files you should use
521 FTP.
522
523 =head2 guestfs_config
524
525  int guestfs_config (guestfs_h *handle,
526                 const char *qemuparam,
527                 const char *qemuvalue);
528
529 This can be used to add arbitrary qemu command line parameters
530 of the form C<-param value>.  Actually it's not quite arbitrary - we
531 prevent you from setting some parameters which would interfere with
532 parameters that we use.
533
534 The first character of C<param> string must be a C<-> (dash).
535
536 C<value> can be NULL.
537
538 This function returns 0 on success or -1 on error.
539
540 =head2 guestfs_cp
541
542  int guestfs_cp (guestfs_h *handle,
543                 const char *src,
544                 const char *dest);
545
546 This copies a file from C<src> to C<dest> where C<dest> is
547 either a destination filename or destination directory.
548
549 This function returns 0 on success or -1 on error.
550
551 =head2 guestfs_cp_a
552
553  int guestfs_cp_a (guestfs_h *handle,
554                 const char *src,
555                 const char *dest);
556
557 This copies a file or directory from C<src> to C<dest>
558 recursively using the C<cp -a> command.
559
560 This function returns 0 on success or -1 on error.
561
562 =head2 guestfs_debug
563
564  char *guestfs_debug (guestfs_h *handle,
565                 const char *subcmd,
566                 char * const* const extraargs);
567
568 The C<guestfs_debug> command exposes some internals of
569 C<guestfsd> (the guestfs daemon) that runs inside the
570 qemu subprocess.
571
572 There is no comprehensive help for this command.  You have
573 to look at the file C<daemon/debug.c> in the libguestfs source
574 to find out what you can do.
575
576 This function returns a string, or NULL on error.
577 I<The caller must free the returned string after use>.
578
579 =head2 guestfs_dmesg
580
581  char *guestfs_dmesg (guestfs_h *handle);
582
583 This returns the kernel messages (C<dmesg> output) from
584 the guest kernel.  This is sometimes useful for extended
585 debugging of problems.
586
587 Another way to get the same information is to enable
588 verbose messages with C<guestfs_set_verbose> or by setting
589 the environment variable C<LIBGUESTFS_DEBUG=1> before
590 running the program.
591
592 This function returns a string, or NULL on error.
593 I<The caller must free the returned string after use>.
594
595 =head2 guestfs_download
596
597  int guestfs_download (guestfs_h *handle,
598                 const char *remotefilename,
599                 const char *filename);
600
601 Download file C<remotefilename> and save it as C<filename>
602 on the local machine.
603
604 C<filename> can also be a named pipe.
605
606 See also C<guestfs_upload>, C<guestfs_cat>.
607
608 This function returns 0 on success or -1 on error.
609
610 =head2 guestfs_drop_caches
611
612  int guestfs_drop_caches (guestfs_h *handle,
613                 int whattodrop);
614
615 This instructs the guest kernel to drop its page cache,
616 and/or dentries and inode caches.  The parameter C<whattodrop>
617 tells the kernel what precisely to drop, see
618 L<http://linux-mm.org/Drop_Caches>
619
620 Setting C<whattodrop> to 3 should drop everything.
621
622 This automatically calls L<sync(2)> before the operation,
623 so that the maximum guest memory is freed.
624
625 This function returns 0 on success or -1 on error.
626
627 =head2 guestfs_end_busy
628
629  int guestfs_end_busy (guestfs_h *handle);
630
631 This sets the state to C<READY>, or if in C<CONFIG> then it leaves the
632 state as is.  This is only used when implementing
633 actions using the low-level API.
634
635 For more information on states, see L<guestfs(3)>.
636
637 This function returns 0 on success or -1 on error.
638
639 =head2 guestfs_equal
640
641  int guestfs_equal (guestfs_h *handle,
642                 const char *file1,
643                 const char *file2);
644
645 This compares the two files C<file1> and C<file2> and returns
646 true if their content is exactly equal, or false otherwise.
647
648 The external L<cmp(1)> program is used for the comparison.
649
650 This function returns a C truth value on success or -1 on error.
651
652 =head2 guestfs_exists
653
654  int guestfs_exists (guestfs_h *handle,
655                 const char *path);
656
657 This returns C<true> if and only if there is a file, directory
658 (or anything) with the given C<path> name.
659
660 See also C<guestfs_is_file>, C<guestfs_is_dir>, C<guestfs_stat>.
661
662 This function returns a C truth value on success or -1 on error.
663
664 =head2 guestfs_file
665
666  char *guestfs_file (guestfs_h *handle,
667                 const char *path);
668
669 This call uses the standard L<file(1)> command to determine
670 the type or contents of the file.  This also works on devices,
671 for example to find out whether a partition contains a filesystem.
672
673 The exact command which runs is C<file -bsL path>.  Note in
674 particular that the filename is not prepended to the output
675 (the C<-b> option).
676
677 This function returns a string, or NULL on error.
678 I<The caller must free the returned string after use>.
679
680 =head2 guestfs_fsck
681
682  int guestfs_fsck (guestfs_h *handle,
683                 const char *fstype,
684                 const char *device);
685
686 This runs the filesystem checker (fsck) on C<device> which
687 should have filesystem type C<fstype>.
688
689 The returned integer is the status.  See L<fsck(8)> for the
690 list of status codes from C<fsck>.
691
692 Notes:
693
694 =over 4
695
696 =item *
697
698 Multiple status codes can be summed together.
699
700 =item *
701
702 A non-zero return code can mean "success", for example if
703 errors have been corrected on the filesystem.
704
705 =item *
706
707 Checking or repairing NTFS volumes is not supported
708 (by linux-ntfs).
709
710 =back
711
712 This command is entirely equivalent to running C<fsck -a -t fstype device>.
713
714 On error this function returns -1.
715
716 =head2 guestfs_get_append
717
718  const char *guestfs_get_append (guestfs_h *handle);
719
720 Return the additional kernel options which are added to the
721 guest kernel command line.
722
723 If C<NULL> then no options are added.
724
725 This function returns a string, or NULL on error.
726 The string is owned by the guest handle and must I<not> be freed.
727
728 =head2 guestfs_get_autosync
729
730  int guestfs_get_autosync (guestfs_h *handle);
731
732 Get the autosync flag.
733
734 This function returns a C truth value on success or -1 on error.
735
736 =head2 guestfs_get_e2label
737
738  char *guestfs_get_e2label (guestfs_h *handle,
739                 const char *device);
740
741 This returns the ext2/3/4 filesystem label of the filesystem on
742 C<device>.
743
744 This function returns a string, or NULL on error.
745 I<The caller must free the returned string after use>.
746
747 =head2 guestfs_get_e2uuid
748
749  char *guestfs_get_e2uuid (guestfs_h *handle,
750                 const char *device);
751
752 This returns the ext2/3/4 filesystem UUID of the filesystem on
753 C<device>.
754
755 This function returns a string, or NULL on error.
756 I<The caller must free the returned string after use>.
757
758 =head2 guestfs_get_path
759
760  const char *guestfs_get_path (guestfs_h *handle);
761
762 Return the current search path.
763
764 This is always non-NULL.  If it wasn't set already, then this will
765 return the default path.
766
767 This function returns a string, or NULL on error.
768 The string is owned by the guest handle and must I<not> be freed.
769
770 =head2 guestfs_get_qemu
771
772  const char *guestfs_get_qemu (guestfs_h *handle);
773
774 Return the current qemu binary.
775
776 This is always non-NULL.  If it wasn't set already, then this will
777 return the default qemu binary name.
778
779 This function returns a string, or NULL on error.
780 The string is owned by the guest handle and must I<not> be freed.
781
782 =head2 guestfs_get_state
783
784  int guestfs_get_state (guestfs_h *handle);
785
786 This returns the current state as an opaque integer.  This is
787 only useful for printing debug and internal error messages.
788
789 For more information on states, see L<guestfs(3)>.
790
791 On error this function returns -1.
792
793 =head2 guestfs_get_verbose
794
795  int guestfs_get_verbose (guestfs_h *handle);
796
797 This returns the verbose messages flag.
798
799 This function returns a C truth value on success or -1 on error.
800
801 =head2 guestfs_grub_install
802
803  int guestfs_grub_install (guestfs_h *handle,
804                 const char *root,
805                 const char *device);
806
807 This command installs GRUB (the Grand Unified Bootloader) on
808 C<device>, with the root directory being C<root>.
809
810 This function returns 0 on success or -1 on error.
811
812 =head2 guestfs_hexdump
813
814  char *guestfs_hexdump (guestfs_h *handle,
815                 const char *path);
816
817 This runs C<hexdump -C> on the given C<path>.  The result is
818 the human-readable, canonical hex dump of the file.
819
820 This function returns a string, or NULL on error.
821 I<The caller must free the returned string after use>.
822
823 Because of the message protocol, there is a transfer limit 
824 of somewhere between 2MB and 4MB.  To transfer large files you should use
825 FTP.
826
827 =head2 guestfs_is_busy
828
829  int guestfs_is_busy (guestfs_h *handle);
830
831 This returns true iff this handle is busy processing a command
832 (in the C<BUSY> state).
833
834 For more information on states, see L<guestfs(3)>.
835
836 This function returns a C truth value on success or -1 on error.
837
838 =head2 guestfs_is_config
839
840  int guestfs_is_config (guestfs_h *handle);
841
842 This returns true iff this handle is being configured
843 (in the C<CONFIG> state).
844
845 For more information on states, see L<guestfs(3)>.
846
847 This function returns a C truth value on success or -1 on error.
848
849 =head2 guestfs_is_dir
850
851  int guestfs_is_dir (guestfs_h *handle,
852                 const char *path);
853
854 This returns C<true> if and only if there is a directory
855 with the given C<path> name.  Note that it returns false for
856 other objects like files.
857
858 See also C<guestfs_stat>.
859
860 This function returns a C truth value on success or -1 on error.
861
862 =head2 guestfs_is_file
863
864  int guestfs_is_file (guestfs_h *handle,
865                 const char *path);
866
867 This returns C<true> if and only if there is a file
868 with the given C<path> name.  Note that it returns false for
869 other objects like directories.
870
871 See also C<guestfs_stat>.
872
873 This function returns a C truth value on success or -1 on error.
874
875 =head2 guestfs_is_launching
876
877  int guestfs_is_launching (guestfs_h *handle);
878
879 This returns true iff this handle is launching the subprocess
880 (in the C<LAUNCHING> state).
881
882 For more information on states, see L<guestfs(3)>.
883
884 This function returns a C truth value on success or -1 on error.
885
886 =head2 guestfs_is_ready
887
888  int guestfs_is_ready (guestfs_h *handle);
889
890 This returns true iff this handle is ready to accept commands
891 (in the C<READY> state).
892
893 For more information on states, see L<guestfs(3)>.
894
895 This function returns a C truth value on success or -1 on error.
896
897 =head2 guestfs_kill_subprocess
898
899  int guestfs_kill_subprocess (guestfs_h *handle);
900
901 This kills the qemu subprocess.  You should never need to call this.
902
903 This function returns 0 on success or -1 on error.
904
905 =head2 guestfs_launch
906
907  int guestfs_launch (guestfs_h *handle);
908
909 Internally libguestfs is implemented by running a virtual machine
910 using L<qemu(1)>.
911
912 You should call this after configuring the handle
913 (eg. adding drives) but before performing any actions.
914
915 This function returns 0 on success or -1 on error.
916
917 =head2 guestfs_list_devices
918
919  char **guestfs_list_devices (guestfs_h *handle);
920
921 List all the block devices.
922
923 The full block device names are returned, eg. C</dev/sda>
924
925 This function returns a NULL-terminated array of strings
926 (like L<environ(3)>), or NULL if there was an error.
927 I<The caller must free the strings and the array after use>.
928
929 =head2 guestfs_list_partitions
930
931  char **guestfs_list_partitions (guestfs_h *handle);
932
933 List all the partitions detected on all block devices.
934
935 The full partition device names are returned, eg. C</dev/sda1>
936
937 This does not return logical volumes.  For that you will need to
938 call C<guestfs_lvs>.
939
940 This function returns a NULL-terminated array of strings
941 (like L<environ(3)>), or NULL if there was an error.
942 I<The caller must free the strings and the array after use>.
943
944 =head2 guestfs_ll
945
946  char *guestfs_ll (guestfs_h *handle,
947                 const char *directory);
948
949 List the files in C<directory> (relative to the root directory,
950 there is no cwd) in the format of 'ls -la'.
951
952 This command is mostly useful for interactive sessions.  It
953 is I<not> intended that you try to parse the output string.
954
955 This function returns a string, or NULL on error.
956 I<The caller must free the returned string after use>.
957
958 =head2 guestfs_ls
959
960  char **guestfs_ls (guestfs_h *handle,
961                 const char *directory);
962
963 List the files in C<directory> (relative to the root directory,
964 there is no cwd).  The '.' and '..' entries are not returned, but
965 hidden files are shown.
966
967 This command is mostly useful for interactive sessions.  Programs
968 should probably use C<guestfs_readdir> instead.
969
970 This function returns a NULL-terminated array of strings
971 (like L<environ(3)>), or NULL if there was an error.
972 I<The caller must free the strings and the array after use>.
973
974 =head2 guestfs_lstat
975
976  struct guestfs_stat *guestfs_lstat (guestfs_h *handle,
977                 const char *path);
978
979 Returns file information for the given C<path>.
980
981 This is the same as C<guestfs_stat> except that if C<path>
982 is a symbolic link, then the link is stat-ed, not the file it
983 refers to.
984
985 This is the same as the C<lstat(2)> system call.
986
987 This function returns a C<struct guestfs_stat *>
988 (see L<stat(2)> and E<lt>guestfs-structs.hE<gt>),
989 or NULL if there was an error.
990 I<The caller must call C<free> after use>.
991
992 =head2 guestfs_lvcreate
993
994  int guestfs_lvcreate (guestfs_h *handle,
995                 const char *logvol,
996                 const char *volgroup,
997                 int mbytes);
998
999 This creates an LVM volume group called C<logvol>
1000 on the volume group C<volgroup>, with C<size> megabytes.
1001
1002 This function returns 0 on success or -1 on error.
1003
1004 =head2 guestfs_lvm_remove_all
1005
1006  int guestfs_lvm_remove_all (guestfs_h *handle);
1007
1008 This command removes all LVM logical volumes, volume groups
1009 and physical volumes.
1010
1011 This function returns 0 on success or -1 on error.
1012
1013 B<This command is dangerous.  Without careful use you
1014 can easily destroy all your data>.
1015
1016 =head2 guestfs_lvremove
1017
1018  int guestfs_lvremove (guestfs_h *handle,
1019                 const char *device);
1020
1021 Remove an LVM logical volume C<device>, where C<device> is
1022 the path to the LV, such as C</dev/VG/LV>.
1023
1024 You can also remove all LVs in a volume group by specifying
1025 the VG name, C</dev/VG>.
1026
1027 This function returns 0 on success or -1 on error.
1028
1029 =head2 guestfs_lvresize
1030
1031  int guestfs_lvresize (guestfs_h *handle,
1032                 const char *device,
1033                 int mbytes);
1034
1035 This resizes (expands or shrinks) an existing LVM logical
1036 volume to C<mbytes>.  When reducing, data in the reduced part
1037 is lost.
1038
1039 This function returns 0 on success or -1 on error.
1040
1041 =head2 guestfs_lvs
1042
1043  char **guestfs_lvs (guestfs_h *handle);
1044
1045 List all the logical volumes detected.  This is the equivalent
1046 of the L<lvs(8)> command.
1047
1048 This returns a list of the logical volume device names
1049 (eg. C</dev/VolGroup00/LogVol00>).
1050
1051 See also C<guestfs_lvs_full>.
1052
1053 This function returns a NULL-terminated array of strings
1054 (like L<environ(3)>), or NULL if there was an error.
1055 I<The caller must free the strings and the array after use>.
1056
1057 =head2 guestfs_lvs_full
1058
1059  struct guestfs_lvm_lv_list *guestfs_lvs_full (guestfs_h *handle);
1060
1061 List all the logical volumes detected.  This is the equivalent
1062 of the L<lvs(8)> command.  The "full" version includes all fields.
1063
1064 This function returns a C<struct guestfs_lvm_lv_list *>
1065 (see E<lt>guestfs-structs.hE<gt>),
1066 or NULL if there was an error.
1067 I<The caller must call C<guestfs_free_lvm_lv_list> after use>.
1068
1069 =head2 guestfs_mkdir
1070
1071  int guestfs_mkdir (guestfs_h *handle,
1072                 const char *path);
1073
1074 Create a directory named C<path>.
1075
1076 This function returns 0 on success or -1 on error.
1077
1078 =head2 guestfs_mkdir_p
1079
1080  int guestfs_mkdir_p (guestfs_h *handle,
1081                 const char *path);
1082
1083 Create a directory named C<path>, creating any parent directories
1084 as necessary.  This is like the C<mkdir -p> shell command.
1085
1086 This function returns 0 on success or -1 on error.
1087
1088 =head2 guestfs_mkfs
1089
1090  int guestfs_mkfs (guestfs_h *handle,
1091                 const char *fstype,
1092                 const char *device);
1093
1094 This creates a filesystem on C<device> (usually a partition
1095 or LVM logical volume).  The filesystem type is C<fstype>, for
1096 example C<ext3>.
1097
1098 This function returns 0 on success or -1 on error.
1099
1100 =head2 guestfs_mount
1101
1102  int guestfs_mount (guestfs_h *handle,
1103                 const char *device,
1104                 const char *mountpoint);
1105
1106 Mount a guest disk at a position in the filesystem.  Block devices
1107 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
1108 the guest.  If those block devices contain partitions, they will have
1109 the usual names (eg. C</dev/sda1>).  Also LVM C</dev/VG/LV>-style
1110 names can be used.
1111
1112 The rules are the same as for L<mount(2)>:  A filesystem must
1113 first be mounted on C</> before others can be mounted.  Other
1114 filesystems can only be mounted on directories which already
1115 exist.
1116
1117 The mounted filesystem is writable, if we have sufficient permissions
1118 on the underlying device.
1119
1120 The filesystem options C<sync> and C<noatime> are set with this
1121 call, in order to improve reliability.
1122
1123 This function returns 0 on success or -1 on error.
1124
1125 =head2 guestfs_mount_options
1126
1127  int guestfs_mount_options (guestfs_h *handle,
1128                 const char *options,
1129                 const char *device,
1130                 const char *mountpoint);
1131
1132 This is the same as the C<guestfs_mount> command, but it
1133 allows you to set the mount options as for the
1134 L<mount(8)> I<-o> flag.
1135
1136 This function returns 0 on success or -1 on error.
1137
1138 =head2 guestfs_mount_ro
1139
1140  int guestfs_mount_ro (guestfs_h *handle,
1141                 const char *device,
1142                 const char *mountpoint);
1143
1144 This is the same as the C<guestfs_mount> command, but it
1145 mounts the filesystem with the read-only (I<-o ro>) flag.
1146
1147 This function returns 0 on success or -1 on error.
1148
1149 =head2 guestfs_mount_vfs
1150
1151  int guestfs_mount_vfs (guestfs_h *handle,
1152                 const char *options,
1153                 const char *vfstype,
1154                 const char *device,
1155                 const char *mountpoint);
1156
1157 This is the same as the C<guestfs_mount> command, but it
1158 allows you to set both the mount options and the vfstype
1159 as for the L<mount(8)> I<-o> and I<-t> flags.
1160
1161 This function returns 0 on success or -1 on error.
1162
1163 =head2 guestfs_mounts
1164
1165  char **guestfs_mounts (guestfs_h *handle);
1166
1167 This returns the list of currently mounted filesystems.  It returns
1168 the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
1169
1170 Some internal mounts are not shown.
1171
1172 This function returns a NULL-terminated array of strings
1173 (like L<environ(3)>), or NULL if there was an error.
1174 I<The caller must free the strings and the array after use>.
1175
1176 =head2 guestfs_mv
1177
1178  int guestfs_mv (guestfs_h *handle,
1179                 const char *src,
1180                 const char *dest);
1181
1182 This moves a file from C<src> to C<dest> where C<dest> is
1183 either a destination filename or destination directory.
1184
1185 This function returns 0 on success or -1 on error.
1186
1187 =head2 guestfs_ping_daemon
1188
1189  int guestfs_ping_daemon (guestfs_h *handle);
1190
1191 This is a test probe into the guestfs daemon running inside
1192 the qemu subprocess.  Calling this function checks that the
1193 daemon responds to the ping message, without affecting the daemon
1194 or attached block device(s) in any other way.
1195
1196 This function returns 0 on success or -1 on error.
1197
1198 =head2 guestfs_pvcreate
1199
1200  int guestfs_pvcreate (guestfs_h *handle,
1201                 const char *device);
1202
1203 This creates an LVM physical volume on the named C<device>,
1204 where C<device> should usually be a partition name such
1205 as C</dev/sda1>.
1206
1207 This function returns 0 on success or -1 on error.
1208
1209 =head2 guestfs_pvremove
1210
1211  int guestfs_pvremove (guestfs_h *handle,
1212                 const char *device);
1213
1214 This wipes a physical volume C<device> so that LVM will no longer
1215 recognise it.
1216
1217 The implementation uses the C<pvremove> command which refuses to
1218 wipe physical volumes that contain any volume groups, so you have
1219 to remove those first.
1220
1221 This function returns 0 on success or -1 on error.
1222
1223 =head2 guestfs_pvresize
1224
1225  int guestfs_pvresize (guestfs_h *handle,
1226                 const char *device);
1227
1228 This resizes (expands or shrinks) an existing LVM physical
1229 volume to match the new size of the underlying device.
1230
1231 This function returns 0 on success or -1 on error.
1232
1233 =head2 guestfs_pvs
1234
1235  char **guestfs_pvs (guestfs_h *handle);
1236
1237 List all the physical volumes detected.  This is the equivalent
1238 of the L<pvs(8)> command.
1239
1240 This returns a list of just the device names that contain
1241 PVs (eg. C</dev/sda2>).
1242
1243 See also C<guestfs_pvs_full>.
1244
1245 This function returns a NULL-terminated array of strings
1246 (like L<environ(3)>), or NULL if there was an error.
1247 I<The caller must free the strings and the array after use>.
1248
1249 =head2 guestfs_pvs_full
1250
1251  struct guestfs_lvm_pv_list *guestfs_pvs_full (guestfs_h *handle);
1252
1253 List all the physical volumes detected.  This is the equivalent
1254 of the L<pvs(8)> command.  The "full" version includes all fields.
1255
1256 This function returns a C<struct guestfs_lvm_pv_list *>
1257 (see E<lt>guestfs-structs.hE<gt>),
1258 or NULL if there was an error.
1259 I<The caller must call C<guestfs_free_lvm_pv_list> after use>.
1260
1261 =head2 guestfs_read_lines
1262
1263  char **guestfs_read_lines (guestfs_h *handle,
1264                 const char *path);
1265
1266 Return the contents of the file named C<path>.
1267
1268 The file contents are returned as a list of lines.  Trailing
1269 C<LF> and C<CRLF> character sequences are I<not> returned.
1270
1271 Note that this function cannot correctly handle binary files
1272 (specifically, files containing C<\0> character which is treated
1273 as end of line).  For those you need to use the C<guestfs_read_file>
1274 function which has a more complex interface.
1275
1276 This function returns a NULL-terminated array of strings
1277 (like L<environ(3)>), or NULL if there was an error.
1278 I<The caller must free the strings and the array after use>.
1279
1280 =head2 guestfs_resize2fs
1281
1282  int guestfs_resize2fs (guestfs_h *handle,
1283                 const char *device);
1284
1285 This resizes an ext2 or ext3 filesystem to match the size of
1286 the underlying device.
1287
1288 This function returns 0 on success or -1 on error.
1289
1290 =head2 guestfs_rm
1291
1292  int guestfs_rm (guestfs_h *handle,
1293                 const char *path);
1294
1295 Remove the single file C<path>.
1296
1297 This function returns 0 on success or -1 on error.
1298
1299 =head2 guestfs_rm_rf
1300
1301  int guestfs_rm_rf (guestfs_h *handle,
1302                 const char *path);
1303
1304 Remove the file or directory C<path>, recursively removing the
1305 contents if its a directory.  This is like the C<rm -rf> shell
1306 command.
1307
1308 This function returns 0 on success or -1 on error.
1309
1310 =head2 guestfs_rmdir
1311
1312  int guestfs_rmdir (guestfs_h *handle,
1313                 const char *path);
1314
1315 Remove the single directory C<path>.
1316
1317 This function returns 0 on success or -1 on error.
1318
1319 =head2 guestfs_set_append
1320
1321  int guestfs_set_append (guestfs_h *handle,
1322                 const char *append);
1323
1324 This function is used to add additional options to the
1325 guest kernel command line.
1326
1327 The default is C<NULL> unless overridden by setting
1328 C<LIBGUESTFS_APPEND> environment variable.
1329
1330 Setting C<append> to C<NULL> means I<no> additional options
1331 are passed (libguestfs always adds a few of its own).
1332
1333 This function returns 0 on success or -1 on error.
1334
1335 =head2 guestfs_set_autosync
1336
1337  int guestfs_set_autosync (guestfs_h *handle,
1338                 int autosync);
1339
1340 If C<autosync> is true, this enables autosync.  Libguestfs will make a
1341 best effort attempt to run C<guestfs_umount_all> followed by
1342 C<guestfs_sync> when the handle is closed
1343 (also if the program exits without closing handles).
1344
1345 This is disabled by default (except in guestfish where it is
1346 enabled by default).
1347
1348 This function returns 0 on success or -1 on error.
1349
1350 =head2 guestfs_set_busy
1351
1352  int guestfs_set_busy (guestfs_h *handle);
1353
1354 This sets the state to C<BUSY>.  This is only used when implementing
1355 actions using the low-level API.
1356
1357 For more information on states, see L<guestfs(3)>.
1358
1359 This function returns 0 on success or -1 on error.
1360
1361 =head2 guestfs_set_e2label
1362
1363  int guestfs_set_e2label (guestfs_h *handle,
1364                 const char *device,
1365                 const char *label);
1366
1367 This sets the ext2/3/4 filesystem label of the filesystem on
1368 C<device> to C<label>.  Filesystem labels are limited to
1369 16 characters.
1370
1371 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2label>
1372 to return the existing label on a filesystem.
1373
1374 This function returns 0 on success or -1 on error.
1375
1376 =head2 guestfs_set_e2uuid
1377
1378  int guestfs_set_e2uuid (guestfs_h *handle,
1379                 const char *device,
1380                 const char *uuid);
1381
1382 This sets the ext2/3/4 filesystem UUID of the filesystem on
1383 C<device> to C<uuid>.  The format of the UUID and alternatives
1384 such as C<clear>, C<random> and C<time> are described in the
1385 L<tune2fs(8)> manpage.
1386
1387 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2uuid>
1388 to return the existing UUID of a filesystem.
1389
1390 This function returns 0 on success or -1 on error.
1391
1392 =head2 guestfs_set_path
1393
1394  int guestfs_set_path (guestfs_h *handle,
1395                 const char *path);
1396
1397 Set the path that libguestfs searches for kernel and initrd.img.
1398
1399 The default is C<$libdir/guestfs> unless overridden by setting
1400 C<LIBGUESTFS_PATH> environment variable.
1401
1402 Setting C<path> to C<NULL> restores the default path.
1403
1404 This function returns 0 on success or -1 on error.
1405
1406 =head2 guestfs_set_qemu
1407
1408  int guestfs_set_qemu (guestfs_h *handle,
1409                 const char *qemu);
1410
1411 Set the qemu binary that we will use.
1412
1413 The default is chosen when the library was compiled by the
1414 configure script.
1415
1416 You can also override this by setting the C<LIBGUESTFS_QEMU>
1417 environment variable.
1418
1419 Setting C<qemu> to C<NULL> restores the default qemu binary.
1420
1421 This function returns 0 on success or -1 on error.
1422
1423 =head2 guestfs_set_ready
1424
1425  int guestfs_set_ready (guestfs_h *handle);
1426
1427 This sets the state to C<READY>.  This is only used when implementing
1428 actions using the low-level API.
1429
1430 For more information on states, see L<guestfs(3)>.
1431
1432 This function returns 0 on success or -1 on error.
1433
1434 =head2 guestfs_set_verbose
1435
1436  int guestfs_set_verbose (guestfs_h *handle,
1437                 int verbose);
1438
1439 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
1440
1441 Verbose messages are disabled unless the environment variable
1442 C<LIBGUESTFS_DEBUG> is defined and set to C<1>.
1443
1444 This function returns 0 on success or -1 on error.
1445
1446 =head2 guestfs_sfdisk
1447
1448  int guestfs_sfdisk (guestfs_h *handle,
1449                 const char *device,
1450                 int cyls,
1451                 int heads,
1452                 int sectors,
1453                 char * const* const lines);
1454
1455 This is a direct interface to the L<sfdisk(8)> program for creating
1456 partitions on block devices.
1457
1458 C<device> should be a block device, for example C</dev/sda>.
1459
1460 C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads
1461 and sectors on the device, which are passed directly to sfdisk as
1462 the I<-C>, I<-H> and I<-S> parameters.  If you pass C<0> for any
1463 of these, then the corresponding parameter is omitted.  Usually for
1464 'large' disks, you can just pass C<0> for these, but for small
1465 (floppy-sized) disks, sfdisk (or rather, the kernel) cannot work
1466 out the right geometry and you will need to tell it.
1467
1468 C<lines> is a list of lines that we feed to C<sfdisk>.  For more
1469 information refer to the L<sfdisk(8)> manpage.
1470
1471 To create a single partition occupying the whole disk, you would
1472 pass C<lines> as a single element list, when the single element being
1473 the string C<,> (comma).
1474
1475 See also: C<guestfs_sfdisk_l>, C<guestfs_sfdisk_N>
1476
1477 This function returns 0 on success or -1 on error.
1478
1479 B<This command is dangerous.  Without careful use you
1480 can easily destroy all your data>.
1481
1482 =head2 guestfs_sfdisk_N
1483
1484  int guestfs_sfdisk_N (guestfs_h *handle,
1485                 const char *device,
1486                 int n,
1487                 int cyls,
1488                 int heads,
1489                 int sectors,
1490                 const char *line);
1491
1492 This runs L<sfdisk(8)> option to modify just the single
1493 partition C<n> (note: C<n> counts from 1).
1494
1495 For other parameters, see C<guestfs_sfdisk>.  You should usually
1496 pass C<0> for the cyls/heads/sectors parameters.
1497
1498 This function returns 0 on success or -1 on error.
1499
1500 B<This command is dangerous.  Without careful use you
1501 can easily destroy all your data>.
1502
1503 =head2 guestfs_sfdisk_disk_geometry
1504
1505  char *guestfs_sfdisk_disk_geometry (guestfs_h *handle,
1506                 const char *device);
1507
1508 This displays the disk geometry of C<device> read from the
1509 partition table.  Especially in the case where the underlying
1510 block device has been resized, this can be different from the
1511 kernel's idea of the geometry (see C<guestfs_sfdisk_kernel_geometry>).
1512
1513 The result is in human-readable format, and not designed to
1514 be parsed.
1515
1516 This function returns a string, or NULL on error.
1517 I<The caller must free the returned string after use>.
1518
1519 =head2 guestfs_sfdisk_kernel_geometry
1520
1521  char *guestfs_sfdisk_kernel_geometry (guestfs_h *handle,
1522                 const char *device);
1523
1524 This displays the kernel's idea of the geometry of C<device>.
1525
1526 The result is in human-readable format, and not designed to
1527 be parsed.
1528
1529 This function returns a string, or NULL on error.
1530 I<The caller must free the returned string after use>.
1531
1532 =head2 guestfs_sfdisk_l
1533
1534  char *guestfs_sfdisk_l (guestfs_h *handle,
1535                 const char *device);
1536
1537 This displays the partition table on C<device>, in the
1538 human-readable output of the L<sfdisk(8)> command.  It is
1539 not intended to be parsed.
1540
1541 This function returns a string, or NULL on error.
1542 I<The caller must free the returned string after use>.
1543
1544 =head2 guestfs_stat
1545
1546  struct guestfs_stat *guestfs_stat (guestfs_h *handle,
1547                 const char *path);
1548
1549 Returns file information for the given C<path>.
1550
1551 This is the same as the C<stat(2)> system call.
1552
1553 This function returns a C<struct guestfs_stat *>
1554 (see L<stat(2)> and E<lt>guestfs-structs.hE<gt>),
1555 or NULL if there was an error.
1556 I<The caller must call C<free> after use>.
1557
1558 =head2 guestfs_statvfs
1559
1560  struct guestfs_statvfs *guestfs_statvfs (guestfs_h *handle,
1561                 const char *path);
1562
1563 Returns file system statistics for any mounted file system.
1564 C<path> should be a file or directory in the mounted file system
1565 (typically it is the mount point itself, but it doesn't need to be).
1566
1567 This is the same as the C<statvfs(2)> system call.
1568
1569 This function returns a C<struct guestfs_statvfs *>
1570 (see L<statvfs(2)> and E<lt>guestfs-structs.hE<gt>),
1571 or NULL if there was an error.
1572 I<The caller must call C<free> after use>.
1573
1574 =head2 guestfs_strings
1575
1576  char **guestfs_strings (guestfs_h *handle,
1577                 const char *path);
1578
1579 This runs the L<strings(1)> command on a file and returns
1580 the list of printable strings found.
1581
1582 This function returns a NULL-terminated array of strings
1583 (like L<environ(3)>), or NULL if there was an error.
1584 I<The caller must free the strings and the array after use>.
1585
1586 Because of the message protocol, there is a transfer limit 
1587 of somewhere between 2MB and 4MB.  To transfer large files you should use
1588 FTP.
1589
1590 =head2 guestfs_strings_e
1591
1592  char **guestfs_strings_e (guestfs_h *handle,
1593                 const char *encoding,
1594                 const char *path);
1595
1596 This is like the C<guestfs_strings> command, but allows you to
1597 specify the encoding.
1598
1599 See the L<strings(1)> manpage for the full list of encodings.
1600
1601 Commonly useful encodings are C<l> (lower case L) which will
1602 show strings inside Windows/x86 files.
1603
1604 The returned strings are transcoded to UTF-8.
1605
1606 This function returns a NULL-terminated array of strings
1607 (like L<environ(3)>), or NULL if there was an error.
1608 I<The caller must free the strings and the array after use>.
1609
1610 Because of the message protocol, there is a transfer limit 
1611 of somewhere between 2MB and 4MB.  To transfer large files you should use
1612 FTP.
1613
1614 =head2 guestfs_sync
1615
1616  int guestfs_sync (guestfs_h *handle);
1617
1618 This syncs the disk, so that any writes are flushed through to the
1619 underlying disk image.
1620
1621 You should always call this if you have modified a disk image, before
1622 closing the handle.
1623
1624 This function returns 0 on success or -1 on error.
1625
1626 =head2 guestfs_tar_in
1627
1628  int guestfs_tar_in (guestfs_h *handle,
1629                 const char *tarfile,
1630                 const char *directory);
1631
1632 This command uploads and unpacks local file C<tarfile> (an
1633 I<uncompressed> tar file) into C<directory>.
1634
1635 To upload a compressed tarball, use C<guestfs_tgz_in>.
1636
1637 This function returns 0 on success or -1 on error.
1638
1639 =head2 guestfs_tar_out
1640
1641  int guestfs_tar_out (guestfs_h *handle,
1642                 const char *directory,
1643                 const char *tarfile);
1644
1645 This command packs the contents of C<directory> and downloads
1646 it to local file C<tarfile>.
1647
1648 To download a compressed tarball, use C<guestfs_tgz_out>.
1649
1650 This function returns 0 on success or -1 on error.
1651
1652 =head2 guestfs_tgz_in
1653
1654  int guestfs_tgz_in (guestfs_h *handle,
1655                 const char *tarball,
1656                 const char *directory);
1657
1658 This command uploads and unpacks local file C<tarball> (a
1659 I<gzip compressed> tar file) into C<directory>.
1660
1661 To upload an uncompressed tarball, use C<guestfs_tar_in>.
1662
1663 This function returns 0 on success or -1 on error.
1664
1665 =head2 guestfs_tgz_out
1666
1667  int guestfs_tgz_out (guestfs_h *handle,
1668                 const char *directory,
1669                 const char *tarball);
1670
1671 This command packs the contents of C<directory> and downloads
1672 it to local file C<tarball>.
1673
1674 To download an uncompressed tarball, use C<guestfs_tar_out>.
1675
1676 This function returns 0 on success or -1 on error.
1677
1678 =head2 guestfs_touch
1679
1680  int guestfs_touch (guestfs_h *handle,
1681                 const char *path);
1682
1683 Touch acts like the L<touch(1)> command.  It can be used to
1684 update the timestamps on a file, or, if the file does not exist,
1685 to create a new zero-length file.
1686
1687 This function returns 0 on success or -1 on error.
1688
1689 =head2 guestfs_tune2fs_l
1690
1691  char **guestfs_tune2fs_l (guestfs_h *handle,
1692                 const char *device);
1693
1694 This returns the contents of the ext2, ext3 or ext4 filesystem
1695 superblock on C<device>.
1696
1697 It is the same as running C<tune2fs -l device>.  See L<tune2fs(8)>
1698 manpage for more details.  The list of fields returned isn't
1699 clearly defined, and depends on both the version of C<tune2fs>
1700 that libguestfs was built against, and the filesystem itself.
1701
1702 This function returns a NULL-terminated array of
1703 strings, or NULL if there was an error.
1704 The array of strings will always have length C<2n+1>, where
1705 C<n> keys and values alternate, followed by the trailing NULL entry.
1706 I<The caller must free the strings and the array after use>.
1707
1708 =head2 guestfs_umount
1709
1710  int guestfs_umount (guestfs_h *handle,
1711                 const char *pathordevice);
1712
1713 This unmounts the given filesystem.  The filesystem may be
1714 specified either by its mountpoint (path) or the device which
1715 contains the filesystem.
1716
1717 This function returns 0 on success or -1 on error.
1718
1719 =head2 guestfs_umount_all
1720
1721  int guestfs_umount_all (guestfs_h *handle);
1722
1723 This unmounts all mounted filesystems.
1724
1725 Some internal mounts are not unmounted by this call.
1726
1727 This function returns 0 on success or -1 on error.
1728
1729 =head2 guestfs_upload
1730
1731  int guestfs_upload (guestfs_h *handle,
1732                 const char *filename,
1733                 const char *remotefilename);
1734
1735 Upload local file C<filename> to C<remotefilename> on the
1736 filesystem.
1737
1738 C<filename> can also be a named pipe.
1739
1740 See also C<guestfs_download>.
1741
1742 This function returns 0 on success or -1 on error.
1743
1744 =head2 guestfs_vg_activate
1745
1746  int guestfs_vg_activate (guestfs_h *handle,
1747                 int activate,
1748                 char * const* const volgroups);
1749
1750 This command activates or (if C<activate> is false) deactivates
1751 all logical volumes in the listed volume groups C<volgroups>.
1752 If activated, then they are made known to the
1753 kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
1754 then those devices disappear.
1755
1756 This command is the same as running C<vgchange -a y|n volgroups...>
1757
1758 Note that if C<volgroups> is an empty list then B<all> volume groups
1759 are activated or deactivated.
1760
1761 This function returns 0 on success or -1 on error.
1762
1763 =head2 guestfs_vg_activate_all
1764
1765  int guestfs_vg_activate_all (guestfs_h *handle,
1766                 int activate);
1767
1768 This command activates or (if C<activate> is false) deactivates
1769 all logical volumes in all volume groups.
1770 If activated, then they are made known to the
1771 kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
1772 then those devices disappear.
1773
1774 This command is the same as running C<vgchange -a y|n>
1775
1776 This function returns 0 on success or -1 on error.
1777
1778 =head2 guestfs_vgcreate
1779
1780  int guestfs_vgcreate (guestfs_h *handle,
1781                 const char *volgroup,
1782                 char * const* const physvols);
1783
1784 This creates an LVM volume group called C<volgroup>
1785 from the non-empty list of physical volumes C<physvols>.
1786
1787 This function returns 0 on success or -1 on error.
1788
1789 =head2 guestfs_vgremove
1790
1791  int guestfs_vgremove (guestfs_h *handle,
1792                 const char *vgname);
1793
1794 Remove an LVM volume group C<vgname>, (for example C<VG>).
1795
1796 This also forcibly removes all logical volumes in the volume
1797 group (if any).
1798
1799 This function returns 0 on success or -1 on error.
1800
1801 =head2 guestfs_vgs
1802
1803  char **guestfs_vgs (guestfs_h *handle);
1804
1805 List all the volumes groups detected.  This is the equivalent
1806 of the L<vgs(8)> command.
1807
1808 This returns a list of just the volume group names that were
1809 detected (eg. C<VolGroup00>).
1810
1811 See also C<guestfs_vgs_full>.
1812
1813 This function returns a NULL-terminated array of strings
1814 (like L<environ(3)>), or NULL if there was an error.
1815 I<The caller must free the strings and the array after use>.
1816
1817 =head2 guestfs_vgs_full
1818
1819  struct guestfs_lvm_vg_list *guestfs_vgs_full (guestfs_h *handle);
1820
1821 List all the volumes groups detected.  This is the equivalent
1822 of the L<vgs(8)> command.  The "full" version includes all fields.
1823
1824 This function returns a C<struct guestfs_lvm_vg_list *>
1825 (see E<lt>guestfs-structs.hE<gt>),
1826 or NULL if there was an error.
1827 I<The caller must call C<guestfs_free_lvm_vg_list> after use>.
1828
1829 =head2 guestfs_wait_ready
1830
1831  int guestfs_wait_ready (guestfs_h *handle);
1832
1833 Internally libguestfs is implemented by running a virtual machine
1834 using L<qemu(1)>.
1835
1836 You should call this after C<guestfs_launch> to wait for the launch
1837 to complete.
1838
1839 This function returns 0 on success or -1 on error.
1840
1841 =head2 guestfs_write_file
1842
1843  int guestfs_write_file (guestfs_h *handle,
1844                 const char *path,
1845                 const char *content,
1846                 int size);
1847
1848 This call creates a file called C<path>.  The contents of the
1849 file is the string C<content> (which can contain any 8 bit data),
1850 with length C<size>.
1851
1852 As a special case, if C<size> is C<0>
1853 then the length is calculated using C<strlen> (so in this case
1854 the content cannot contain embedded ASCII NULs).
1855
1856 I<NB.> Owing to a bug, writing content containing ASCII NUL
1857 characters does I<not> work, even if the length is specified.
1858 We hope to resolve this bug in a future version.  In the meantime
1859 use C<guestfs_upload>.
1860
1861 This function returns 0 on success or -1 on error.
1862
1863 Because of the message protocol, there is a transfer limit 
1864 of somewhere between 2MB and 4MB.  To transfer large files you should use
1865 FTP.
1866
1867 =head2 guestfs_zero
1868
1869  int guestfs_zero (guestfs_h *handle,
1870                 const char *device);
1871
1872 This command writes zeroes over the first few blocks of C<device>.
1873
1874 How many blocks are zeroed isn't specified (but it's I<not> enough
1875 to securely wipe the device).  It should be sufficient to remove
1876 any partition tables, filesystem superblocks and so on.
1877
1878 This function returns 0 on success or -1 on error.
1879
1880 =head2 guestfs_zerofree
1881
1882  int guestfs_zerofree (guestfs_h *handle,
1883                 const char *device);
1884
1885 This runs the I<zerofree> program on C<device>.  This program
1886 claims to zero unused inodes and disk blocks on an ext2/3
1887 filesystem, thus making it possible to compress the filesystem
1888 more effectively.
1889
1890 You should B<not> run this program if the filesystem is
1891 mounted.
1892
1893 It is possible that using this program can damage the filesystem
1894 or data on the filesystem.
1895
1896 This function returns 0 on success or -1 on error.
1897