1 =head2 guestfs_add_cdrom
3 int guestfs_add_cdrom (guestfs_h *handle,
6 This function adds a virtual CD-ROM disk image to the guest.
8 This is equivalent to the qemu parameter C<-cdrom filename>.
10 Note that this call checks for the existence of C<filename>. This
11 stops you from specifying other types of drive which are supported
12 by qemu such as C<nbd:> and C<http:> URLs. To specify those, use
13 the general C<guestfs_config> call instead.
15 This function returns 0 on success or -1 on error.
17 =head2 guestfs_add_drive
19 int guestfs_add_drive (guestfs_h *handle,
20 const char *filename);
22 This function adds a virtual machine disk image C<filename> to the
23 guest. The first time you call this function, the disk appears as IDE
24 disk 0 (C</dev/sda>) in the guest, the second time as C</dev/sdb>, and
27 You don't necessarily need to be root when using libguestfs. However
28 you obviously do need sufficient permissions to access the filename
29 for whatever operations you want to perform (ie. read access if you
30 just want to read the image or write access if you want to modify the
33 This is equivalent to the qemu parameter
34 C<-drive file=filename,cache=off,if=virtio>.
36 Note that this call checks for the existence of C<filename>. This
37 stops you from specifying other types of drive which are supported
38 by qemu such as C<nbd:> and C<http:> URLs. To specify those, use
39 the general C<guestfs_config> call instead.
41 This function returns 0 on success or -1 on error.
43 =head2 guestfs_add_drive_ro
45 int guestfs_add_drive_ro (guestfs_h *handle,
46 const char *filename);
48 This adds a drive in snapshot mode, making it effectively
51 Note that writes to the device are allowed, and will be seen for
52 the duration of the guestfs handle, but they are written
53 to a temporary file which is discarded as soon as the guestfs
54 handle is closed. We don't currently have any method to enable
55 changes to be committed, although qemu can support this.
57 This is equivalent to the qemu parameter
58 C<-drive file=filename,snapshot=on,if=virtio>.
60 Note that this call checks for the existence of C<filename>. This
61 stops you from specifying other types of drive which are supported
62 by qemu such as C<nbd:> and C<http:> URLs. To specify those, use
63 the general C<guestfs_config> call instead.
65 This function returns 0 on success or -1 on error.
67 =head2 guestfs_aug_close
69 int guestfs_aug_close (guestfs_h *handle);
71 Close the current Augeas handle and free up any resources
72 used by it. After calling this, you have to call
73 C<guestfs_aug_init> again before you can use any other
76 This function returns 0 on success or -1 on error.
78 =head2 guestfs_aug_defnode
80 struct guestfs_int_bool *guestfs_aug_defnode (guestfs_h *handle,
85 Defines a variable C<name> whose value is the result of
88 If C<expr> evaluates to an empty nodeset, a node is created,
89 equivalent to calling C<guestfs_aug_set> C<expr>, C<value>.
90 C<name> will be the nodeset containing that single node.
92 On success this returns a pair containing the
93 number of nodes in the nodeset, and a boolean flag
94 if a node was created.
96 This function returns a C<struct guestfs_int_bool *>,
97 or NULL if there was an error.
98 I<The caller must call C<guestfs_free_int_bool> after use>.
100 =head2 guestfs_aug_defvar
102 int guestfs_aug_defvar (guestfs_h *handle,
106 Defines an Augeas variable C<name> whose value is the result
107 of evaluating C<expr>. If C<expr> is NULL, then C<name> is
110 On success this returns the number of nodes in C<expr>, or
111 C<0> if C<expr> evaluates to something which is not a nodeset.
113 On error this function returns -1.
115 =head2 guestfs_aug_get
117 char *guestfs_aug_get (guestfs_h *handle,
120 Look up the value associated with C<path>. If C<path>
121 matches exactly one node, the C<value> is returned.
123 This function returns a string, or NULL on error.
124 I<The caller must free the returned string after use>.
126 =head2 guestfs_aug_init
128 int guestfs_aug_init (guestfs_h *handle,
132 Create a new Augeas handle for editing configuration files.
133 If there was any previous Augeas handle associated with this
134 guestfs session, then it is closed.
136 You must call this before using any other C<guestfs_aug_*>
139 C<root> is the filesystem root. C<root> must not be NULL,
142 The flags are the same as the flags defined in
143 E<lt>augeas.hE<gt>, the logical I<or> of the following
148 =item C<AUG_SAVE_BACKUP> = 1
150 Keep the original file with a C<.augsave> extension.
152 =item C<AUG_SAVE_NEWFILE> = 2
154 Save changes into a file with extension C<.augnew>, and
155 do not overwrite original. Overrides C<AUG_SAVE_BACKUP>.
157 =item C<AUG_TYPE_CHECK> = 4
159 Typecheck lenses (can be expensive).
161 =item C<AUG_NO_STDINC> = 8
163 Do not use standard load path for modules.
165 =item C<AUG_SAVE_NOOP> = 16
167 Make save a no-op, just record what would have been changed.
169 =item C<AUG_NO_LOAD> = 32
171 Do not load the tree in C<guestfs_aug_init>.
175 To close the handle, you can call C<guestfs_aug_close>.
177 To find out more about Augeas, see L<http://augeas.net/>.
179 This function returns 0 on success or -1 on error.
181 =head2 guestfs_aug_insert
183 int guestfs_aug_insert (guestfs_h *handle,
188 Create a new sibling C<label> for C<path>, inserting it into
189 the tree before or after C<path> (depending on the boolean
192 C<path> must match exactly one existing node in the tree, and
193 C<label> must be a label, ie. not contain C</>, C<*> or end
194 with a bracketed index C<[N]>.
196 This function returns 0 on success or -1 on error.
198 =head2 guestfs_aug_load
200 int guestfs_aug_load (guestfs_h *handle);
202 Load files into the tree.
204 See C<aug_load> in the Augeas documentation for the full gory
207 This function returns 0 on success or -1 on error.
209 =head2 guestfs_aug_ls
211 char **guestfs_aug_ls (guestfs_h *handle,
214 This is just a shortcut for listing C<guestfs_aug_match>
215 C<path/*> and sorting the resulting nodes into alphabetical order.
217 This function returns a NULL-terminated array of strings
218 (like L<environ(3)>), or NULL if there was an error.
219 I<The caller must free the strings and the array after use>.
221 =head2 guestfs_aug_match
223 char **guestfs_aug_match (guestfs_h *handle,
226 Returns a list of paths which match the path expression C<path>.
227 The returned paths are sufficiently qualified so that they match
228 exactly one node in the current tree.
230 This function returns a NULL-terminated array of strings
231 (like L<environ(3)>), or NULL if there was an error.
232 I<The caller must free the strings and the array after use>.
234 =head2 guestfs_aug_mv
236 int guestfs_aug_mv (guestfs_h *handle,
240 Move the node C<src> to C<dest>. C<src> must match exactly
241 one node. C<dest> is overwritten if it exists.
243 This function returns 0 on success or -1 on error.
245 =head2 guestfs_aug_rm
247 int guestfs_aug_rm (guestfs_h *handle,
250 Remove C<path> and all of its children.
252 On success this returns the number of entries which were removed.
254 On error this function returns -1.
256 =head2 guestfs_aug_save
258 int guestfs_aug_save (guestfs_h *handle);
260 This writes all pending changes to disk.
262 The flags which were passed to C<guestfs_aug_init> affect exactly
265 This function returns 0 on success or -1 on error.
267 =head2 guestfs_aug_set
269 int guestfs_aug_set (guestfs_h *handle,
273 Set the value associated with C<path> to C<value>.
275 This function returns 0 on success or -1 on error.
277 =head2 guestfs_blockdev_flushbufs
279 int guestfs_blockdev_flushbufs (guestfs_h *handle,
282 This tells the kernel to flush internal buffers associated
285 This uses the L<blockdev(8)> command.
287 This function returns 0 on success or -1 on error.
289 =head2 guestfs_blockdev_getbsz
291 int guestfs_blockdev_getbsz (guestfs_h *handle,
294 This returns the block size of a device.
296 (Note this is different from both I<size in blocks> and
297 I<filesystem block size>).
299 This uses the L<blockdev(8)> command.
301 On error this function returns -1.
303 =head2 guestfs_blockdev_getro
305 int guestfs_blockdev_getro (guestfs_h *handle,
308 Returns a boolean indicating if the block device is read-only
309 (true if read-only, false if not).
311 This uses the L<blockdev(8)> command.
313 This function returns a C truth value on success or -1 on error.
315 =head2 guestfs_blockdev_getsize64
317 int64_t guestfs_blockdev_getsize64 (guestfs_h *handle,
320 This returns the size of the device in bytes.
322 See also C<guestfs_blockdev_getsz>.
324 This uses the L<blockdev(8)> command.
326 On error this function returns -1.
328 =head2 guestfs_blockdev_getss
330 int guestfs_blockdev_getss (guestfs_h *handle,
333 This returns the size of sectors on a block device.
334 Usually 512, but can be larger for modern devices.
336 (Note, this is not the size in sectors, use C<guestfs_blockdev_getsz>
339 This uses the L<blockdev(8)> command.
341 On error this function returns -1.
343 =head2 guestfs_blockdev_getsz
345 int64_t guestfs_blockdev_getsz (guestfs_h *handle,
348 This returns the size of the device in units of 512-byte sectors
349 (even if the sectorsize isn't 512 bytes ... weird).
351 See also C<guestfs_blockdev_getss> for the real sector size of
352 the device, and C<guestfs_blockdev_getsize64> for the more
353 useful I<size in bytes>.
355 This uses the L<blockdev(8)> command.
357 On error this function returns -1.
359 =head2 guestfs_blockdev_rereadpt
361 int guestfs_blockdev_rereadpt (guestfs_h *handle,
364 Reread the partition table on C<device>.
366 This uses the L<blockdev(8)> command.
368 This function returns 0 on success or -1 on error.
370 =head2 guestfs_blockdev_setbsz
372 int guestfs_blockdev_setbsz (guestfs_h *handle,
376 This sets the block size of a device.
378 (Note this is different from both I<size in blocks> and
379 I<filesystem block size>).
381 This uses the L<blockdev(8)> command.
383 This function returns 0 on success or -1 on error.
385 =head2 guestfs_blockdev_setro
387 int guestfs_blockdev_setro (guestfs_h *handle,
390 Sets the block device named C<device> to read-only.
392 This uses the L<blockdev(8)> command.
394 This function returns 0 on success or -1 on error.
396 =head2 guestfs_blockdev_setrw
398 int guestfs_blockdev_setrw (guestfs_h *handle,
401 Sets the block device named C<device> to read-write.
403 This uses the L<blockdev(8)> command.
405 This function returns 0 on success or -1 on error.
409 char *guestfs_cat (guestfs_h *handle,
412 Return the contents of the file named C<path>.
414 Note that this function cannot correctly handle binary files
415 (specifically, files containing C<\0> character which is treated
416 as end of string). For those you need to use the C<guestfs_download>
417 function which has a more complex interface.
419 This function returns a string, or NULL on error.
420 I<The caller must free the returned string after use>.
422 Because of the message protocol, there is a transfer limit
423 of somewhere between 2MB and 4MB. To transfer large files you should use
426 =head2 guestfs_checksum
428 char *guestfs_checksum (guestfs_h *handle,
429 const char *csumtype,
432 This call computes the MD5, SHAx or CRC checksum of the
435 The type of checksum to compute is given by the C<csumtype>
436 parameter which must have one of the following values:
442 Compute the cyclic redundancy check (CRC) specified by POSIX
443 for the C<cksum> command.
447 Compute the MD5 hash (using the C<md5sum> program).
451 Compute the SHA1 hash (using the C<sha1sum> program).
455 Compute the SHA224 hash (using the C<sha224sum> program).
459 Compute the SHA256 hash (using the C<sha256sum> program).
463 Compute the SHA384 hash (using the C<sha384sum> program).
467 Compute the SHA512 hash (using the C<sha512sum> program).
471 The checksum is returned as a printable string.
473 This function returns a string, or NULL on error.
474 I<The caller must free the returned string after use>.
478 int guestfs_chmod (guestfs_h *handle,
482 Change the mode (permissions) of C<path> to C<mode>. Only
483 numeric modes are supported.
485 This function returns 0 on success or -1 on error.
489 int guestfs_chown (guestfs_h *handle,
494 Change the file owner to C<owner> and group to C<group>.
496 Only numeric uid and gid are supported. If you want to use
497 names, you will need to locate and parse the password file
498 yourself (Augeas support makes this relatively easy).
500 This function returns 0 on success or -1 on error.
502 =head2 guestfs_command
504 char *guestfs_command (guestfs_h *handle,
505 char * const* const arguments);
507 This call runs a command from the guest filesystem. The
508 filesystem must be mounted, and must contain a compatible
509 operating system (ie. something Linux, with the same
510 or compatible processor architecture).
512 The single parameter is an argv-style list of arguments.
513 The first element is the name of the program to run.
514 Subsequent elements are parameters. The list must be
515 non-empty (ie. must contain a program name). Note that
516 the command runs directly, and is I<not> invoked via
517 the shell (see C<guestfs_sh>).
519 The return value is anything printed to I<stdout> by
522 If the command returns a non-zero exit status, then
523 this function returns an error message. The error message
524 string is the content of I<stderr> from the command.
526 The C<$PATH> environment variable will contain at least
527 C</usr/bin> and C</bin>. If you require a program from
528 another location, you should provide the full path in the
531 Shared libraries and data files required by the program
532 must be available on filesystems which are mounted in the
533 correct places. It is the caller's responsibility to ensure
534 all filesystems that are needed are mounted at the right
537 This function returns a string, or NULL on error.
538 I<The caller must free the returned string after use>.
540 Because of the message protocol, there is a transfer limit
541 of somewhere between 2MB and 4MB. To transfer large files you should use
544 =head2 guestfs_command_lines
546 char **guestfs_command_lines (guestfs_h *handle,
547 char * const* const arguments);
549 This is the same as C<guestfs_command>, but splits the
550 result into a list of lines.
552 See also: C<guestfs_sh_lines>
554 This function returns a NULL-terminated array of strings
555 (like L<environ(3)>), or NULL if there was an error.
556 I<The caller must free the strings and the array after use>.
558 Because of the message protocol, there is a transfer limit
559 of somewhere between 2MB and 4MB. To transfer large files you should use
562 =head2 guestfs_config
564 int guestfs_config (guestfs_h *handle,
565 const char *qemuparam,
566 const char *qemuvalue);
568 This can be used to add arbitrary qemu command line parameters
569 of the form C<-param value>. Actually it's not quite arbitrary - we
570 prevent you from setting some parameters which would interfere with
571 parameters that we use.
573 The first character of C<param> string must be a C<-> (dash).
575 C<value> can be NULL.
577 This function returns 0 on success or -1 on error.
581 int guestfs_cp (guestfs_h *handle,
585 This copies a file from C<src> to C<dest> where C<dest> is
586 either a destination filename or destination directory.
588 This function returns 0 on success or -1 on error.
592 int guestfs_cp_a (guestfs_h *handle,
596 This copies a file or directory from C<src> to C<dest>
597 recursively using the C<cp -a> command.
599 This function returns 0 on success or -1 on error.
603 char *guestfs_debug (guestfs_h *handle,
605 char * const* const extraargs);
607 The C<guestfs_debug> command exposes some internals of
608 C<guestfsd> (the guestfs daemon) that runs inside the
611 There is no comprehensive help for this command. You have
612 to look at the file C<daemon/debug.c> in the libguestfs source
613 to find out what you can do.
615 This function returns a string, or NULL on error.
616 I<The caller must free the returned string after use>.
620 char *guestfs_df (guestfs_h *handle);
622 This command runs the C<df> command to report disk space used.
624 This command is mostly useful for interactive sessions. It
625 is I<not> intended that you try to parse the output string.
626 Use C<statvfs> from programs.
628 This function returns a string, or NULL on error.
629 I<The caller must free the returned string after use>.
633 char *guestfs_df_h (guestfs_h *handle);
635 This command runs the C<df -h> command to report disk space used
636 in human-readable format.
638 This command is mostly useful for interactive sessions. It
639 is I<not> intended that you try to parse the output string.
640 Use C<statvfs> from programs.
642 This function returns a string, or NULL on error.
643 I<The caller must free the returned string after use>.
647 char *guestfs_dmesg (guestfs_h *handle);
649 This returns the kernel messages (C<dmesg> output) from
650 the guest kernel. This is sometimes useful for extended
651 debugging of problems.
653 Another way to get the same information is to enable
654 verbose messages with C<guestfs_set_verbose> or by setting
655 the environment variable C<LIBGUESTFS_DEBUG=1> before
658 This function returns a string, or NULL on error.
659 I<The caller must free the returned string after use>.
661 =head2 guestfs_download
663 int guestfs_download (guestfs_h *handle,
664 const char *remotefilename,
665 const char *filename);
667 Download file C<remotefilename> and save it as C<filename>
668 on the local machine.
670 C<filename> can also be a named pipe.
672 See also C<guestfs_upload>, C<guestfs_cat>.
674 This function returns 0 on success or -1 on error.
676 =head2 guestfs_drop_caches
678 int guestfs_drop_caches (guestfs_h *handle,
681 This instructs the guest kernel to drop its page cache,
682 and/or dentries and inode caches. The parameter C<whattodrop>
683 tells the kernel what precisely to drop, see
684 L<http://linux-mm.org/Drop_Caches>
686 Setting C<whattodrop> to 3 should drop everything.
688 This automatically calls L<sync(2)> before the operation,
689 so that the maximum guest memory is freed.
691 This function returns 0 on success or -1 on error.
695 int64_t guestfs_du (guestfs_h *handle,
698 This command runs the C<du -s> command to estimate file space
701 C<path> can be a file or a directory. If C<path> is a directory
702 then the estimate includes the contents of the directory and all
703 subdirectories (recursively).
705 The result is the estimated size in I<kilobytes>
706 (ie. units of 1024 bytes).
708 On error this function returns -1.
710 =head2 guestfs_e2fsck_f
712 int guestfs_e2fsck_f (guestfs_h *handle,
715 This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3
716 filesystem checker on C<device>, noninteractively (C<-p>),
717 even if the filesystem appears to be clean (C<-f>).
719 This command is only needed because of C<guestfs_resize2fs>
720 (q.v.). Normally you should use C<guestfs_fsck>.
722 This function returns 0 on success or -1 on error.
724 =head2 guestfs_end_busy
726 int guestfs_end_busy (guestfs_h *handle);
728 This sets the state to C<READY>, or if in C<CONFIG> then it leaves the
729 state as is. This is only used when implementing
730 actions using the low-level API.
732 For more information on states, see L<guestfs(3)>.
734 This function returns 0 on success or -1 on error.
738 int guestfs_equal (guestfs_h *handle,
742 This compares the two files C<file1> and C<file2> and returns
743 true if their content is exactly equal, or false otherwise.
745 The external L<cmp(1)> program is used for the comparison.
747 This function returns a C truth value on success or -1 on error.
749 =head2 guestfs_exists
751 int guestfs_exists (guestfs_h *handle,
754 This returns C<true> if and only if there is a file, directory
755 (or anything) with the given C<path> name.
757 See also C<guestfs_is_file>, C<guestfs_is_dir>, C<guestfs_stat>.
759 This function returns a C truth value on success or -1 on error.
763 char *guestfs_file (guestfs_h *handle,
766 This call uses the standard L<file(1)> command to determine
767 the type or contents of the file. This also works on devices,
768 for example to find out whether a partition contains a filesystem.
770 The exact command which runs is C<file -bsL path>. Note in
771 particular that the filename is not prepended to the output
774 This function returns a string, or NULL on error.
775 I<The caller must free the returned string after use>.
779 char **guestfs_find (guestfs_h *handle,
780 const char *directory);
782 This command lists out all files and directories, recursively,
783 starting at C<directory>. It is essentially equivalent to
784 running the shell command C<find directory -print> but some
785 post-processing happens on the output, described below.
787 This returns a list of strings I<without any prefix>. Thus
788 if the directory structure was:
794 then the returned list from C<guestfs_find> C</tmp> would be
802 If C<directory> is not a directory, then this command returns
805 The returned list is sorted.
807 This function returns a NULL-terminated array of strings
808 (like L<environ(3)>), or NULL if there was an error.
809 I<The caller must free the strings and the array after use>.
813 int guestfs_fsck (guestfs_h *handle,
817 This runs the filesystem checker (fsck) on C<device> which
818 should have filesystem type C<fstype>.
820 The returned integer is the status. See L<fsck(8)> for the
821 list of status codes from C<fsck>.
829 Multiple status codes can be summed together.
833 A non-zero return code can mean "success", for example if
834 errors have been corrected on the filesystem.
838 Checking or repairing NTFS volumes is not supported
843 This command is entirely equivalent to running C<fsck -a -t fstype device>.
845 On error this function returns -1.
847 =head2 guestfs_get_append
849 const char *guestfs_get_append (guestfs_h *handle);
851 Return the additional kernel options which are added to the
852 guest kernel command line.
854 If C<NULL> then no options are added.
856 This function returns a string, or NULL on error.
857 The string is owned by the guest handle and must I<not> be freed.
859 =head2 guestfs_get_autosync
861 int guestfs_get_autosync (guestfs_h *handle);
863 Get the autosync flag.
865 This function returns a C truth value on success or -1 on error.
867 =head2 guestfs_get_e2label
869 char *guestfs_get_e2label (guestfs_h *handle,
872 This returns the ext2/3/4 filesystem label of the filesystem on
875 This function returns a string, or NULL on error.
876 I<The caller must free the returned string after use>.
878 =head2 guestfs_get_e2uuid
880 char *guestfs_get_e2uuid (guestfs_h *handle,
883 This returns the ext2/3/4 filesystem UUID of the filesystem on
886 This function returns a string, or NULL on error.
887 I<The caller must free the returned string after use>.
889 =head2 guestfs_get_memsize
891 int guestfs_get_memsize (guestfs_h *handle);
893 This gets the memory size in megabytes allocated to the
896 If C<guestfs_set_memsize> was not called
897 on this handle, and if C<LIBGUESTFS_MEMSIZE> was not set,
898 then this returns the compiled-in default value for memsize.
900 For more information on the architecture of libguestfs,
903 On error this function returns -1.
905 =head2 guestfs_get_path
907 const char *guestfs_get_path (guestfs_h *handle);
909 Return the current search path.
911 This is always non-NULL. If it wasn't set already, then this will
912 return the default path.
914 This function returns a string, or NULL on error.
915 The string is owned by the guest handle and must I<not> be freed.
917 =head2 guestfs_get_qemu
919 const char *guestfs_get_qemu (guestfs_h *handle);
921 Return the current qemu binary.
923 This is always non-NULL. If it wasn't set already, then this will
924 return the default qemu binary name.
926 This function returns a string, or NULL on error.
927 The string is owned by the guest handle and must I<not> be freed.
929 =head2 guestfs_get_state
931 int guestfs_get_state (guestfs_h *handle);
933 This returns the current state as an opaque integer. This is
934 only useful for printing debug and internal error messages.
936 For more information on states, see L<guestfs(3)>.
938 On error this function returns -1.
940 =head2 guestfs_get_verbose
942 int guestfs_get_verbose (guestfs_h *handle);
944 This returns the verbose messages flag.
946 This function returns a C truth value on success or -1 on error.
948 =head2 guestfs_glob_expand
950 char **guestfs_glob_expand (guestfs_h *handle,
951 const char *pattern);
953 This command searches for all the pathnames matching
954 C<pattern> according to the wildcard expansion rules
957 If no paths match, then this returns an empty list
958 (note: not an error).
960 It is just a wrapper around the C L<glob(3)> function
961 with flags C<GLOB_MARK|GLOB_BRACE>.
962 See that manual page for more details.
964 This function returns a NULL-terminated array of strings
965 (like L<environ(3)>), or NULL if there was an error.
966 I<The caller must free the strings and the array after use>.
968 =head2 guestfs_grub_install
970 int guestfs_grub_install (guestfs_h *handle,
974 This command installs GRUB (the Grand Unified Bootloader) on
975 C<device>, with the root directory being C<root>.
977 This function returns 0 on success or -1 on error.
981 char **guestfs_head (guestfs_h *handle,
984 This command returns up to the first 10 lines of a file as
987 This function returns a NULL-terminated array of strings
988 (like L<environ(3)>), or NULL if there was an error.
989 I<The caller must free the strings and the array after use>.
991 Because of the message protocol, there is a transfer limit
992 of somewhere between 2MB and 4MB. To transfer large files you should use
995 =head2 guestfs_head_n
997 char **guestfs_head_n (guestfs_h *handle,
1001 If the parameter C<nrlines> is a positive number, this returns the first
1002 C<nrlines> lines of the file C<path>.
1004 If the parameter C<nrlines> is a negative number, this returns lines
1005 from the file C<path>, excluding the last C<nrlines> lines.
1007 If the parameter C<nrlines> is zero, this returns an empty list.
1009 This function returns a NULL-terminated array of strings
1010 (like L<environ(3)>), or NULL if there was an error.
1011 I<The caller must free the strings and the array after use>.
1013 Because of the message protocol, there is a transfer limit
1014 of somewhere between 2MB and 4MB. To transfer large files you should use
1017 =head2 guestfs_hexdump
1019 char *guestfs_hexdump (guestfs_h *handle,
1022 This runs C<hexdump -C> on the given C<path>. The result is
1023 the human-readable, canonical hex dump of the file.
1025 This function returns a string, or NULL on error.
1026 I<The caller must free the returned string after use>.
1028 Because of the message protocol, there is a transfer limit
1029 of somewhere between 2MB and 4MB. To transfer large files you should use
1032 =head2 guestfs_initrd_list
1034 char **guestfs_initrd_list (guestfs_h *handle,
1037 This command lists out files contained in an initrd.
1039 The files are listed without any initial C</> character. The
1040 files are listed in the order they appear (not necessarily
1041 alphabetical). Directory names are listed as separate items.
1043 Old Linux kernels (2.4 and earlier) used a compressed ext2
1044 filesystem as initrd. We I<only> support the newer initramfs
1045 format (compressed cpio files).
1047 This function returns a NULL-terminated array of strings
1048 (like L<environ(3)>), or NULL if there was an error.
1049 I<The caller must free the strings and the array after use>.
1051 =head2 guestfs_is_busy
1053 int guestfs_is_busy (guestfs_h *handle);
1055 This returns true iff this handle is busy processing a command
1056 (in the C<BUSY> state).
1058 For more information on states, see L<guestfs(3)>.
1060 This function returns a C truth value on success or -1 on error.
1062 =head2 guestfs_is_config
1064 int guestfs_is_config (guestfs_h *handle);
1066 This returns true iff this handle is being configured
1067 (in the C<CONFIG> state).
1069 For more information on states, see L<guestfs(3)>.
1071 This function returns a C truth value on success or -1 on error.
1073 =head2 guestfs_is_dir
1075 int guestfs_is_dir (guestfs_h *handle,
1078 This returns C<true> if and only if there is a directory
1079 with the given C<path> name. Note that it returns false for
1080 other objects like files.
1082 See also C<guestfs_stat>.
1084 This function returns a C truth value on success or -1 on error.
1086 =head2 guestfs_is_file
1088 int guestfs_is_file (guestfs_h *handle,
1091 This returns C<true> if and only if there is a file
1092 with the given C<path> name. Note that it returns false for
1093 other objects like directories.
1095 See also C<guestfs_stat>.
1097 This function returns a C truth value on success or -1 on error.
1099 =head2 guestfs_is_launching
1101 int guestfs_is_launching (guestfs_h *handle);
1103 This returns true iff this handle is launching the subprocess
1104 (in the C<LAUNCHING> state).
1106 For more information on states, see L<guestfs(3)>.
1108 This function returns a C truth value on success or -1 on error.
1110 =head2 guestfs_is_ready
1112 int guestfs_is_ready (guestfs_h *handle);
1114 This returns true iff this handle is ready to accept commands
1115 (in the C<READY> state).
1117 For more information on states, see L<guestfs(3)>.
1119 This function returns a C truth value on success or -1 on error.
1121 =head2 guestfs_kill_subprocess
1123 int guestfs_kill_subprocess (guestfs_h *handle);
1125 This kills the qemu subprocess. You should never need to call this.
1127 This function returns 0 on success or -1 on error.
1129 =head2 guestfs_launch
1131 int guestfs_launch (guestfs_h *handle);
1133 Internally libguestfs is implemented by running a virtual machine
1136 You should call this after configuring the handle
1137 (eg. adding drives) but before performing any actions.
1139 This function returns 0 on success or -1 on error.
1141 =head2 guestfs_list_devices
1143 char **guestfs_list_devices (guestfs_h *handle);
1145 List all the block devices.
1147 The full block device names are returned, eg. C</dev/sda>
1149 This function returns a NULL-terminated array of strings
1150 (like L<environ(3)>), or NULL if there was an error.
1151 I<The caller must free the strings and the array after use>.
1153 =head2 guestfs_list_partitions
1155 char **guestfs_list_partitions (guestfs_h *handle);
1157 List all the partitions detected on all block devices.
1159 The full partition device names are returned, eg. C</dev/sda1>
1161 This does not return logical volumes. For that you will need to
1162 call C<guestfs_lvs>.
1164 This function returns a NULL-terminated array of strings
1165 (like L<environ(3)>), or NULL if there was an error.
1166 I<The caller must free the strings and the array after use>.
1170 char *guestfs_ll (guestfs_h *handle,
1171 const char *directory);
1173 List the files in C<directory> (relative to the root directory,
1174 there is no cwd) in the format of 'ls -la'.
1176 This command is mostly useful for interactive sessions. It
1177 is I<not> intended that you try to parse the output string.
1179 This function returns a string, or NULL on error.
1180 I<The caller must free the returned string after use>.
1184 char **guestfs_ls (guestfs_h *handle,
1185 const char *directory);
1187 List the files in C<directory> (relative to the root directory,
1188 there is no cwd). The '.' and '..' entries are not returned, but
1189 hidden files are shown.
1191 This command is mostly useful for interactive sessions. Programs
1192 should probably use C<guestfs_readdir> instead.
1194 This function returns a NULL-terminated array of strings
1195 (like L<environ(3)>), or NULL if there was an error.
1196 I<The caller must free the strings and the array after use>.
1198 =head2 guestfs_lstat
1200 struct guestfs_stat *guestfs_lstat (guestfs_h *handle,
1203 Returns file information for the given C<path>.
1205 This is the same as C<guestfs_stat> except that if C<path>
1206 is a symbolic link, then the link is stat-ed, not the file it
1209 This is the same as the C<lstat(2)> system call.
1211 This function returns a C<struct guestfs_stat *>
1212 (see L<stat(2)> and E<lt>guestfs-structs.hE<gt>),
1213 or NULL if there was an error.
1214 I<The caller must call C<free> after use>.
1216 =head2 guestfs_lvcreate
1218 int guestfs_lvcreate (guestfs_h *handle,
1220 const char *volgroup,
1223 This creates an LVM volume group called C<logvol>
1224 on the volume group C<volgroup>, with C<size> megabytes.
1226 This function returns 0 on success or -1 on error.
1228 =head2 guestfs_lvm_remove_all
1230 int guestfs_lvm_remove_all (guestfs_h *handle);
1232 This command removes all LVM logical volumes, volume groups
1233 and physical volumes.
1235 This function returns 0 on success or -1 on error.
1237 B<This command is dangerous. Without careful use you
1238 can easily destroy all your data>.
1240 =head2 guestfs_lvremove
1242 int guestfs_lvremove (guestfs_h *handle,
1243 const char *device);
1245 Remove an LVM logical volume C<device>, where C<device> is
1246 the path to the LV, such as C</dev/VG/LV>.
1248 You can also remove all LVs in a volume group by specifying
1249 the VG name, C</dev/VG>.
1251 This function returns 0 on success or -1 on error.
1253 =head2 guestfs_lvresize
1255 int guestfs_lvresize (guestfs_h *handle,
1259 This resizes (expands or shrinks) an existing LVM logical
1260 volume to C<mbytes>. When reducing, data in the reduced part
1263 This function returns 0 on success or -1 on error.
1267 char **guestfs_lvs (guestfs_h *handle);
1269 List all the logical volumes detected. This is the equivalent
1270 of the L<lvs(8)> command.
1272 This returns a list of the logical volume device names
1273 (eg. C</dev/VolGroup00/LogVol00>).
1275 See also C<guestfs_lvs_full>.
1277 This function returns a NULL-terminated array of strings
1278 (like L<environ(3)>), or NULL if there was an error.
1279 I<The caller must free the strings and the array after use>.
1281 =head2 guestfs_lvs_full
1283 struct guestfs_lvm_lv_list *guestfs_lvs_full (guestfs_h *handle);
1285 List all the logical volumes detected. This is the equivalent
1286 of the L<lvs(8)> command. The "full" version includes all fields.
1288 This function returns a C<struct guestfs_lvm_lv_list *>
1289 (see E<lt>guestfs-structs.hE<gt>),
1290 or NULL if there was an error.
1291 I<The caller must call C<guestfs_free_lvm_lv_list> after use>.
1293 =head2 guestfs_mkdir
1295 int guestfs_mkdir (guestfs_h *handle,
1298 Create a directory named C<path>.
1300 This function returns 0 on success or -1 on error.
1302 =head2 guestfs_mkdir_p
1304 int guestfs_mkdir_p (guestfs_h *handle,
1307 Create a directory named C<path>, creating any parent directories
1308 as necessary. This is like the C<mkdir -p> shell command.
1310 This function returns 0 on success or -1 on error.
1312 =head2 guestfs_mkdtemp
1314 char *guestfs_mkdtemp (guestfs_h *handle,
1315 const char *template);
1317 This command creates a temporary directory. The
1318 C<template> parameter should be a full pathname for the
1319 temporary directory name with the final six characters being
1322 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX",
1323 the second one being suitable for Windows filesystems.
1325 The name of the temporary directory that was created
1328 The temporary directory is created with mode 0700
1329 and is owned by root.
1331 The caller is responsible for deleting the temporary
1332 directory and its contents after use.
1334 See also: L<mkdtemp(3)>
1336 This function returns a string, or NULL on error.
1337 I<The caller must free the returned string after use>.
1339 =head2 guestfs_mkfifo
1341 int guestfs_mkfifo (guestfs_h *handle,
1345 This call creates a FIFO (named pipe) called C<path> with
1346 mode C<mode>. It is just a convenient wrapper around
1349 This function returns 0 on success or -1 on error.
1353 int guestfs_mkfs (guestfs_h *handle,
1355 const char *device);
1357 This creates a filesystem on C<device> (usually a partition
1358 or LVM logical volume). The filesystem type is C<fstype>, for
1361 This function returns 0 on success or -1 on error.
1363 =head2 guestfs_mknod
1365 int guestfs_mknod (guestfs_h *handle,
1371 This call creates block or character special devices, or
1372 named pipes (FIFOs).
1374 The C<mode> parameter should be the mode, using the standard
1375 constants. C<devmajor> and C<devminor> are the
1376 device major and minor numbers, only used when creating block
1377 and character special devices.
1379 This function returns 0 on success or -1 on error.
1381 =head2 guestfs_mknod_b
1383 int guestfs_mknod_b (guestfs_h *handle,
1389 This call creates a block device node called C<path> with
1390 mode C<mode> and device major/minor C<devmajor> and C<devminor>.
1391 It is just a convenient wrapper around C<guestfs_mknod>.
1393 This function returns 0 on success or -1 on error.
1395 =head2 guestfs_mknod_c
1397 int guestfs_mknod_c (guestfs_h *handle,
1403 This call creates a char device node called C<path> with
1404 mode C<mode> and device major/minor C<devmajor> and C<devminor>.
1405 It is just a convenient wrapper around C<guestfs_mknod>.
1407 This function returns 0 on success or -1 on error.
1409 =head2 guestfs_mkswap
1411 int guestfs_mkswap (guestfs_h *handle,
1412 const char *device);
1414 Create a swap partition on C<device>.
1416 This function returns 0 on success or -1 on error.
1418 =head2 guestfs_mkswap_L
1420 int guestfs_mkswap_L (guestfs_h *handle,
1422 const char *device);
1424 Create a swap partition on C<device> with label C<label>.
1426 This function returns 0 on success or -1 on error.
1428 =head2 guestfs_mkswap_U
1430 int guestfs_mkswap_U (guestfs_h *handle,
1432 const char *device);
1434 Create a swap partition on C<device> with UUID C<uuid>.
1436 This function returns 0 on success or -1 on error.
1438 =head2 guestfs_mount
1440 int guestfs_mount (guestfs_h *handle,
1442 const char *mountpoint);
1444 Mount a guest disk at a position in the filesystem. Block devices
1445 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
1446 the guest. If those block devices contain partitions, they will have
1447 the usual names (eg. C</dev/sda1>). Also LVM C</dev/VG/LV>-style
1450 The rules are the same as for L<mount(2)>: A filesystem must
1451 first be mounted on C</> before others can be mounted. Other
1452 filesystems can only be mounted on directories which already
1455 The mounted filesystem is writable, if we have sufficient permissions
1456 on the underlying device.
1458 The filesystem options C<sync> and C<noatime> are set with this
1459 call, in order to improve reliability.
1461 This function returns 0 on success or -1 on error.
1463 =head2 guestfs_mount_loop
1465 int guestfs_mount_loop (guestfs_h *handle,
1467 const char *mountpoint);
1469 This command lets you mount C<file> (a filesystem image
1470 in a file) on a mount point. It is entirely equivalent to
1471 the command C<mount -o loop file mountpoint>.
1473 This function returns 0 on success or -1 on error.
1475 =head2 guestfs_mount_options
1477 int guestfs_mount_options (guestfs_h *handle,
1478 const char *options,
1480 const char *mountpoint);
1482 This is the same as the C<guestfs_mount> command, but it
1483 allows you to set the mount options as for the
1484 L<mount(8)> I<-o> flag.
1486 This function returns 0 on success or -1 on error.
1488 =head2 guestfs_mount_ro
1490 int guestfs_mount_ro (guestfs_h *handle,
1492 const char *mountpoint);
1494 This is the same as the C<guestfs_mount> command, but it
1495 mounts the filesystem with the read-only (I<-o ro>) flag.
1497 This function returns 0 on success or -1 on error.
1499 =head2 guestfs_mount_vfs
1501 int guestfs_mount_vfs (guestfs_h *handle,
1502 const char *options,
1503 const char *vfstype,
1505 const char *mountpoint);
1507 This is the same as the C<guestfs_mount> command, but it
1508 allows you to set both the mount options and the vfstype
1509 as for the L<mount(8)> I<-o> and I<-t> flags.
1511 This function returns 0 on success or -1 on error.
1513 =head2 guestfs_mounts
1515 char **guestfs_mounts (guestfs_h *handle);
1517 This returns the list of currently mounted filesystems. It returns
1518 the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
1520 Some internal mounts are not shown.
1522 This function returns a NULL-terminated array of strings
1523 (like L<environ(3)>), or NULL if there was an error.
1524 I<The caller must free the strings and the array after use>.
1528 int guestfs_mv (guestfs_h *handle,
1532 This moves a file from C<src> to C<dest> where C<dest> is
1533 either a destination filename or destination directory.
1535 This function returns 0 on success or -1 on error.
1537 =head2 guestfs_ntfs_3g_probe
1539 int guestfs_ntfs_3g_probe (guestfs_h *handle,
1541 const char *device);
1543 This command runs the L<ntfs-3g.probe(8)> command which probes
1544 an NTFS C<device> for mountability. (Not all NTFS volumes can
1545 be mounted read-write, and some cannot be mounted at all).
1547 C<rw> is a boolean flag. Set it to true if you want to test
1548 if the volume can be mounted read-write. Set it to false if
1549 you want to test if the volume can be mounted read-only.
1551 The return value is an integer which C<0> if the operation
1552 would succeed, or some non-zero value documented in the
1553 L<ntfs-3g.probe(8)> manual page.
1555 On error this function returns -1.
1557 =head2 guestfs_ping_daemon
1559 int guestfs_ping_daemon (guestfs_h *handle);
1561 This is a test probe into the guestfs daemon running inside
1562 the qemu subprocess. Calling this function checks that the
1563 daemon responds to the ping message, without affecting the daemon
1564 or attached block device(s) in any other way.
1566 This function returns 0 on success or -1 on error.
1568 =head2 guestfs_pvcreate
1570 int guestfs_pvcreate (guestfs_h *handle,
1571 const char *device);
1573 This creates an LVM physical volume on the named C<device>,
1574 where C<device> should usually be a partition name such
1577 This function returns 0 on success or -1 on error.
1579 =head2 guestfs_pvremove
1581 int guestfs_pvremove (guestfs_h *handle,
1582 const char *device);
1584 This wipes a physical volume C<device> so that LVM will no longer
1587 The implementation uses the C<pvremove> command which refuses to
1588 wipe physical volumes that contain any volume groups, so you have
1589 to remove those first.
1591 This function returns 0 on success or -1 on error.
1593 =head2 guestfs_pvresize
1595 int guestfs_pvresize (guestfs_h *handle,
1596 const char *device);
1598 This resizes (expands or shrinks) an existing LVM physical
1599 volume to match the new size of the underlying device.
1601 This function returns 0 on success or -1 on error.
1605 char **guestfs_pvs (guestfs_h *handle);
1607 List all the physical volumes detected. This is the equivalent
1608 of the L<pvs(8)> command.
1610 This returns a list of just the device names that contain
1611 PVs (eg. C</dev/sda2>).
1613 See also C<guestfs_pvs_full>.
1615 This function returns a NULL-terminated array of strings
1616 (like L<environ(3)>), or NULL if there was an error.
1617 I<The caller must free the strings and the array after use>.
1619 =head2 guestfs_pvs_full
1621 struct guestfs_lvm_pv_list *guestfs_pvs_full (guestfs_h *handle);
1623 List all the physical volumes detected. This is the equivalent
1624 of the L<pvs(8)> command. The "full" version includes all fields.
1626 This function returns a C<struct guestfs_lvm_pv_list *>
1627 (see E<lt>guestfs-structs.hE<gt>),
1628 or NULL if there was an error.
1629 I<The caller must call C<guestfs_free_lvm_pv_list> after use>.
1631 =head2 guestfs_read_lines
1633 char **guestfs_read_lines (guestfs_h *handle,
1636 Return the contents of the file named C<path>.
1638 The file contents are returned as a list of lines. Trailing
1639 C<LF> and C<CRLF> character sequences are I<not> returned.
1641 Note that this function cannot correctly handle binary files
1642 (specifically, files containing C<\0> character which is treated
1643 as end of line). For those you need to use the C<guestfs_read_file>
1644 function which has a more complex interface.
1646 This function returns a NULL-terminated array of strings
1647 (like L<environ(3)>), or NULL if there was an error.
1648 I<The caller must free the strings and the array after use>.
1650 =head2 guestfs_resize2fs
1652 int guestfs_resize2fs (guestfs_h *handle,
1653 const char *device);
1655 This resizes an ext2 or ext3 filesystem to match the size of
1656 the underlying device.
1658 I<Note:> It is sometimes required that you run C<guestfs_e2fsck_f>
1659 on the C<device> before calling this command. For unknown reasons
1660 C<resize2fs> sometimes gives an error about this and sometimes not.
1661 In any case, it is always safe to call C<guestfs_e2fsck_f> before
1662 calling this function.
1664 This function returns 0 on success or -1 on error.
1668 int guestfs_rm (guestfs_h *handle,
1671 Remove the single file C<path>.
1673 This function returns 0 on success or -1 on error.
1675 =head2 guestfs_rm_rf
1677 int guestfs_rm_rf (guestfs_h *handle,
1680 Remove the file or directory C<path>, recursively removing the
1681 contents if its a directory. This is like the C<rm -rf> shell
1684 This function returns 0 on success or -1 on error.
1686 =head2 guestfs_rmdir
1688 int guestfs_rmdir (guestfs_h *handle,
1691 Remove the single directory C<path>.
1693 This function returns 0 on success or -1 on error.
1695 =head2 guestfs_scrub_device
1697 int guestfs_scrub_device (guestfs_h *handle,
1698 const char *device);
1700 This command writes patterns over C<device> to make data retrieval
1703 It is an interface to the L<scrub(1)> program. See that
1704 manual page for more details.
1706 This function returns 0 on success or -1 on error.
1708 B<This command is dangerous. Without careful use you
1709 can easily destroy all your data>.
1711 =head2 guestfs_scrub_file
1713 int guestfs_scrub_file (guestfs_h *handle,
1716 This command writes patterns over a file to make data retrieval
1719 The file is I<removed> after scrubbing.
1721 It is an interface to the L<scrub(1)> program. See that
1722 manual page for more details.
1724 This function returns 0 on success or -1 on error.
1726 =head2 guestfs_scrub_freespace
1728 int guestfs_scrub_freespace (guestfs_h *handle,
1731 This command creates the directory C<dir> and then fills it
1732 with files until the filesystem is full, and scrubs the files
1733 as for C<guestfs_scrub_file>, and deletes them.
1734 The intention is to scrub any free space on the partition
1737 It is an interface to the L<scrub(1)> program. See that
1738 manual page for more details.
1740 This function returns 0 on success or -1 on error.
1742 =head2 guestfs_set_append
1744 int guestfs_set_append (guestfs_h *handle,
1745 const char *append);
1747 This function is used to add additional options to the
1748 guest kernel command line.
1750 The default is C<NULL> unless overridden by setting
1751 C<LIBGUESTFS_APPEND> environment variable.
1753 Setting C<append> to C<NULL> means I<no> additional options
1754 are passed (libguestfs always adds a few of its own).
1756 This function returns 0 on success or -1 on error.
1758 =head2 guestfs_set_autosync
1760 int guestfs_set_autosync (guestfs_h *handle,
1763 If C<autosync> is true, this enables autosync. Libguestfs will make a
1764 best effort attempt to run C<guestfs_umount_all> followed by
1765 C<guestfs_sync> when the handle is closed
1766 (also if the program exits without closing handles).
1768 This is disabled by default (except in guestfish where it is
1769 enabled by default).
1771 This function returns 0 on success or -1 on error.
1773 =head2 guestfs_set_busy
1775 int guestfs_set_busy (guestfs_h *handle);
1777 This sets the state to C<BUSY>. This is only used when implementing
1778 actions using the low-level API.
1780 For more information on states, see L<guestfs(3)>.
1782 This function returns 0 on success or -1 on error.
1784 =head2 guestfs_set_e2label
1786 int guestfs_set_e2label (guestfs_h *handle,
1790 This sets the ext2/3/4 filesystem label of the filesystem on
1791 C<device> to C<label>. Filesystem labels are limited to
1794 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2label>
1795 to return the existing label on a filesystem.
1797 This function returns 0 on success or -1 on error.
1799 =head2 guestfs_set_e2uuid
1801 int guestfs_set_e2uuid (guestfs_h *handle,
1805 This sets the ext2/3/4 filesystem UUID of the filesystem on
1806 C<device> to C<uuid>. The format of the UUID and alternatives
1807 such as C<clear>, C<random> and C<time> are described in the
1808 L<tune2fs(8)> manpage.
1810 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2uuid>
1811 to return the existing UUID of a filesystem.
1813 This function returns 0 on success or -1 on error.
1815 =head2 guestfs_set_memsize
1817 int guestfs_set_memsize (guestfs_h *handle,
1820 This sets the memory size in megabytes allocated to the
1821 qemu subprocess. This only has any effect if called before
1824 You can also change this by setting the environment
1825 variable C<LIBGUESTFS_MEMSIZE> before the handle is
1828 For more information on the architecture of libguestfs,
1831 This function returns 0 on success or -1 on error.
1833 =head2 guestfs_set_path
1835 int guestfs_set_path (guestfs_h *handle,
1838 Set the path that libguestfs searches for kernel and initrd.img.
1840 The default is C<$libdir/guestfs> unless overridden by setting
1841 C<LIBGUESTFS_PATH> environment variable.
1843 Setting C<path> to C<NULL> restores the default path.
1845 This function returns 0 on success or -1 on error.
1847 =head2 guestfs_set_qemu
1849 int guestfs_set_qemu (guestfs_h *handle,
1852 Set the qemu binary that we will use.
1854 The default is chosen when the library was compiled by the
1857 You can also override this by setting the C<LIBGUESTFS_QEMU>
1858 environment variable.
1860 Setting C<qemu> to C<NULL> restores the default qemu binary.
1862 This function returns 0 on success or -1 on error.
1864 =head2 guestfs_set_ready
1866 int guestfs_set_ready (guestfs_h *handle);
1868 This sets the state to C<READY>. This is only used when implementing
1869 actions using the low-level API.
1871 For more information on states, see L<guestfs(3)>.
1873 This function returns 0 on success or -1 on error.
1875 =head2 guestfs_set_verbose
1877 int guestfs_set_verbose (guestfs_h *handle,
1880 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
1882 Verbose messages are disabled unless the environment variable
1883 C<LIBGUESTFS_DEBUG> is defined and set to C<1>.
1885 This function returns 0 on success or -1 on error.
1887 =head2 guestfs_sfdisk
1889 int guestfs_sfdisk (guestfs_h *handle,
1894 char * const* const lines);
1896 This is a direct interface to the L<sfdisk(8)> program for creating
1897 partitions on block devices.
1899 C<device> should be a block device, for example C</dev/sda>.
1901 C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads
1902 and sectors on the device, which are passed directly to sfdisk as
1903 the I<-C>, I<-H> and I<-S> parameters. If you pass C<0> for any
1904 of these, then the corresponding parameter is omitted. Usually for
1905 'large' disks, you can just pass C<0> for these, but for small
1906 (floppy-sized) disks, sfdisk (or rather, the kernel) cannot work
1907 out the right geometry and you will need to tell it.
1909 C<lines> is a list of lines that we feed to C<sfdisk>. For more
1910 information refer to the L<sfdisk(8)> manpage.
1912 To create a single partition occupying the whole disk, you would
1913 pass C<lines> as a single element list, when the single element being
1914 the string C<,> (comma).
1916 See also: C<guestfs_sfdisk_l>, C<guestfs_sfdisk_N>
1918 This function returns 0 on success or -1 on error.
1920 B<This command is dangerous. Without careful use you
1921 can easily destroy all your data>.
1923 =head2 guestfs_sfdisk_N
1925 int guestfs_sfdisk_N (guestfs_h *handle,
1933 This runs L<sfdisk(8)> option to modify just the single
1934 partition C<n> (note: C<n> counts from 1).
1936 For other parameters, see C<guestfs_sfdisk>. You should usually
1937 pass C<0> for the cyls/heads/sectors parameters.
1939 This function returns 0 on success or -1 on error.
1941 B<This command is dangerous. Without careful use you
1942 can easily destroy all your data>.
1944 =head2 guestfs_sfdisk_disk_geometry
1946 char *guestfs_sfdisk_disk_geometry (guestfs_h *handle,
1947 const char *device);
1949 This displays the disk geometry of C<device> read from the
1950 partition table. Especially in the case where the underlying
1951 block device has been resized, this can be different from the
1952 kernel's idea of the geometry (see C<guestfs_sfdisk_kernel_geometry>).
1954 The result is in human-readable format, and not designed to
1957 This function returns a string, or NULL on error.
1958 I<The caller must free the returned string after use>.
1960 =head2 guestfs_sfdisk_kernel_geometry
1962 char *guestfs_sfdisk_kernel_geometry (guestfs_h *handle,
1963 const char *device);
1965 This displays the kernel's idea of the geometry of C<device>.
1967 The result is in human-readable format, and not designed to
1970 This function returns a string, or NULL on error.
1971 I<The caller must free the returned string after use>.
1973 =head2 guestfs_sfdisk_l
1975 char *guestfs_sfdisk_l (guestfs_h *handle,
1976 const char *device);
1978 This displays the partition table on C<device>, in the
1979 human-readable output of the L<sfdisk(8)> command. It is
1980 not intended to be parsed.
1982 This function returns a string, or NULL on error.
1983 I<The caller must free the returned string after use>.
1987 char *guestfs_sh (guestfs_h *handle,
1988 const char *command);
1990 This call runs a command from the guest filesystem via the
1993 This is like C<guestfs_command>, but passes the command to:
1995 /bin/sh -c "command"
1997 Depending on the guest's shell, this usually results in
1998 wildcards being expanded, shell expressions being interpolated
2001 All the provisos about C<guestfs_command> apply to this call.
2003 This function returns a string, or NULL on error.
2004 I<The caller must free the returned string after use>.
2006 =head2 guestfs_sh_lines
2008 char **guestfs_sh_lines (guestfs_h *handle,
2009 const char *command);
2011 This is the same as C<guestfs_sh>, but splits the result
2012 into a list of lines.
2014 See also: C<guestfs_command_lines>
2016 This function returns a NULL-terminated array of strings
2017 (like L<environ(3)>), or NULL if there was an error.
2018 I<The caller must free the strings and the array after use>.
2020 =head2 guestfs_sleep
2022 int guestfs_sleep (guestfs_h *handle,
2025 Sleep for C<secs> seconds.
2027 This function returns 0 on success or -1 on error.
2031 struct guestfs_stat *guestfs_stat (guestfs_h *handle,
2034 Returns file information for the given C<path>.
2036 This is the same as the C<stat(2)> system call.
2038 This function returns a C<struct guestfs_stat *>
2039 (see L<stat(2)> and E<lt>guestfs-structs.hE<gt>),
2040 or NULL if there was an error.
2041 I<The caller must call C<free> after use>.
2043 =head2 guestfs_statvfs
2045 struct guestfs_statvfs *guestfs_statvfs (guestfs_h *handle,
2048 Returns file system statistics for any mounted file system.
2049 C<path> should be a file or directory in the mounted file system
2050 (typically it is the mount point itself, but it doesn't need to be).
2052 This is the same as the C<statvfs(2)> system call.
2054 This function returns a C<struct guestfs_statvfs *>
2055 (see L<statvfs(2)> and E<lt>guestfs-structs.hE<gt>),
2056 or NULL if there was an error.
2057 I<The caller must call C<free> after use>.
2059 =head2 guestfs_strings
2061 char **guestfs_strings (guestfs_h *handle,
2064 This runs the L<strings(1)> command on a file and returns
2065 the list of printable strings found.
2067 This function returns a NULL-terminated array of strings
2068 (like L<environ(3)>), or NULL if there was an error.
2069 I<The caller must free the strings and the array after use>.
2071 Because of the message protocol, there is a transfer limit
2072 of somewhere between 2MB and 4MB. To transfer large files you should use
2075 =head2 guestfs_strings_e
2077 char **guestfs_strings_e (guestfs_h *handle,
2078 const char *encoding,
2081 This is like the C<guestfs_strings> command, but allows you to
2082 specify the encoding.
2084 See the L<strings(1)> manpage for the full list of encodings.
2086 Commonly useful encodings are C<l> (lower case L) which will
2087 show strings inside Windows/x86 files.
2089 The returned strings are transcoded to UTF-8.
2091 This function returns a NULL-terminated array of strings
2092 (like L<environ(3)>), or NULL if there was an error.
2093 I<The caller must free the strings and the array after use>.
2095 Because of the message protocol, there is a transfer limit
2096 of somewhere between 2MB and 4MB. To transfer large files you should use
2101 int guestfs_sync (guestfs_h *handle);
2103 This syncs the disk, so that any writes are flushed through to the
2104 underlying disk image.
2106 You should always call this if you have modified a disk image, before
2109 This function returns 0 on success or -1 on error.
2113 char **guestfs_tail (guestfs_h *handle,
2116 This command returns up to the last 10 lines of a file as
2119 This function returns a NULL-terminated array of strings
2120 (like L<environ(3)>), or NULL if there was an error.
2121 I<The caller must free the strings and the array after use>.
2123 Because of the message protocol, there is a transfer limit
2124 of somewhere between 2MB and 4MB. To transfer large files you should use
2127 =head2 guestfs_tail_n
2129 char **guestfs_tail_n (guestfs_h *handle,
2133 If the parameter C<nrlines> is a positive number, this returns the last
2134 C<nrlines> lines of the file C<path>.
2136 If the parameter C<nrlines> is a negative number, this returns lines
2137 from the file C<path>, starting with the C<-nrlines>th line.
2139 If the parameter C<nrlines> is zero, this returns an empty list.
2141 This function returns a NULL-terminated array of strings
2142 (like L<environ(3)>), or NULL if there was an error.
2143 I<The caller must free the strings and the array after use>.
2145 Because of the message protocol, there is a transfer limit
2146 of somewhere between 2MB and 4MB. To transfer large files you should use
2149 =head2 guestfs_tar_in
2151 int guestfs_tar_in (guestfs_h *handle,
2152 const char *tarfile,
2153 const char *directory);
2155 This command uploads and unpacks local file C<tarfile> (an
2156 I<uncompressed> tar file) into C<directory>.
2158 To upload a compressed tarball, use C<guestfs_tgz_in>.
2160 This function returns 0 on success or -1 on error.
2162 =head2 guestfs_tar_out
2164 int guestfs_tar_out (guestfs_h *handle,
2165 const char *directory,
2166 const char *tarfile);
2168 This command packs the contents of C<directory> and downloads
2169 it to local file C<tarfile>.
2171 To download a compressed tarball, use C<guestfs_tgz_out>.
2173 This function returns 0 on success or -1 on error.
2175 =head2 guestfs_tgz_in
2177 int guestfs_tgz_in (guestfs_h *handle,
2178 const char *tarball,
2179 const char *directory);
2181 This command uploads and unpacks local file C<tarball> (a
2182 I<gzip compressed> tar file) into C<directory>.
2184 To upload an uncompressed tarball, use C<guestfs_tar_in>.
2186 This function returns 0 on success or -1 on error.
2188 =head2 guestfs_tgz_out
2190 int guestfs_tgz_out (guestfs_h *handle,
2191 const char *directory,
2192 const char *tarball);
2194 This command packs the contents of C<directory> and downloads
2195 it to local file C<tarball>.
2197 To download an uncompressed tarball, use C<guestfs_tar_out>.
2199 This function returns 0 on success or -1 on error.
2201 =head2 guestfs_touch
2203 int guestfs_touch (guestfs_h *handle,
2206 Touch acts like the L<touch(1)> command. It can be used to
2207 update the timestamps on a file, or, if the file does not exist,
2208 to create a new zero-length file.
2210 This function returns 0 on success or -1 on error.
2212 =head2 guestfs_tune2fs_l
2214 char **guestfs_tune2fs_l (guestfs_h *handle,
2215 const char *device);
2217 This returns the contents of the ext2, ext3 or ext4 filesystem
2218 superblock on C<device>.
2220 It is the same as running C<tune2fs -l device>. See L<tune2fs(8)>
2221 manpage for more details. The list of fields returned isn't
2222 clearly defined, and depends on both the version of C<tune2fs>
2223 that libguestfs was built against, and the filesystem itself.
2225 This function returns a NULL-terminated array of
2226 strings, or NULL if there was an error.
2227 The array of strings will always have length C<2n+1>, where
2228 C<n> keys and values alternate, followed by the trailing NULL entry.
2229 I<The caller must free the strings and the array after use>.
2231 =head2 guestfs_umask
2233 int guestfs_umask (guestfs_h *handle,
2236 This function sets the mask used for creating new files and
2237 device nodes to C<mask & 0777>.
2239 Typical umask values would be C<022> which creates new files
2240 with permissions like "-rw-r--r--" or "-rwxr-xr-x", and
2241 C<002> which creates new files with permissions like
2242 "-rw-rw-r--" or "-rwxrwxr-x".
2244 The default umask is C<022>. This is important because it
2245 means that directories and device nodes will be created with
2246 C<0644> or C<0755> mode even if you specify C<0777>.
2248 See also L<umask(2)>, C<guestfs_mknod>, C<guestfs_mkdir>.
2250 This call returns the previous umask.
2252 On error this function returns -1.
2254 =head2 guestfs_umount
2256 int guestfs_umount (guestfs_h *handle,
2257 const char *pathordevice);
2259 This unmounts the given filesystem. The filesystem may be
2260 specified either by its mountpoint (path) or the device which
2261 contains the filesystem.
2263 This function returns 0 on success or -1 on error.
2265 =head2 guestfs_umount_all
2267 int guestfs_umount_all (guestfs_h *handle);
2269 This unmounts all mounted filesystems.
2271 Some internal mounts are not unmounted by this call.
2273 This function returns 0 on success or -1 on error.
2275 =head2 guestfs_upload
2277 int guestfs_upload (guestfs_h *handle,
2278 const char *filename,
2279 const char *remotefilename);
2281 Upload local file C<filename> to C<remotefilename> on the
2284 C<filename> can also be a named pipe.
2286 See also C<guestfs_download>.
2288 This function returns 0 on success or -1 on error.
2290 =head2 guestfs_vg_activate
2292 int guestfs_vg_activate (guestfs_h *handle,
2294 char * const* const volgroups);
2296 This command activates or (if C<activate> is false) deactivates
2297 all logical volumes in the listed volume groups C<volgroups>.
2298 If activated, then they are made known to the
2299 kernel, ie. they appear as C</dev/mapper> devices. If deactivated,
2300 then those devices disappear.
2302 This command is the same as running C<vgchange -a y|n volgroups...>
2304 Note that if C<volgroups> is an empty list then B<all> volume groups
2305 are activated or deactivated.
2307 This function returns 0 on success or -1 on error.
2309 =head2 guestfs_vg_activate_all
2311 int guestfs_vg_activate_all (guestfs_h *handle,
2314 This command activates or (if C<activate> is false) deactivates
2315 all logical volumes in all volume groups.
2316 If activated, then they are made known to the
2317 kernel, ie. they appear as C</dev/mapper> devices. If deactivated,
2318 then those devices disappear.
2320 This command is the same as running C<vgchange -a y|n>
2322 This function returns 0 on success or -1 on error.
2324 =head2 guestfs_vgcreate
2326 int guestfs_vgcreate (guestfs_h *handle,
2327 const char *volgroup,
2328 char * const* const physvols);
2330 This creates an LVM volume group called C<volgroup>
2331 from the non-empty list of physical volumes C<physvols>.
2333 This function returns 0 on success or -1 on error.
2335 =head2 guestfs_vgremove
2337 int guestfs_vgremove (guestfs_h *handle,
2338 const char *vgname);
2340 Remove an LVM volume group C<vgname>, (for example C<VG>).
2342 This also forcibly removes all logical volumes in the volume
2345 This function returns 0 on success or -1 on error.
2349 char **guestfs_vgs (guestfs_h *handle);
2351 List all the volumes groups detected. This is the equivalent
2352 of the L<vgs(8)> command.
2354 This returns a list of just the volume group names that were
2355 detected (eg. C<VolGroup00>).
2357 See also C<guestfs_vgs_full>.
2359 This function returns a NULL-terminated array of strings
2360 (like L<environ(3)>), or NULL if there was an error.
2361 I<The caller must free the strings and the array after use>.
2363 =head2 guestfs_vgs_full
2365 struct guestfs_lvm_vg_list *guestfs_vgs_full (guestfs_h *handle);
2367 List all the volumes groups detected. This is the equivalent
2368 of the L<vgs(8)> command. The "full" version includes all fields.
2370 This function returns a C<struct guestfs_lvm_vg_list *>
2371 (see E<lt>guestfs-structs.hE<gt>),
2372 or NULL if there was an error.
2373 I<The caller must call C<guestfs_free_lvm_vg_list> after use>.
2375 =head2 guestfs_wait_ready
2377 int guestfs_wait_ready (guestfs_h *handle);
2379 Internally libguestfs is implemented by running a virtual machine
2382 You should call this after C<guestfs_launch> to wait for the launch
2385 This function returns 0 on success or -1 on error.
2389 int guestfs_wc_c (guestfs_h *handle,
2392 This command counts the characters in a file, using the
2393 C<wc -c> external command.
2395 On error this function returns -1.
2399 int guestfs_wc_l (guestfs_h *handle,
2402 This command counts the lines in a file, using the
2403 C<wc -l> external command.
2405 On error this function returns -1.
2409 int guestfs_wc_w (guestfs_h *handle,
2412 This command counts the words in a file, using the
2413 C<wc -w> external command.
2415 On error this function returns -1.
2417 =head2 guestfs_write_file
2419 int guestfs_write_file (guestfs_h *handle,
2421 const char *content,
2424 This call creates a file called C<path>. The contents of the
2425 file is the string C<content> (which can contain any 8 bit data),
2426 with length C<size>.
2428 As a special case, if C<size> is C<0>
2429 then the length is calculated using C<strlen> (so in this case
2430 the content cannot contain embedded ASCII NULs).
2432 I<NB.> Owing to a bug, writing content containing ASCII NUL
2433 characters does I<not> work, even if the length is specified.
2434 We hope to resolve this bug in a future version. In the meantime
2435 use C<guestfs_upload>.
2437 This function returns 0 on success or -1 on error.
2439 Because of the message protocol, there is a transfer limit
2440 of somewhere between 2MB and 4MB. To transfer large files you should use
2445 int guestfs_zero (guestfs_h *handle,
2446 const char *device);
2448 This command writes zeroes over the first few blocks of C<device>.
2450 How many blocks are zeroed isn't specified (but it's I<not> enough
2451 to securely wipe the device). It should be sufficient to remove
2452 any partition tables, filesystem superblocks and so on.
2454 See also: C<guestfs_scrub_device>.
2456 This function returns 0 on success or -1 on error.
2458 =head2 guestfs_zerofree
2460 int guestfs_zerofree (guestfs_h *handle,
2461 const char *device);
2463 This runs the I<zerofree> program on C<device>. This program
2464 claims to zero unused inodes and disk blocks on an ext2/3
2465 filesystem, thus making it possible to compress the filesystem
2468 You should B<not> run this program if the filesystem is
2471 It is possible that using this program can damage the filesystem
2472 or data on the filesystem.
2474 This function returns 0 on success or -1 on error.