1Sys::Guestfs(3) User Contributed Perl Documentation Sys::Guestfs(3)
2
6 Sys::Guestfs - Perl bindings for libguestfs
7
9 use Sys::Guestfs;
10 my $h = Sys::Guestfs->new ();
12 $h->add_drive ('guest.img');
13 $h->launch ();
14 $h->mount ('/dev/sda1', '/');
15 $h->touch ('/hello');
16 $h->sync ();
17
19 The "Sys::Guestfs" module provides a Perl XS binding to the libguestfs
20 API for examining and modifying virtual machine disk images.
21 Amongst the things this is good for: making batch configuration changes
23 to guests, getting disk used/free statistics (see also: virt-df),
24 migrating between virtualization systems (see also: virt-p2v),
25 performing partial backups, performing partial guest clones, cloning
26 guests and changing registry/UUID/hostname info, and much else besides.
27 Libguestfs uses Linux kernel and qemu code, and can access any type of
29 guest filesystem that Linux and qemu can, including but not limited to:
30 ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
31 schemes, qcow, qcow2, vmdk.
32 Libguestfs provides ways to enumerate guest storage (eg. partitions,
34 LVs, what filesystem is in each LV, etc.). It can also run commands in
35 the context of the guest. Also you can access filesystems over FUSE.
36 See also Sys::Guestfs::Lib(3) for a set of useful library functions for
38 using libguestfs from Perl, including integration with libvirt.
39
41 All errors turn into calls to "croak" (see Carp(3)).
42
44 $h = Sys::Guestfs->new ();
45 Create a new guestfs handle.
46 $h->close ();
48 Explicitly close the guestfs handle.
49 Note: You should not usually call this function. The handle will
51 be closed implicitly when its reference count goes to zero (eg.
52 when it goes out of scope or the program ends). This call is only
53 required in some exceptional cases, such as where the program may
54 contain cached references to the handle 'somewhere' and you really
55 have to have the close happen right away. After calling "close"
56 the program must not call any method (including "close") on the
57 handle (but the implicit call to "DESTROY" that happens when the
58 final reference is cleaned up is OK).
59 $h->set_progress_callback (\&cb);
61 Set the progress notification callback for this handle to the Perl
62 closure "cb".
63 "cb" will be called whenever a long-running operation generates a
65 progress notification message. The 4 parameters to the function
66 are: "proc_nr", "serial", "position" and "total".
67 You should carefully read the documentation for
69 "guestfs_set_progress_callback" in guestfs(3) before using this
70 function.
71 $h->clear_progress_callback ();
73 This removes any progress callback function associated with the
74 handle.
75 $h->add_cdrom ($filename);
77 This function adds a virtual CD-ROM disk image to the guest.
78 This is equivalent to the qemu parameter "-cdrom filename".
80 Notes:
82 · This call checks for the existence of "filename". This stops
84 you from specifying other types of drive which are supported by
85 qemu such as "nbd:" and "http:" URLs. To specify those, use
86 the general "$h->config" call instead.
87 · If you just want to add an ISO file (often you use this as an
89 efficient way to transfer large files into the guest), then you
90 should probably use "$h->add_drive_ro" instead.
91 $h->add_drive ($filename);
93 This function adds a virtual machine disk image "filename" to the
94 guest. The first time you call this function, the disk appears as
95 IDE disk 0 ("/dev/sda") in the guest, the second time as
96 "/dev/sdb", and so on.
97 You don't necessarily need to be root when using libguestfs.
99 However you obviously do need sufficient permissions to access the
100 filename for whatever operations you want to perform (ie. read
101 access if you just want to read the image or write access if you
102 want to modify the image).
103 This is equivalent to the qemu parameter "-drive
105 file=filename,cache=off,if=...".
106 "cache=off" is omitted in cases where it is not supported by the
108 underlying filesystem.
109 "if=..." is set at compile time by the configuration option
111 "./configure --with-drive-if=...". In the rare case where you
112 might need to change this at run time, use "$h->add_drive_with_if"
113 or "$h->add_drive_ro_with_if".
114 Note that this call checks for the existence of "filename". This
116 stops you from specifying other types of drive which are supported
117 by qemu such as "nbd:" and "http:" URLs. To specify those, use the
118 general "$h->config" call instead.
119 $h->add_drive_ro ($filename);
121 This adds a drive in snapshot mode, making it effectively read-
122 only.
123 Note that writes to the device are allowed, and will be seen for
125 the duration of the guestfs handle, but they are written to a
126 temporary file which is discarded as soon as the guestfs handle is
127 closed. We don't currently have any method to enable changes to be
128 committed, although qemu can support this.
129 This is equivalent to the qemu parameter "-drive
131 file=filename,snapshot=on,if=...".
132 "if=..." is set at compile time by the configuration option
134 "./configure --with-drive-if=...". In the rare case where you
135 might need to change this at run time, use "$h->add_drive_with_if"
136 or "$h->add_drive_ro_with_if".
137 Note that this call checks for the existence of "filename". This
139 stops you from specifying other types of drive which are supported
140 by qemu such as "nbd:" and "http:" URLs. To specify those, use the
141 general "$h->config" call instead.
142 $h->add_drive_ro_with_if ($filename, $iface);
144 This is the same as "$h->add_drive_ro" but it allows you to specify
145 the QEMU interface emulation to use at run time.
146 $h->add_drive_with_if ($filename, $iface);
148 This is the same as "$h->add_drive" but it allows you to specify
149 the QEMU interface emulation to use at run time.
150 $h->aug_clear ($augpath);
152 Set the value associated with "path" to "NULL". This is the same
153 as the augtool(1) "clear" command.
154 $h->aug_close ();
156 Close the current Augeas handle and free up any resources used by
157 it. After calling this, you have to call "$h->aug_init" again
158 before you can use any other Augeas functions.
159 %nrnodescreated = $h->aug_defnode ($name, $expr, $val);
161 Defines a variable "name" whose value is the result of evaluating
162 "expr".
163 If "expr" evaluates to an empty nodeset, a node is created,
165 equivalent to calling "$h->aug_set" "expr", "value". "name" will
166 be the nodeset containing that single node.
167 On success this returns a pair containing the number of nodes in
169 the nodeset, and a boolean flag if a node was created.
170 $nrnodes = $h->aug_defvar ($name, $expr);
172 Defines an Augeas variable "name" whose value is the result of
173 evaluating "expr". If "expr" is NULL, then "name" is undefined.
174 On success this returns the number of nodes in "expr", or 0 if
176 "expr" evaluates to something which is not a nodeset.
177 $val = $h->aug_get ($augpath);
179 Look up the value associated with "path". If "path" matches
180 exactly one node, the "value" is returned.
181 $h->aug_init ($root, $flags);
183 Create a new Augeas handle for editing configuration files. If
184 there was any previous Augeas handle associated with this guestfs
185 session, then it is closed.
186 You must call this before using any other "$h->aug_*" commands.
188 "root" is the filesystem root. "root" must not be NULL, use "/"
190 instead.
191 The flags are the same as the flags defined in <augeas.h>, the
193 logical or of the following integers:
194 "AUG_SAVE_BACKUP" = 1
196 Keep the original file with a ".augsave" extension.
197 "AUG_SAVE_NEWFILE" = 2
199 Save changes into a file with extension ".augnew", and do not
200 overwrite original. Overrides "AUG_SAVE_BACKUP".
201 "AUG_TYPE_CHECK" = 4
203 Typecheck lenses (can be expensive).
204 "AUG_NO_STDINC" = 8
206 Do not use standard load path for modules.
207 "AUG_SAVE_NOOP" = 16
209 Make save a no-op, just record what would have been changed.
210 "AUG_NO_LOAD" = 32
212 Do not load the tree in "$h->aug_init".
213 To close the handle, you can call "$h->aug_close".
215 To find out more about Augeas, see <http://augeas.net/>.
217 $h->aug_insert ($augpath, $label, $before);
219 Create a new sibling "label" for "path", inserting it into the tree
220 before or after "path" (depending on the boolean flag "before").
221 "path" must match exactly one existing node in the tree, and
223 "label" must be a label, ie. not contain "/", "*" or end with a
224 bracketed index "[N]".
225 $h->aug_load ();
227 Load files into the tree.
228 See "aug_load" in the Augeas documentation for the full gory
230 details.
231 @matches = $h->aug_ls ($augpath);
233 This is just a shortcut for listing "$h->aug_match" "path/*" and
234 sorting the resulting nodes into alphabetical order.
235 @matches = $h->aug_match ($augpath);
237 Returns a list of paths which match the path expression "path".
238 The returned paths are sufficiently qualified so that they match
239 exactly one node in the current tree.
240 $h->aug_mv ($src, $dest);
242 Move the node "src" to "dest". "src" must match exactly one node.
243 "dest" is overwritten if it exists.
244 $nrnodes = $h->aug_rm ($augpath);
246 Remove "path" and all of its children.
247 On success this returns the number of entries which were removed.
249 $h->aug_save ();
251 This writes all pending changes to disk.
252 The flags which were passed to "$h->aug_init" affect exactly how
254 files are saved.
255 $h->aug_set ($augpath, $val);
257 Set the value associated with "path" to "val".
258 In the Augeas API, it is possible to clear a node by setting the
260 value to NULL. Due to an oversight in the libguestfs API you
261 cannot do that with this call. Instead you must use the
262 "$h->aug_clear" call.
263 $h->available (\@groups);
265 This command is used to check the availability of some groups of
266 functionality in the appliance, which not all builds of the
267 libguestfs appliance will be able to provide.
268 The libguestfs groups, and the functions that those groups
270 correspond to, are listed in "AVAILABILITY" in guestfs(3). You can
271 also fetch this list at runtime by calling
272 "$h->available_all_groups".
273 The argument "groups" is a list of group names, eg: "["inotify",
275 "augeas"]" would check for the availability of the Linux inotify
276 functions and Augeas (configuration file editing) functions.
277 The command returns no error if all requested groups are available.
279 It fails with an error if one or more of the requested groups is
281 unavailable in the appliance.
282 If an unknown group name is included in the list of groups then an
284 error is always returned.
285 Notes:
287 · You must call "$h->launch" before calling this function.
289 The reason is because we don't know what groups are supported
291 by the appliance/daemon until it is running and can be queried.
292 · If a group of functions is available, this does not necessarily
294 mean that they will work. You still have to check for errors
295 when calling individual API functions even if they are
296 available.
297 · It is usually the job of distro packagers to build complete
299 functionality into the libguestfs appliance. Upstream
300 libguestfs, if built from source with all requirements
301 satisfied, will support everything.
302 · This call was added in version 1.0.80. In previous versions of
304 libguestfs all you could do would be to speculatively execute a
305 command to find out if the daemon implemented it. See also
306 "$h->version".
307 @groups = $h->available_all_groups ();
309 This command returns a list of all optional groups that this daemon
310 knows about. Note this returns both supported and unsupported
311 groups. To find out which ones the daemon can actually support you
312 have to call "$h->available" on each member of the returned list.
313 See also "$h->available" and "AVAILABILITY" in guestfs(3).
315 $h->base64_in ($base64file, $filename);
317 This command uploads base64-encoded data from "base64file" to
318 "filename".
319 $h->base64_out ($filename, $base64file);
321 This command downloads the contents of "filename", writing it out
322 to local file "base64file" encoded as base64.
323 $h->blockdev_flushbufs ($device);
325 This tells the kernel to flush internal buffers associated with
326 "device".
327 This uses the blockdev(8) command.
329 $blocksize = $h->blockdev_getbsz ($device);
331 This returns the block size of a device.
332 (Note this is different from both size in blocks and filesystem
334 block size).
335 This uses the blockdev(8) command.
337 $ro = $h->blockdev_getro ($device);
339 Returns a boolean indicating if the block device is read-only (true
340 if read-only, false if not).
341 This uses the blockdev(8) command.
343 $sizeinbytes = $h->blockdev_getsize64 ($device);
345 This returns the size of the device in bytes.
346 See also "$h->blockdev_getsz".
348 This uses the blockdev(8) command.
350 $sectorsize = $h->blockdev_getss ($device);
352 This returns the size of sectors on a block device. Usually 512,
353 but can be larger for modern devices.
354 (Note, this is not the size in sectors, use "$h->blockdev_getsz"
356 for that).
357 This uses the blockdev(8) command.
359 $sizeinsectors = $h->blockdev_getsz ($device);
361 This returns the size of the device in units of 512-byte sectors
362 (even if the sectorsize isn't 512 bytes ... weird).
363 See also "$h->blockdev_getss" for the real sector size of the
365 device, and "$h->blockdev_getsize64" for the more useful size in
366 bytes.
367 This uses the blockdev(8) command.
369 $h->blockdev_rereadpt ($device);
371 Reread the partition table on "device".
372 This uses the blockdev(8) command.
374 $h->blockdev_setbsz ($device, $blocksize);
376 This sets the block size of a device.
377 (Note this is different from both size in blocks and filesystem
379 block size).
380 This uses the blockdev(8) command.
382 $h->blockdev_setro ($device);
384 Sets the block device named "device" to read-only.
385 This uses the blockdev(8) command.
387 $h->blockdev_setrw ($device);
389 Sets the block device named "device" to read-write.
390 This uses the blockdev(8) command.
392 $rpath = $h->case_sensitive_path ($path);
394 This can be used to resolve case insensitive paths on a filesystem
395 which is case sensitive. The use case is to resolve paths which
396 you have read from Windows configuration files or the Windows
397 Registry, to the true path.
398 The command handles a peculiarity of the Linux ntfs-3g filesystem
400 driver (and probably others), which is that although the underlying
401 filesystem is case-insensitive, the driver exports the filesystem
402 to Linux as case-sensitive.
403 One consequence of this is that special directories such as
405 "c:\windows" may appear as "/WINDOWS" or "/windows" (or other
406 things) depending on the precise details of how they were created.
407 In Windows itself this would not be a problem.
408 Bug or feature? You decide:
410 http://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1
411 <http://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1>
412 This function resolves the true case of each element in the path
414 and returns the case-sensitive path.
415 Thus "$h->case_sensitive_path" ("/Windows/System32") might return
417 "/WINDOWS/system32" (the exact return value would depend on details
418 of how the directories were originally created under Windows).
419 Note: This function does not handle drive names, backslashes etc.
421 See also "$h->realpath".
423 $content = $h->cat ($path);
425 Return the contents of the file named "path".
426 Note that this function cannot correctly handle binary files
428 (specifically, files containing "\0" character which is treated as
429 end of string). For those you need to use the "$h->read_file" or
430 "$h->download" functions which have a more complex interface.
431 Because of the message protocol, there is a transfer limit of
433 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
434 guestfs(3).
435 $checksum = $h->checksum ($csumtype, $path);
437 This call computes the MD5, SHAx or CRC checksum of the file named
438 "path".
439 The type of checksum to compute is given by the "csumtype"
441 parameter which must have one of the following values:
442 "crc"
444 Compute the cyclic redundancy check (CRC) specified by POSIX
445 for the "cksum" command.
446 "md5"
448 Compute the MD5 hash (using the "md5sum" program).
449 "sha1"
451 Compute the SHA1 hash (using the "sha1sum" program).
452 "sha224"
454 Compute the SHA224 hash (using the "sha224sum" program).
455 "sha256"
457 Compute the SHA256 hash (using the "sha256sum" program).
458 "sha384"
460 Compute the SHA384 hash (using the "sha384sum" program).
461 "sha512"
463 Compute the SHA512 hash (using the "sha512sum" program).
464 The checksum is returned as a printable string.
466 To get the checksum for a device, use "$h->checksum_device".
468 To get the checksums for many files, use "$h->checksums_out".
470 $checksum = $h->checksum_device ($csumtype, $device);
472 This call computes the MD5, SHAx or CRC checksum of the contents of
473 the device named "device". For the types of checksums supported
474 see the "$h->checksum" command.
475 $h->checksums_out ($csumtype, $directory, $sumsfile);
477 This command computes the checksums of all regular files in
478 "directory" and then emits a list of those checksums to the local
479 output file "sumsfile".
480 This can be used for verifying the integrity of a virtual machine.
482 However to be properly secure you should pay attention to the
483 output of the checksum command (it uses the ones from GNU
484 coreutils). In particular when the filename is not printable,
485 coreutils uses a special backslash syntax. For more information,
486 see the GNU coreutils info file.
487 $h->chmod ($mode, $path);
489 Change the mode (permissions) of "path" to "mode". Only numeric
490 modes are supported.
491 Note: When using this command from guestfish, "mode" by default
493 would be decimal, unless you prefix it with 0 to get octal, ie. use
494 0700 not 700.
495 The mode actually set is affected by the umask.
497 $h->chown ($owner, $group, $path);
499 Change the file owner to "owner" and group to "group".
500 Only numeric uid and gid are supported. If you want to use names,
502 you will need to locate and parse the password file yourself
503 (Augeas support makes this relatively easy).
504 $output = $h->command (\@arguments);
506 This call runs a command from the guest filesystem. The filesystem
507 must be mounted, and must contain a compatible operating system
508 (ie. something Linux, with the same or compatible processor
509 architecture).
510 The single parameter is an argv-style list of arguments. The first
512 element is the name of the program to run. Subsequent elements are
513 parameters. The list must be non-empty (ie. must contain a program
514 name). Note that the command runs directly, and is not invoked via
515 the shell (see "$h->sh").
516 The return value is anything printed to stdout by the command.
518 If the command returns a non-zero exit status, then this function
520 returns an error message. The error message string is the content
521 of stderr from the command.
522 The $PATH environment variable will contain at least "/usr/bin" and
524 "/bin". If you require a program from another location, you should
525 provide the full path in the first parameter.
526 Shared libraries and data files required by the program must be
528 available on filesystems which are mounted in the correct places.
529 It is the caller's responsibility to ensure all filesystems that
530 are needed are mounted at the right locations.
531 Because of the message protocol, there is a transfer limit of
533 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
534 guestfs(3).
535 @lines = $h->command_lines (\@arguments);
537 This is the same as "$h->command", but splits the result into a
538 list of lines.
539 See also: "$h->sh_lines"
541 Because of the message protocol, there is a transfer limit of
543 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
544 guestfs(3).
545 $h->config ($qemuparam, $qemuvalue);
547 This can be used to add arbitrary qemu command line parameters of
548 the form "-param value". Actually it's not quite arbitrary - we
549 prevent you from setting some parameters which would interfere with
550 parameters that we use.
551 The first character of "param" string must be a "-" (dash).
553 "value" can be NULL.
555 $h->copy_size ($src, $dest, $size);
557 This command copies exactly "size" bytes from one source device or
558 file "src" to another destination device or file "dest".
559 Note this will fail if the source is too short or if the
561 destination is not large enough.
562 $h->cp ($src, $dest);
564 This copies a file from "src" to "dest" where "dest" is either a
565 destination filename or destination directory.
566 $h->cp_a ($src, $dest);
568 This copies a file or directory from "src" to "dest" recursively
569 using the "cp -a" command.
570 $h->dd ($src, $dest);
572 This command copies from one source device or file "src" to another
573 destination device or file "dest". Normally you would use this to
574 copy to or from a device or partition, for example to duplicate a
575 filesystem.
576 If the destination is a device, it must be as large or larger than
578 the source file or device, otherwise the copy will fail. This
579 command cannot do partial copies (see "$h->copy_size").
580 $result = $h->debug ($subcmd, \@extraargs);
582 The "$h->debug" command exposes some internals of "guestfsd" (the
583 guestfs daemon) that runs inside the qemu subprocess.
584 There is no comprehensive help for this command. You have to look
586 at the file "daemon/debug.c" in the libguestfs source to find out
587 what you can do.
588 $h->debug_upload ($filename, $tmpname, $mode);
590 The "$h->debug_upload" command uploads a file to the libguestfs
591 appliance.
592 There is no comprehensive help for this command. You have to look
594 at the file "daemon/debug.c" in the libguestfs source to find out
595 what it is for.
596 $output = $h->df ();
598 This command runs the "df" command to report disk space used.
599 This command is mostly useful for interactive sessions. It is not
601 intended that you try to parse the output string. Use "statvfs"
602 from programs.
603 $output = $h->df_h ();
605 This command runs the "df -h" command to report disk space used in
606 human-readable format.
607 This command is mostly useful for interactive sessions. It is not
609 intended that you try to parse the output string. Use "statvfs"
610 from programs.
611 $kmsgs = $h->dmesg ();
613 This returns the kernel messages ("dmesg" output) from the guest
614 kernel. This is sometimes useful for extended debugging of
615 problems.
616 Another way to get the same information is to enable verbose
618 messages with "$h->set_verbose" or by setting the environment
619 variable "LIBGUESTFS_DEBUG=1" before running the program.
620 $h->download ($remotefilename, $filename);
622 Download file "remotefilename" and save it as "filename" on the
623 local machine.
624 "filename" can also be a named pipe.
626 See also "$h->upload", "$h->cat".
628 $h->download_offset ($remotefilename, $filename, $offset, $size);
630 Download file "remotefilename" and save it as "filename" on the
631 local machine.
632 "remotefilename" is read for "size" bytes starting at "offset"
634 (this region must be within the file or device).
635 Note that there is no limit on the amount of data that can be
637 downloaded with this call, unlike with "$h->pread", and this call
638 always reads the full amount unless an error occurs.
639 See also "$h->download", "$h->pread".
641 $h->drop_caches ($whattodrop);
643 This instructs the guest kernel to drop its page cache, and/or
644 dentries and inode caches. The parameter "whattodrop" tells the
645 kernel what precisely to drop, see http://linux-mm.org/Drop_Caches
646 <http://linux-mm.org/Drop_Caches>
647 Setting "whattodrop" to 3 should drop everything.
649 This automatically calls sync(2) before the operation, so that the
651 maximum guest memory is freed.
652 $sizekb = $h->du ($path);
654 This command runs the "du -s" command to estimate file space usage
655 for "path".
656 "path" can be a file or a directory. If "path" is a directory then
658 the estimate includes the contents of the directory and all
659 subdirectories (recursively).
660 The result is the estimated size in kilobytes (ie. units of 1024
662 bytes).
663 $h->e2fsck_f ($device);
665 This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
666 checker on "device", noninteractively ("-p"), even if the
667 filesystem appears to be clean ("-f").
668 This command is only needed because of "$h->resize2fs" (q.v.).
670 Normally you should use "$h->fsck".
671 $output = $h->echo_daemon (\@words);
673 This command concatenates the list of "words" passed with single
674 spaces between them and returns the resulting string.
675 You can use this command to test the connection through to the
677 daemon.
678 See also "$h->ping_daemon".
680 @lines = $h->egrep ($regex, $path);
682 This calls the external "egrep" program and returns the matching
683 lines.
684 Because of the message protocol, there is a transfer limit of
686 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
687 guestfs(3).
688 @lines = $h->egrepi ($regex, $path);
690 This calls the external "egrep -i" program and returns the matching
691 lines.
692 Because of the message protocol, there is a transfer limit of
694 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
695 guestfs(3).
696 $equality = $h->equal ($file1, $file2);
698 This compares the two files "file1" and "file2" and returns true if
699 their content is exactly equal, or false otherwise.
700 The external cmp(1) program is used for the comparison.
702 $existsflag = $h->exists ($path);
704 This returns "true" if and only if there is a file, directory (or
705 anything) with the given "path" name.
706 See also "$h->is_file", "$h->is_dir", "$h->stat".
708 $h->fallocate ($path, $len);
710 This command preallocates a file (containing zero bytes) named
711 "path" of size "len" bytes. If the file exists already, it is
712 overwritten.
713 Do not confuse this with the guestfish-specific "alloc" command
715 which allocates a file in the host and attaches it as a device.
716 This function is deprecated. In new code, use the "fallocate64"
718 call instead.
719 Deprecated functions will not be removed from the API, but the fact
721 that they are deprecated indicates that there are problems with
722 correct use of these functions.
723 $h->fallocate64 ($path, $len);
725 This command preallocates a file (containing zero bytes) named
726 "path" of size "len" bytes. If the file exists already, it is
727 overwritten.
728 Note that this call allocates disk blocks for the file. To create
730 a sparse file use "$h->truncate_size" instead.
731 The deprecated call "$h->fallocate" does the same, but owing to an
733 oversight it only allowed 30 bit lengths to be specified,
734 effectively limiting the maximum size of files created through that
735 call to 1GB.
736 Do not confuse this with the guestfish-specific "alloc" and
738 "sparse" commands which create a file in the host and attach it as
739 a device.
740 @lines = $h->fgrep ($pattern, $path);
742 This calls the external "fgrep" program and returns the matching
743 lines.
744 Because of the message protocol, there is a transfer limit of
746 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
747 guestfs(3).
748 @lines = $h->fgrepi ($pattern, $path);
750 This calls the external "fgrep -i" program and returns the matching
751 lines.
752 Because of the message protocol, there is a transfer limit of
754 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
755 guestfs(3).
756 $description = $h->file ($path);
758 This call uses the standard file(1) command to determine the type
759 or contents of the file.
760 This call will also transparently look inside various types of
762 compressed file.
763 The exact command which runs is "file -zb path". Note in
765 particular that the filename is not prepended to the output (the
766 "-b" option).
767 This command can also be used on "/dev/" devices (and partitions,
769 LV names). You can for example use this to determine if a device
770 contains a filesystem, although it's usually better to use
771 "$h->vfs_type".
772 If the "path" does not begin with "/dev/" then this command only
774 works for the content of regular files. For other file types
775 (directory, symbolic link etc) it will just return the string
776 "directory" etc.
777 $arch = $h->file_architecture ($filename);
779 This detects the architecture of the binary "filename", and returns
780 it if known.
781 Currently defined architectures are:
783 "i386"
785 This string is returned for all 32 bit i386, i486, i586, i686
786 binaries irrespective of the precise processor requirements of
787 the binary.
788 "x86_64"
790 64 bit x86-64.
791 "sparc"
793 32 bit SPARC.
794 "sparc64"
796 64 bit SPARC V9 and above.
797 "ia64"
799 Intel Itanium.
800 "ppc"
802 32 bit Power PC.
803 "ppc64"
805 64 bit Power PC.
806 Libguestfs may return other architecture strings in future.
808 The function works on at least the following types of files:
810 · many types of Un*x and Linux binary
812 · many types of Un*x and Linux shared library
814 · Windows Win32 and Win64 binaries
816 · Windows Win32 and Win64 DLLs
818 Win32 binaries and DLLs return "i386".
820 Win64 binaries and DLLs return "x86_64".
822 · Linux kernel modules
824 · Linux new-style initrd images
826 · some non-x86 Linux vmlinuz kernels
828 What it can't do currently:
830 · static libraries (libfoo.a)
832 · Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
834 · x86 Linux vmlinuz kernels
836 x86 vmlinuz images (bzImage format) consist of a mix of 16-,
838 32- and compressed code, and are horribly hard to unpack. If
839 you want to find the architecture of a kernel, use the
840 architecture of the associated initrd or kernel module(s)
841 instead.
842 $size = $h->filesize ($file);
844 This command returns the size of "file" in bytes.
845 To get other stats about a file, use "$h->stat", "$h->lstat",
847 "$h->is_dir", "$h->is_file" etc. To get the size of block devices,
848 use "$h->blockdev_getsize64".
849 $h->fill ($c, $len, $path);
851 This command creates a new file called "path". The initial content
852 of the file is "len" octets of "c", where "c" must be a number in
853 the range "[0..255]".
854 To fill a file with zero bytes (sparsely), it is much more
856 efficient to use "$h->truncate_size". To create a file with a
857 pattern of repeating bytes use "$h->fill_pattern".
858 $h->fill_pattern ($pattern, $len, $path);
860 This function is like "$h->fill" except that it creates a new file
861 of length "len" containing the repeating pattern of bytes in
862 "pattern". The pattern is truncated if necessary to ensure the
863 length of the file is exactly "len" bytes.
864 @names = $h->find ($directory);
866 This command lists out all files and directories, recursively,
867 starting at "directory". It is essentially equivalent to running
868 the shell command "find directory -print" but some post-processing
869 happens on the output, described below.
870 This returns a list of strings without any prefix. Thus if the
872 directory structure was:
873 /tmp/a
875 /tmp/b
876 /tmp/c/d
877 then the returned list from "$h->find" "/tmp" would be 4 elements:
879 a
881 b
882 c
883 c/d
884 If "directory" is not a directory, then this command returns an
886 error.
887 The returned list is sorted.
889 See also "$h->find0".
891 Because of the message protocol, there is a transfer limit of
893 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
894 guestfs(3).
895 $h->find0 ($directory, $files);
897 This command lists out all files and directories, recursively,
898 starting at "directory", placing the resulting list in the external
899 file called "files".
900 This command works the same way as "$h->find" with the following
902 exceptions:
903 · The resulting list is written to an external file.
905 · Items (filenames) in the result are separated by "\0"
907 characters. See find(1) option -print0.
908 · This command is not limited in the number of names that it can
910 return.
911 · The result list is not sorted.
913 $device = $h->findfs_label ($label);
915 This command searches the filesystems and returns the one which has
916 the given label. An error is returned if no such filesystem can be
917 found.
918 To find the label of a filesystem, use "$h->vfs_label".
920 $device = $h->findfs_uuid ($uuid);
922 This command searches the filesystems and returns the one which has
923 the given UUID. An error is returned if no such filesystem can be
924 found.
925 To find the UUID of a filesystem, use "$h->vfs_uuid".
927 $status = $h->fsck ($fstype, $device);
929 This runs the filesystem checker (fsck) on "device" which should
930 have filesystem type "fstype".
931 The returned integer is the status. See fsck(8) for the list of
933 status codes from "fsck".
934 Notes:
936 · Multiple status codes can be summed together.
938 · A non-zero return code can mean "success", for example if
940 errors have been corrected on the filesystem.
941 · Checking or repairing NTFS volumes is not supported (by linux-
943 ntfs).
944 This command is entirely equivalent to running "fsck -a -t fstype
946 device".
947 $append = $h->get_append ();
949 Return the additional kernel options which are added to the guest
950 kernel command line.
951 If "NULL" then no options are added.
953 $autosync = $h->get_autosync ();
955 Get the autosync flag.
956 $direct = $h->get_direct ();
958 Return the direct appliance mode flag.
959 $label = $h->get_e2label ($device);
961 This returns the ext2/3/4 filesystem label of the filesystem on
962 "device".
963 This function is deprecated. In new code, use the "vfs_label" call
965 instead.
966 Deprecated functions will not be removed from the API, but the fact
968 that they are deprecated indicates that there are problems with
969 correct use of these functions.
970 $uuid = $h->get_e2uuid ($device);
972 This returns the ext2/3/4 filesystem UUID of the filesystem on
973 "device".
974 This function is deprecated. In new code, use the "vfs_uuid" call
976 instead.
977 Deprecated functions will not be removed from the API, but the fact
979 that they are deprecated indicates that there are problems with
980 correct use of these functions.
981 $memsize = $h->get_memsize ();
983 This gets the memory size in megabytes allocated to the qemu
984 subprocess.
985 If "$h->set_memsize" was not called on this handle, and if
987 "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
988 default value for memsize.
989 For more information on the architecture of libguestfs, see
991 guestfs(3).
992 $network = $h->get_network ();
994 This returns the enable network flag.
995 $path = $h->get_path ();
997 Return the current search path.
998 This is always non-NULL. If it wasn't set already, then this will
1000 return the default path.
1001 $pid = $h->get_pid ();
1003 Return the process ID of the qemu subprocess. If there is no qemu
1004 subprocess, then this will return an error.
1005 This is an internal call used for debugging and testing.
1007 $qemu = $h->get_qemu ();
1009 Return the current qemu binary.
1010 This is always non-NULL. If it wasn't set already, then this will
1012 return the default qemu binary name.
1013 $recoveryproc = $h->get_recovery_proc ();
1015 Return the recovery process enabled flag.
1016 $selinux = $h->get_selinux ();
1018 This returns the current setting of the selinux flag which is
1019 passed to the appliance at boot time. See "$h->set_selinux".
1020 For more information on the architecture of libguestfs, see
1022 guestfs(3).
1023 $state = $h->get_state ();
1025 This returns the current state as an opaque integer. This is only
1026 useful for printing debug and internal error messages.
1027 For more information on states, see guestfs(3).
1029 $trace = $h->get_trace ();
1031 Return the command trace flag.
1032 $mask = $h->get_umask ();
1034 Return the current umask. By default the umask is 022 unless it
1035 has been set by calling "$h->umask".
1036 $verbose = $h->get_verbose ();
1038 This returns the verbose messages flag.
1039 $context = $h->getcon ();
1041 This gets the SELinux security context of the daemon.
1042 See the documentation about SELINUX in guestfs(3), and "$h->setcon"
1044 @xattrs = $h->getxattrs ($path);
1046 This call lists the extended attributes of the file or directory
1047 "path".
1048 At the system call level, this is a combination of the listxattr(2)
1050 and getxattr(2) calls.
1051 See also: "$h->lgetxattrs", attr(5).
1053 @paths = $h->glob_expand ($pattern);
1055 This command searches for all the pathnames matching "pattern"
1056 according to the wildcard expansion rules used by the shell.
1057 If no paths match, then this returns an empty list (note: not an
1059 error).
1060 It is just a wrapper around the C glob(3) function with flags
1062 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
1063 @lines = $h->grep ($regex, $path);
1065 This calls the external "grep" program and returns the matching
1066 lines.
1067 Because of the message protocol, there is a transfer limit of
1069 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1070 guestfs(3).
1071 @lines = $h->grepi ($regex, $path);
1073 This calls the external "grep -i" program and returns the matching
1074 lines.
1075 Because of the message protocol, there is a transfer limit of
1077 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1078 guestfs(3).
1079 $h->grub_install ($root, $device);
1081 This command installs GRUB (the Grand Unified Bootloader) on
1082 "device", with the root directory being "root".
1083 Note: If grub-install reports the error "No suitable drive was
1085 found in the generated device map." it may be that you need to
1086 create a "/boot/grub/device.map" file first that contains the
1087 mapping between grub device names and Linux device names. It is
1088 usually sufficient to create a file containing:
1089 (hd0) /dev/vda
1091 replacing "/dev/vda" with the name of the installation device.
1093 @lines = $h->head ($path);
1095 This command returns up to the first 10 lines of a file as a list
1096 of strings.
1097 Because of the message protocol, there is a transfer limit of
1099 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1100 guestfs(3).
1101 @lines = $h->head_n ($nrlines, $path);
1103 If the parameter "nrlines" is a positive number, this returns the
1104 first "nrlines" lines of the file "path".
1105 If the parameter "nrlines" is a negative number, this returns lines
1107 from the file "path", excluding the last "nrlines" lines.
1108 If the parameter "nrlines" is zero, this returns an empty list.
1110 Because of the message protocol, there is a transfer limit of
1112 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1113 guestfs(3).
1114 $dump = $h->hexdump ($path);
1116 This runs "hexdump -C" on the given "path". The result is the
1117 human-readable, canonical hex dump of the file.
1118 Because of the message protocol, there is a transfer limit of
1120 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1121 guestfs(3).
1122 $content = $h->initrd_cat ($initrdpath, $filename);
1124 This command unpacks the file "filename" from the initrd file
1125 called "initrdpath". The filename must be given without the
1126 initial "/" character.
1127 For example, in guestfish you could use the following command to
1129 examine the boot script (usually called "/init") contained in a
1130 Linux initrd or initramfs image:
1131 initrd-cat /boot/initrd-<version>.img init
1133 See also "$h->initrd_list".
1135 Because of the message protocol, there is a transfer limit of
1137 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1138 guestfs(3).
1139 @filenames = $h->initrd_list ($path);
1141 This command lists out files contained in an initrd.
1142 The files are listed without any initial "/" character. The files
1144 are listed in the order they appear (not necessarily alphabetical).
1145 Directory names are listed as separate items.
1146 Old Linux kernels (2.4 and earlier) used a compressed ext2
1148 filesystem as initrd. We only support the newer initramfs format
1149 (compressed cpio files).
1150 $wd = $h->inotify_add_watch ($path, $mask);
1152 Watch "path" for the events listed in "mask".
1153 Note that if "path" is a directory then events within that
1155 directory are watched, but this does not happen recursively (in
1156 subdirectories).
1157 Note for non-C or non-Linux callers: the inotify events are defined
1159 by the Linux kernel ABI and are listed in
1160 "/usr/include/sys/inotify.h".
1161 $h->inotify_close ();
1163 This closes the inotify handle which was previously opened by
1164 inotify_init. It removes all watches, throws away any pending
1165 events, and deallocates all resources.
1166 @paths = $h->inotify_files ();
1168 This function is a helpful wrapper around "$h->inotify_read" which
1169 just returns a list of pathnames of objects that were touched. The
1170 returned pathnames are sorted and deduplicated.
1171 $h->inotify_init ($maxevents);
1173 This command creates a new inotify handle. The inotify subsystem
1174 can be used to notify events which happen to objects in the guest
1175 filesystem.
1176 "maxevents" is the maximum number of events which will be queued up
1178 between calls to "$h->inotify_read" or "$h->inotify_files". If
1179 this is passed as 0, then the kernel (or previously set) default is
1180 used. For Linux 2.6.29 the default was 16384 events. Beyond this
1181 limit, the kernel throws away events, but records the fact that it
1182 threw them away by setting a flag "IN_Q_OVERFLOW" in the returned
1183 structure list (see "$h->inotify_read").
1184 Before any events are generated, you have to add some watches to
1186 the internal watch list. See: "$h->inotify_add_watch",
1187 "$h->inotify_rm_watch" and "$h->inotify_watch_all".
1188 Queued up events should be read periodically by calling
1190 "$h->inotify_read" (or "$h->inotify_files" which is just a helpful
1191 wrapper around "$h->inotify_read"). If you don't read the events
1192 out often enough then you risk the internal queue overflowing.
1193 The handle should be closed after use by calling
1195 "$h->inotify_close". This also removes any watches automatically.
1196 See also inotify(7) for an overview of the inotify interface as
1198 exposed by the Linux kernel, which is roughly what we expose via
1199 libguestfs. Note that there is one global inotify handle per
1200 libguestfs instance.
1201 @events = $h->inotify_read ();
1203 Return the complete queue of events that have happened since the
1204 previous read call.
1205 If no events have happened, this returns an empty list.
1207 Note: In order to make sure that all events have been read, you
1209 must call this function repeatedly until it returns an empty list.
1210 The reason is that the call will read events up to the maximum
1211 appliance-to-host message size and leave remaining events in the
1212 queue.
1213 $h->inotify_rm_watch ($wd);
1215 Remove a previously defined inotify watch. See
1216 "$h->inotify_add_watch".
1217 $arch = $h->inspect_get_arch ($root);
1219 This function should only be called with a root device string as
1220 returned by "$h->inspect_os".
1221 This returns the architecture of the inspected operating system.
1223 The possible return values are listed under
1224 "$h->file_architecture".
1225 If the architecture could not be determined, then the string
1227 "unknown" is returned.
1228 Please read "INSPECTION" in guestfs(3) for more details.
1230 $distro = $h->inspect_get_distro ($root);
1232 This function should only be called with a root device string as
1233 returned by "$h->inspect_os".
1234 This returns the distro (distribution) of the inspected operating
1236 system.
1237 Currently defined distros are:
1239 "debian"
1241 Debian or a Debian-derived distro such as Ubuntu.
1242 "fedora"
1244 Fedora.
1245 "redhat-based"
1247 Some Red Hat-derived distro.
1248 "rhel"
1250 Red Hat Enterprise Linux and some derivatives.
1251 "windows"
1253 Windows does not have distributions. This string is returned
1254 if the OS type is Windows.
1255 "unknown"
1257 The distro could not be determined.
1258 Future versions of libguestfs may return other strings here. The
1260 caller should be prepared to handle any string.
1261 Please read "INSPECTION" in guestfs(3) for more details.
1263 @filesystems = $h->inspect_get_filesystems ($root);
1265 This function should only be called with a root device string as
1266 returned by "$h->inspect_os".
1267 This returns a list of all the filesystems that we think are
1269 associated with this operating system. This includes the root
1270 filesystem, other ordinary filesystems, and non-mounted devices
1271 like swap partitions.
1272 In the case of a multi-boot virtual machine, it is possible for a
1274 filesystem to be shared between operating systems.
1275 Please read "INSPECTION" in guestfs(3) for more details. See also
1277 "$h->inspect_get_mountpoints".
1278 $major = $h->inspect_get_major_version ($root);
1280 This function should only be called with a root device string as
1281 returned by "$h->inspect_os".
1282 This returns the major version number of the inspected operating
1284 system.
1285 Windows uses a consistent versioning scheme which is not reflected
1287 in the popular public names used by the operating system. Notably
1288 the operating system known as "Windows 7" is really version 6.1
1289 (ie. major = 6, minor = 1). You can find out the real versions
1290 corresponding to releases of Windows by consulting Wikipedia or
1291 MSDN.
1292 If the version could not be determined, then 0 is returned.
1294 Please read "INSPECTION" in guestfs(3) for more details.
1296 $minor = $h->inspect_get_minor_version ($root);
1298 This function should only be called with a root device string as
1299 returned by "$h->inspect_os".
1300 This returns the minor version number of the inspected operating
1302 system.
1303 If the version could not be determined, then 0 is returned.
1305 Please read "INSPECTION" in guestfs(3) for more details. See also
1307 "$h->inspect_get_major_version".
1308 %mountpoints = $h->inspect_get_mountpoints ($root);
1310 This function should only be called with a root device string as
1311 returned by "$h->inspect_os".
1312 This returns a hash of where we think the filesystems associated
1314 with this operating system should be mounted. Callers should note
1315 that this is at best an educated guess made by reading
1316 configuration files such as "/etc/fstab".
1317 Each element in the returned hashtable has a key which is the path
1319 of the mountpoint (eg. "/boot") and a value which is the filesystem
1320 that would be mounted there (eg. "/dev/sda1").
1321 Non-mounted devices such as swap devices are not returned in this
1323 list.
1324 Please read "INSPECTION" in guestfs(3) for more details. See also
1326 "$h->inspect_get_filesystems".
1327 $product = $h->inspect_get_product_name ($root);
1329 This function should only be called with a root device string as
1330 returned by "$h->inspect_os".
1331 This returns the product name of the inspected operating system.
1333 The product name is generally some freeform string which can be
1334 displayed to the user, but should not be parsed by programs.
1335 If the product name could not be determined, then the string
1337 "unknown" is returned.
1338 Please read "INSPECTION" in guestfs(3) for more details.
1340 $name = $h->inspect_get_type ($root);
1342 This function should only be called with a root device string as
1343 returned by "$h->inspect_os".
1344 This returns the type of the inspected operating system. Currently
1346 defined types are:
1347 "linux"
1349 Any Linux-based operating system.
1350 "windows"
1352 Any Microsoft Windows operating system.
1353 "unknown"
1355 The operating system type could not be determined.
1356 Future versions of libguestfs may return other strings here. The
1358 caller should be prepared to handle any string.
1359 Please read "INSPECTION" in guestfs(3) for more details.
1361 @roots = $h->inspect_os ();
1363 This function uses other libguestfs functions and certain
1364 heuristics to inspect the disk(s) (usually disks belonging to a
1365 virtual machine), looking for operating systems.
1366 The list returned is empty if no operating systems were found.
1368 If one operating system was found, then this returns a list with a
1370 single element, which is the name of the root filesystem of this
1371 operating system. It is also possible for this function to return
1372 a list containing more than one element, indicating a dual-boot or
1373 multi-boot virtual machine, with each element being the root
1374 filesystem of one of the operating systems.
1375 You can pass the root string(s) returned to other
1377 "$h->inspect_get_*" functions in order to query further information
1378 about each operating system, such as the name and version.
1379 This function uses other libguestfs features such as "$h->mount_ro"
1381 and "$h->umount_all" in order to mount and unmount filesystems and
1382 look at the contents. This should be called with no disks
1383 currently mounted. The function may also use Augeas, so any
1384 existing Augeas handle will be closed.
1385 This function cannot decrypt encrypted disks. The caller must do
1387 that first (supplying the necessary keys) if the disk is encrypted.
1388 Please read "INSPECTION" in guestfs(3) for more details.
1390 See also "$h->list_filesystems".
1392 $flag = $h->is_blockdev ($path);
1394 This returns "true" if and only if there is a block device with the
1395 given "path" name.
1396 See also "$h->stat".
1398 $busy = $h->is_busy ();
1400 This returns true iff this handle is busy processing a command (in
1401 the "BUSY" state).
1402 For more information on states, see guestfs(3).
1404 $flag = $h->is_chardev ($path);
1406 This returns "true" if and only if there is a character device with
1407 the given "path" name.
1408 See also "$h->stat".
1410 $config = $h->is_config ();
1412 This returns true iff this handle is being configured (in the
1413 "CONFIG" state).
1414 For more information on states, see guestfs(3).
1416 $dirflag = $h->is_dir ($path);
1418 This returns "true" if and only if there is a directory with the
1419 given "path" name. Note that it returns false for other objects
1420 like files.
1421 See also "$h->stat".
1423 $flag = $h->is_fifo ($path);
1425 This returns "true" if and only if there is a FIFO (named pipe)
1426 with the given "path" name.
1427 See also "$h->stat".
1429 $fileflag = $h->is_file ($path);
1431 This returns "true" if and only if there is a regular file with the
1432 given "path" name. Note that it returns false for other objects
1433 like directories.
1434 See also "$h->stat".
1436 $launching = $h->is_launching ();
1438 This returns true iff this handle is launching the subprocess (in
1439 the "LAUNCHING" state).
1440 For more information on states, see guestfs(3).
1442 $lvflag = $h->is_lv ($device);
1444 This command tests whether "device" is a logical volume, and
1445 returns true iff this is the case.
1446 $ready = $h->is_ready ();
1448 This returns true iff this handle is ready to accept commands (in
1449 the "READY" state).
1450 For more information on states, see guestfs(3).
1452 $flag = $h->is_socket ($path);
1454 This returns "true" if and only if there is a Unix domain socket
1455 with the given "path" name.
1456 See also "$h->stat".
1458 $flag = $h->is_symlink ($path);
1460 This returns "true" if and only if there is a symbolic link with
1461 the given "path" name.
1462 See also "$h->stat".
1464 $h->kill_subprocess ();
1466 This kills the qemu subprocess. You should never need to call
1467 this.
1468 $h->launch ();
1470 Internally libguestfs is implemented by running a virtual machine
1471 using qemu(1).
1472 You should call this after configuring the handle (eg. adding
1474 drives) but before performing any actions.
1475 $h->lchown ($owner, $group, $path);
1477 Change the file owner to "owner" and group to "group". This is
1478 like "$h->chown" but if "path" is a symlink then the link itself is
1479 changed, not the target.
1480 Only numeric uid and gid are supported. If you want to use names,
1482 you will need to locate and parse the password file yourself
1483 (Augeas support makes this relatively easy).
1484 @xattrs = $h->lgetxattrs ($path);
1486 This is the same as "$h->getxattrs", but if "path" is a symbolic
1487 link, then it returns the extended attributes of the link itself.
1488 @devices = $h->list_devices ();
1490 List all the block devices.
1491 The full block device names are returned, eg. "/dev/sda".
1493 See also "$h->list_filesystems".
1495 %fses = $h->list_filesystems ();
1497 This inspection command looks for filesystems on partitions, block
1498 devices and logical volumes, returning a list of devices containing
1499 filesystems and their type.
1500 The return value is a hash, where the keys are the devices
1502 containing filesystems, and the values are the filesystem types.
1503 For example:
1504 "/dev/sda1" => "ntfs"
1506 "/dev/sda2" => "ext2"
1507 "/dev/vg_guest/lv_root" => "ext4"
1508 "/dev/vg_guest/lv_swap" => "swap"
1509 The value can have the special value "unknown", meaning the content
1511 of the device is undetermined or empty. "swap" means a Linux swap
1512 partition.
1513 This command runs other libguestfs commands, which might include
1515 "$h->mount" and "$h->umount", and therefore you should use this
1516 soon after launch and only when nothing is mounted.
1517 Not all of the filesystems returned will be mountable. In
1519 particular, swap partitions are returned in the list. Also this
1520 command does not check that each filesystem found is valid and
1521 mountable, and some filesystems might be mountable but require
1522 special options. Filesystems may not all belong to a single
1523 logical operating system (use "$h->inspect_os" to look for OSes).
1524 @partitions = $h->list_partitions ();
1526 List all the partitions detected on all block devices.
1527 The full partition device names are returned, eg. "/dev/sda1"
1529 This does not return logical volumes. For that you will need to
1531 call "$h->lvs".
1532 See also "$h->list_filesystems".
1534 $listing = $h->ll ($directory);
1536 List the files in "directory" (relative to the root directory,
1537 there is no cwd) in the format of 'ls -la'.
1538 This command is mostly useful for interactive sessions. It is not
1540 intended that you try to parse the output string.
1541 $h->ln ($target, $linkname);
1543 This command creates a hard link using the "ln" command.
1544 $h->ln_f ($target, $linkname);
1546 This command creates a hard link using the "ln -f" command. The
1547 "-f" option removes the link ("linkname") if it exists already.
1548 $h->ln_s ($target, $linkname);
1550 This command creates a symbolic link using the "ln -s" command.
1551 $h->ln_sf ($target, $linkname);
1553 This command creates a symbolic link using the "ln -sf" command,
1554 The "-f" option removes the link ("linkname") if it exists already.
1555 $h->lremovexattr ($xattr, $path);
1557 This is the same as "$h->removexattr", but if "path" is a symbolic
1558 link, then it removes an extended attribute of the link itself.
1559 @listing = $h->ls ($directory);
1561 List the files in "directory" (relative to the root directory,
1562 there is no cwd). The '.' and '..' entries are not returned, but
1563 hidden files are shown.
1564 This command is mostly useful for interactive sessions. Programs
1566 should probably use "$h->readdir" instead.
1567 $h->lsetxattr ($xattr, $val, $vallen, $path);
1569 This is the same as "$h->setxattr", but if "path" is a symbolic
1570 link, then it sets an extended attribute of the link itself.
1571 %statbuf = $h->lstat ($path);
1573 Returns file information for the given "path".
1574 This is the same as "$h->stat" except that if "path" is a symbolic
1576 link, then the link is stat-ed, not the file it refers to.
1577 This is the same as the lstat(2) system call.
1579 @statbufs = $h->lstatlist ($path, \@names);
1581 This call allows you to perform the "$h->lstat" operation on
1582 multiple files, where all files are in the directory "path".
1583 "names" is the list of files from this directory.
1584 On return you get a list of stat structs, with a one-to-one
1586 correspondence to the "names" list. If any name did not exist or
1587 could not be lstat'd, then the "ino" field of that structure is set
1588 to "-1".
1589 This call is intended for programs that want to efficiently list a
1591 directory contents without making many round-trips. See also
1592 "$h->lxattrlist" for a similarly efficient call for getting
1593 extended attributes. Very long directory listings might cause the
1594 protocol message size to be exceeded, causing this call to fail.
1595 The caller must split up such requests into smaller groups of
1596 names.
1597 $h->luks_add_key ($device, $key, $newkey, $keyslot);
1599 This command adds a new key on LUKS device "device". "key" is any
1600 existing key, and is used to access the device. "newkey" is the
1601 new key to add. "keyslot" is the key slot that will be replaced.
1602 Note that if "keyslot" already contains a key, then this command
1604 will fail. You have to use "$h->luks_kill_slot" first to remove
1605 that key.
1606 $h->luks_close ($device);
1608 This closes a LUKS device that was created earlier by
1609 "$h->luks_open" or "$h->luks_open_ro". The "device" parameter must
1610 be the name of the LUKS mapping device (ie. "/dev/mapper/mapname")
1611 and not the name of the underlying block device.
1612 $h->luks_format ($device, $key, $keyslot);
1614 This command erases existing data on "device" and formats the
1615 device as a LUKS encrypted device. "key" is the initial key, which
1616 is added to key slot "slot". (LUKS supports 8 key slots, numbered
1617 0-7).
1618 This command is dangerous. Without careful use you can easily
1620 destroy all your data.
1621 $h->luks_format_cipher ($device, $key, $keyslot, $cipher);
1623 This command is the same as "$h->luks_format" but it also allows
1624 you to set the "cipher" used.
1625 This command is dangerous. Without careful use you can easily
1627 destroy all your data.
1628 $h->luks_kill_slot ($device, $key, $keyslot);
1630 This command deletes the key in key slot "keyslot" from the
1631 encrypted LUKS device "device". "key" must be one of the other
1632 keys.
1633 $h->luks_open ($device, $key, $mapname);
1635 This command opens a block device which has been encrypted
1636 according to the Linux Unified Key Setup (LUKS) standard.
1637 "device" is the encrypted block device or partition.
1639 The caller must supply one of the keys associated with the LUKS
1641 block device, in the "key" parameter.
1642 This creates a new block device called "/dev/mapper/mapname".
1644 Reads and writes to this block device are decrypted from and
1645 encrypted to the underlying "device" respectively.
1646 If this block device contains LVM volume groups, then calling
1648 "$h->vgscan" followed by "$h->vg_activate_all" will make them
1649 visible.
1650 $h->luks_open_ro ($device, $key, $mapname);
1652 This is the same as "$h->luks_open" except that a read-only mapping
1653 is created.
1654 $h->lvcreate ($logvol, $volgroup, $mbytes);
1656 This creates an LVM logical volume called "logvol" on the volume
1657 group "volgroup", with "size" megabytes.
1658 $h->lvm_clear_filter ();
1660 This undoes the effect of "$h->lvm_set_filter". LVM will be able
1661 to see every block device.
1662 This command also clears the LVM cache and performs a volume group
1664 scan.
1665 $h->lvm_remove_all ();
1667 This command removes all LVM logical volumes, volume groups and
1668 physical volumes.
1669 This command is dangerous. Without careful use you can easily
1671 destroy all your data.
1672 $h->lvm_set_filter (\@devices);
1674 This sets the LVM device filter so that LVM will only be able to
1675 "see" the block devices in the list "devices", and will ignore all
1676 other attached block devices.
1677 Where disk image(s) contain duplicate PVs or VGs, this command is
1679 useful to get LVM to ignore the duplicates, otherwise LVM can get
1680 confused. Note also there are two types of duplication possible:
1681 either cloned PVs/VGs which have identical UUIDs; or VGs that are
1682 not cloned but just happen to have the same name. In normal
1683 operation you cannot create this situation, but you can do it
1684 outside LVM, eg. by cloning disk images or by bit twiddling inside
1685 the LVM metadata.
1686 This command also clears the LVM cache and performs a volume group
1688 scan.
1689 You can filter whole block devices or individual partitions.
1691 You cannot use this if any VG is currently in use (eg. contains a
1693 mounted filesystem), even if you are not filtering out that VG.
1694 $h->lvremove ($device);
1696 Remove an LVM logical volume "device", where "device" is the path
1697 to the LV, such as "/dev/VG/LV".
1698 You can also remove all LVs in a volume group by specifying the VG
1700 name, "/dev/VG".
1701 $h->lvrename ($logvol, $newlogvol);
1703 Rename a logical volume "logvol" with the new name "newlogvol".
1704 $h->lvresize ($device, $mbytes);
1706 This resizes (expands or shrinks) an existing LVM logical volume to
1707 "mbytes". When reducing, data in the reduced part is lost.
1708 $h->lvresize_free ($lv, $percent);
1710 This expands an existing logical volume "lv" so that it fills "pc"%
1711 of the remaining free space in the volume group. Commonly you
1712 would call this with pc = 100 which expands the logical volume as
1713 much as possible, using all remaining free space in the volume
1714 group.
1715 @logvols = $h->lvs ();
1717 List all the logical volumes detected. This is the equivalent of
1718 the lvs(8) command.
1719 This returns a list of the logical volume device names (eg.
1721 "/dev/VolGroup00/LogVol00").
1722 See also "$h->lvs_full", "$h->list_filesystems".
1724 @logvols = $h->lvs_full ();
1726 List all the logical volumes detected. This is the equivalent of
1727 the lvs(8) command. The "full" version includes all fields.
1728 $uuid = $h->lvuuid ($device);
1730 This command returns the UUID of the LVM LV "device".
1731 @xattrs = $h->lxattrlist ($path, \@names);
1733 This call allows you to get the extended attributes of multiple
1734 files, where all files are in the directory "path". "names" is the
1735 list of files from this directory.
1736 On return you get a flat list of xattr structs which must be
1738 interpreted sequentially. The first xattr struct always has a
1739 zero-length "attrname". "attrval" in this struct is zero-length to
1740 indicate there was an error doing "lgetxattr" for this file, or is
1741 a C string which is a decimal number (the number of following
1742 attributes for this file, which could be "0"). Then after the
1743 first xattr struct are the zero or more attributes for the first
1744 named file. This repeats for the second and subsequent files.
1745 This call is intended for programs that want to efficiently list a
1747 directory contents without making many round-trips. See also
1748 "$h->lstatlist" for a similarly efficient call for getting standard
1749 stats. Very long directory listings might cause the protocol
1750 message size to be exceeded, causing this call to fail. The caller
1751 must split up such requests into smaller groups of names.
1752 $h->mkdir ($path);
1754 Create a directory named "path".
1755 $h->mkdir_mode ($path, $mode);
1757 This command creates a directory, setting the initial permissions
1758 of the directory to "mode".
1759 For common Linux filesystems, the actual mode which is set will be
1761 "mode & ~umask & 01777". Non-native-Linux filesystems may
1762 interpret the mode in other ways.
1763 See also "$h->mkdir", "$h->umask"
1765 $h->mkdir_p ($path);
1767 Create a directory named "path", creating any parent directories as
1768 necessary. This is like the "mkdir -p" shell command.
1769 $dir = $h->mkdtemp ($template);
1771 This command creates a temporary directory. The "template"
1772 parameter should be a full pathname for the temporary directory
1773 name with the final six characters being "XXXXXX".
1774 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the
1776 second one being suitable for Windows filesystems.
1777 The name of the temporary directory that was created is returned.
1779 The temporary directory is created with mode 0700 and is owned by
1781 root.
1782 The caller is responsible for deleting the temporary directory and
1784 its contents after use.
1785 See also: mkdtemp(3)
1787 $h->mke2fs_J ($fstype, $blocksize, $device, $journal);
1789 This creates an ext2/3/4 filesystem on "device" with an external
1790 journal on "journal". It is equivalent to the command:
1791 mke2fs -t fstype -b blocksize -J device=<journal> <device>
1793 See also "$h->mke2journal".
1795 $h->mke2fs_JL ($fstype, $blocksize, $device, $label);
1797 This creates an ext2/3/4 filesystem on "device" with an external
1798 journal on the journal labeled "label".
1799 See also "$h->mke2journal_L".
1801 $h->mke2fs_JU ($fstype, $blocksize, $device, $uuid);
1803 This creates an ext2/3/4 filesystem on "device" with an external
1804 journal on the journal with UUID "uuid".
1805 See also "$h->mke2journal_U".
1807 $h->mke2journal ($blocksize, $device);
1809 This creates an ext2 external journal on "device". It is
1810 equivalent to the command:
1811 mke2fs -O journal_dev -b blocksize device
1813 $h->mke2journal_L ($blocksize, $label, $device);
1815 This creates an ext2 external journal on "device" with label
1816 "label".
1817 $h->mke2journal_U ($blocksize, $uuid, $device);
1819 This creates an ext2 external journal on "device" with UUID "uuid".
1820 $h->mkfifo ($mode, $path);
1822 This call creates a FIFO (named pipe) called "path" with mode
1823 "mode". It is just a convenient wrapper around "$h->mknod".
1824 The mode actually set is affected by the umask.
1826 $h->mkfs ($fstype, $device);
1828 This creates a filesystem on "device" (usually a partition or LVM
1829 logical volume). The filesystem type is "fstype", for example
1830 "ext3".
1831 $h->mkfs_b ($fstype, $blocksize, $device);
1833 This call is similar to "$h->mkfs", but it allows you to control
1834 the block size of the resulting filesystem. Supported block sizes
1835 depend on the filesystem type, but typically they are 1024, 2048 or
1836 4096 only.
1837 For VFAT and NTFS the "blocksize" parameter is treated as the
1839 requested cluster size.
1840 $h->mkmountpoint ($exemptpath);
1842 "$h->mkmountpoint" and "$h->rmmountpoint" are specialized calls
1843 that can be used to create extra mountpoints before mounting the
1844 first filesystem.
1845 These calls are only necessary in some very limited circumstances,
1847 mainly the case where you want to mount a mix of unrelated and/or
1848 read-only filesystems together.
1849 For example, live CDs often contain a "Russian doll" nest of
1851 filesystems, an ISO outer layer, with a squashfs image inside, with
1852 an ext2/3 image inside that. You can unpack this as follows in
1853 guestfish:
1854 add-ro Fedora-11-i686-Live.iso
1856 run
1857 mkmountpoint /cd
1858 mkmountpoint /squash
1859 mkmountpoint /ext3
1860 mount /dev/sda /cd
1861 mount-loop /cd/LiveOS/squashfs.img /squash
1862 mount-loop /squash/LiveOS/ext3fs.img /ext3
1863 The inner filesystem is now unpacked under the /ext3 mountpoint.
1865 $h->mknod ($mode, $devmajor, $devminor, $path);
1867 This call creates block or character special devices, or named
1868 pipes (FIFOs).
1869 The "mode" parameter should be the mode, using the standard
1871 constants. "devmajor" and "devminor" are the device major and
1872 minor numbers, only used when creating block and character special
1873 devices.
1874 Note that, just like mknod(2), the mode must be bitwise OR'd with
1876 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just
1877 creates a regular file). These constants are available in the
1878 standard Linux header files, or you can use "$h->mknod_b",
1879 "$h->mknod_c" or "$h->mkfifo" which are wrappers around this
1880 command which bitwise OR in the appropriate constant for you.
1881 The mode actually set is affected by the umask.
1883 $h->mknod_b ($mode, $devmajor, $devminor, $path);
1885 This call creates a block device node called "path" with mode
1886 "mode" and device major/minor "devmajor" and "devminor". It is
1887 just a convenient wrapper around "$h->mknod".
1888 The mode actually set is affected by the umask.
1890 $h->mknod_c ($mode, $devmajor, $devminor, $path);
1892 This call creates a char device node called "path" with mode "mode"
1893 and device major/minor "devmajor" and "devminor". It is just a
1894 convenient wrapper around "$h->mknod".
1895 The mode actually set is affected by the umask.
1897 $h->mkswap ($device);
1899 Create a swap partition on "device".
1900 $h->mkswap_L ($label, $device);
1902 Create a swap partition on "device" with label "label".
1903 Note that you cannot attach a swap label to a block device (eg.
1905 "/dev/sda"), just to a partition. This appears to be a limitation
1906 of the kernel or swap tools.
1907 $h->mkswap_U ($uuid, $device);
1909 Create a swap partition on "device" with UUID "uuid".
1910 $h->mkswap_file ($path);
1912 Create a swap file.
1913 This command just writes a swap file signature to an existing file.
1915 To create the file itself, use something like "$h->fallocate".
1916 $h->modprobe ($modulename);
1918 This loads a kernel module in the appliance.
1919 The kernel module must have been whitelisted when libguestfs was
1921 built (see "appliance/kmod.whitelist.in" in the source).
1922 $h->mount ($device, $mountpoint);
1924 Mount a guest disk at a position in the filesystem. Block devices
1925 are named "/dev/sda", "/dev/sdb" and so on, as they were added to
1926 the guest. If those block devices contain partitions, they will
1927 have the usual names (eg. "/dev/sda1"). Also LVM
1928 "/dev/VG/LV"-style names can be used.
1929 The rules are the same as for mount(2): A filesystem must first be
1931 mounted on "/" before others can be mounted. Other filesystems can
1932 only be mounted on directories which already exist.
1933 The mounted filesystem is writable, if we have sufficient
1935 permissions on the underlying device.
1936 Important note: When you use this call, the filesystem options
1938 "sync" and "noatime" are set implicitly. This was originally done
1939 because we thought it would improve reliability, but it turns out
1940 that -o sync has a very large negative performance impact and
1941 negligible effect on reliability. Therefore we recommend that you
1942 avoid using "$h->mount" in any code that needs performance, and
1943 instead use "$h->mount_options" (use an empty string for the first
1944 parameter if you don't want any options).
1945 $h->mount_loop ($file, $mountpoint);
1947 This command lets you mount "file" (a filesystem image in a file)
1948 on a mount point. It is entirely equivalent to the command "mount
1949 -o loop file mountpoint".
1950 $h->mount_options ($options, $device, $mountpoint);
1952 This is the same as the "$h->mount" command, but it allows you to
1953 set the mount options as for the mount(8) -o flag.
1954 If the "options" parameter is an empty string, then no options are
1956 passed (all options default to whatever the filesystem uses).
1957 $h->mount_ro ($device, $mountpoint);
1959 This is the same as the "$h->mount" command, but it mounts the
1960 filesystem with the read-only (-o ro) flag.
1961 $h->mount_vfs ($options, $vfstype, $device, $mountpoint);
1963 This is the same as the "$h->mount" command, but it allows you to
1964 set both the mount options and the vfstype as for the mount(8) -o
1965 and -t flags.
1966 %mps = $h->mountpoints ();
1968 This call is similar to "$h->mounts". That call returns a list of
1969 devices. This one returns a hash table (map) of device name to
1970 directory where the device is mounted.
1971 @devices = $h->mounts ();
1973 This returns the list of currently mounted filesystems. It returns
1974 the list of devices (eg. "/dev/sda1", "/dev/VG/LV").
1975 Some internal mounts are not shown.
1977 See also: "$h->mountpoints"
1979 $h->mv ($src, $dest);
1981 This moves a file from "src" to "dest" where "dest" is either a
1982 destination filename or destination directory.
1983 $status = $h->ntfs_3g_probe ($rw, $device);
1985 This command runs the ntfs-3g.probe(8) command which probes an NTFS
1986 "device" for mountability. (Not all NTFS volumes can be mounted
1987 read-write, and some cannot be mounted at all).
1988 "rw" is a boolean flag. Set it to true if you want to test if the
1990 volume can be mounted read-write. Set it to false if you want to
1991 test if the volume can be mounted read-only.
1992 The return value is an integer which 0 if the operation would
1994 succeed, or some non-zero value documented in the ntfs-3g.probe(8)
1995 manual page.
1996 $h->ntfsresize ($device);
1998 This command resizes an NTFS filesystem, expanding or shrinking it
1999 to the size of the underlying device. See also ntfsresize(8).
2000 $h->ntfsresize_size ($device, $size);
2002 This command is the same as "$h->ntfsresize" except that it allows
2003 you to specify the new size (in bytes) explicitly.
2004 $h->part_add ($device, $prlogex, $startsect, $endsect);
2006 This command adds a partition to "device". If there is no
2007 partition table on the device, call "$h->part_init" first.
2008 The "prlogex" parameter is the type of partition. Normally you
2010 should pass "p" or "primary" here, but MBR partition tables also
2011 support "l" (or "logical") and "e" (or "extended") partition types.
2012 "startsect" and "endsect" are the start and end of the partition in
2014 sectors. "endsect" may be negative, which means it counts
2015 backwards from the end of the disk ("-1" is the last sector).
2016 Creating a partition which covers the whole disk is not so easy.
2018 Use "$h->part_disk" to do that.
2019 $h->part_del ($device, $partnum);
2021 This command deletes the partition numbered "partnum" on "device".
2022 Note that in the case of MBR partitioning, deleting an extended
2024 partition also deletes any logical partitions it contains.
2025 $h->part_disk ($device, $parttype);
2027 This command is simply a combination of "$h->part_init" followed by
2028 "$h->part_add" to create a single primary partition covering the
2029 whole disk.
2030 "parttype" is the partition table type, usually "mbr" or "gpt", but
2032 other possible values are described in "$h->part_init".
2033 This command is dangerous. Without careful use you can easily
2035 destroy all your data.
2036 $bootable = $h->part_get_bootable ($device, $partnum);
2038 This command returns true if the partition "partnum" on "device"
2039 has the bootable flag set.
2040 See also "$h->part_set_bootable".
2042 $idbyte = $h->part_get_mbr_id ($device, $partnum);
2044 Returns the MBR type byte (also known as the ID byte) from the
2045 numbered partition "partnum".
2046 Note that only MBR (old DOS-style) partitions have type bytes. You
2048 will get undefined results for other partition table types (see
2049 "$h->part_get_parttype").
2050 $parttype = $h->part_get_parttype ($device);
2052 This command examines the partition table on "device" and returns
2053 the partition table type (format) being used.
2054 Common return values include: "msdos" (a DOS/Windows style MBR
2056 partition table), "gpt" (a GPT/EFI-style partition table). Other
2057 values are possible, although unusual. See "$h->part_init" for a
2058 full list.
2059 $h->part_init ($device, $parttype);
2061 This creates an empty partition table on "device" of one of the
2062 partition types listed below. Usually "parttype" should be either
2063 "msdos" or "gpt" (for large disks).
2064 Initially there are no partitions. Following this, you should call
2066 "$h->part_add" for each partition required.
2067 Possible values for "parttype" are:
2069 efi | gpt
2071 Intel EFI / GPT partition table.
2072 This is recommended for >= 2 TB partitions that will be
2074 accessed from Linux and Intel-based Mac OS X. It also has
2075 limited backwards compatibility with the "mbr" format.
2076 mbr | msdos
2078 The standard PC "Master Boot Record" (MBR) format used by MS-
2079 DOS and Windows. This partition type will only work for device
2080 sizes up to 2 TB. For large disks we recommend using "gpt".
2081 Other partition table types that may work but are not supported
2083 include:
2084 aix AIX disk labels.
2086 amiga | rdb
2088 Amiga "Rigid Disk Block" format.
2089 bsd BSD disk labels.
2091 dasd
2093 DASD, used on IBM mainframes.
2094 dvh MIPS/SGI volumes.
2096 mac Old Mac partition format. Modern Macs use "gpt".
2098 pc98
2100 NEC PC-98 format, common in Japan apparently.
2101 sun Sun disk labels.
2103 @partitions = $h->part_list ($device);
2105 This command parses the partition table on "device" and returns the
2106 list of partitions found.
2107 The fields in the returned structure are:
2109 part_num
2111 Partition number, counting from 1.
2112 part_start
2114 Start of the partition in bytes. To get sectors you have to
2115 divide by the device's sector size, see "$h->blockdev_getss".
2116 part_end
2118 End of the partition in bytes.
2119 part_size
2121 Size of the partition in bytes.
2122 $h->part_set_bootable ($device, $partnum, $bootable);
2124 This sets the bootable flag on partition numbered "partnum" on
2125 device "device". Note that partitions are numbered from 1.
2126 The bootable flag is used by some operating systems (notably
2128 Windows) to determine which partition to boot from. It is by no
2129 means universally recognized.
2130 $h->part_set_mbr_id ($device, $partnum, $idbyte);
2132 Sets the MBR type byte (also known as the ID byte) of the numbered
2133 partition "partnum" to "idbyte". Note that the type bytes quoted
2134 in most documentation are in fact hexadecimal numbers, but usually
2135 documented without any leading "0x" which might be confusing.
2136 Note that only MBR (old DOS-style) partitions have type bytes. You
2138 will get undefined results for other partition table types (see
2139 "$h->part_get_parttype").
2140 $h->part_set_name ($device, $partnum, $name);
2142 This sets the partition name on partition numbered "partnum" on
2143 device "device". Note that partitions are numbered from 1.
2144 The partition name can only be set on certain types of partition
2146 table. This works on "gpt" but not on "mbr" partitions.
2147 $device = $h->part_to_dev ($partition);
2149 This function takes a partition name (eg. "/dev/sdb1") and removes
2150 the partition number, returning the device name (eg. "/dev/sdb").
2151 The named partition must exist, for example as a string returned
2153 from "$h->list_partitions".
2154 $h->ping_daemon ();
2156 This is a test probe into the guestfs daemon running inside the
2157 qemu subprocess. Calling this function checks that the daemon
2158 responds to the ping message, without affecting the daemon or
2159 attached block device(s) in any other way.
2160 $content = $h->pread ($path, $count, $offset);
2162 This command lets you read part of a file. It reads "count" bytes
2163 of the file, starting at "offset", from file "path".
2164 This may read fewer bytes than requested. For further details see
2166 the pread(2) system call.
2167 See also "$h->pwrite", "$h->pread_device".
2169 Because of the message protocol, there is a transfer limit of
2171 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2172 guestfs(3).
2173 $content = $h->pread_device ($device, $count, $offset);
2175 This command lets you read part of a file. It reads "count" bytes
2176 of "device", starting at "offset".
2177 This may read fewer bytes than requested. For further details see
2179 the pread(2) system call.
2180 See also "$h->pread".
2182 Because of the message protocol, there is a transfer limit of
2184 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2185 guestfs(3).
2186 $h->pvcreate ($device);
2188 This creates an LVM physical volume on the named "device", where
2189 "device" should usually be a partition name such as "/dev/sda1".
2190 $h->pvremove ($device);
2192 This wipes a physical volume "device" so that LVM will no longer
2193 recognise it.
2194 The implementation uses the "pvremove" command which refuses to
2196 wipe physical volumes that contain any volume groups, so you have
2197 to remove those first.
2198 $h->pvresize ($device);
2200 This resizes (expands or shrinks) an existing LVM physical volume
2201 to match the new size of the underlying device.
2202 $h->pvresize_size ($device, $size);
2204 This command is the same as "$h->pvresize" except that it allows
2205 you to specify the new size (in bytes) explicitly.
2206 @physvols = $h->pvs ();
2208 List all the physical volumes detected. This is the equivalent of
2209 the pvs(8) command.
2210 This returns a list of just the device names that contain PVs (eg.
2212 "/dev/sda2").
2213 See also "$h->pvs_full".
2215 @physvols = $h->pvs_full ();
2217 List all the physical volumes detected. This is the equivalent of
2218 the pvs(8) command. The "full" version includes all fields.
2219 $uuid = $h->pvuuid ($device);
2221 This command returns the UUID of the LVM PV "device".
2222 $nbytes = $h->pwrite ($path, $content, $offset);
2224 This command writes to part of a file. It writes the data buffer
2225 "content" to the file "path" starting at offset "offset".
2226 This command implements the pwrite(2) system call, and like that
2228 system call it may not write the full data requested. The return
2229 value is the number of bytes that were actually written to the
2230 file. This could even be 0, although short writes are unlikely for
2231 regular files in ordinary circumstances.
2232 See also "$h->pread", "$h->pwrite_device".
2234 Because of the message protocol, there is a transfer limit of
2236 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2237 guestfs(3).
2238 $nbytes = $h->pwrite_device ($device, $content, $offset);
2240 This command writes to part of a device. It writes the data buffer
2241 "content" to "device" starting at offset "offset".
2242 This command implements the pwrite(2) system call, and like that
2244 system call it may not write the full data requested (although
2245 short writes to disk devices and partitions are probably impossible
2246 with standard Linux kernels).
2247 See also "$h->pwrite".
2249 Because of the message protocol, there is a transfer limit of
2251 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2252 guestfs(3).
2253 $content = $h->read_file ($path);
2255 This calls returns the contents of the file "path" as a buffer.
2256 Unlike "$h->cat", this function can correctly handle files that
2258 contain embedded ASCII NUL characters. However unlike
2259 "$h->download", this function is limited in the total size of file
2260 that can be handled.
2261 Because of the message protocol, there is a transfer limit of
2263 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2264 guestfs(3).
2265 @lines = $h->read_lines ($path);
2267 Return the contents of the file named "path".
2268 The file contents are returned as a list of lines. Trailing "LF"
2270 and "CRLF" character sequences are not returned.
2271 Note that this function cannot correctly handle binary files
2273 (specifically, files containing "\0" character which is treated as
2274 end of line). For those you need to use the "$h->read_file"
2275 function which has a more complex interface.
2276 @entries = $h->readdir ($dir);
2278 This returns the list of directory entries in directory "dir".
2279 All entries in the directory are returned, including "." and "..".
2281 The entries are not sorted, but returned in the same order as the
2282 underlying filesystem.
2283 Also this call returns basic file type information about each file.
2285 The "ftyp" field will contain one of the following characters:
2286 'b' Block special
2288 'c' Char special
2290 'd' Directory
2292 'f' FIFO (named pipe)
2294 'l' Symbolic link
2296 'r' Regular file
2298 's' Socket
2300 'u' Unknown file type
2302 '?' The readdir(3) call returned a "d_type" field with an
2304 unexpected value
2305 This function is primarily intended for use by programs. To get a
2307 simple list of names, use "$h->ls". To get a printable directory
2308 for human consumption, use "$h->ll".
2309 $link = $h->readlink ($path);
2311 This command reads the target of a symbolic link.
2312 @links = $h->readlinklist ($path, \@names);
2314 This call allows you to do a "readlink" operation on multiple
2315 files, where all files are in the directory "path". "names" is the
2316 list of files from this directory.
2317 On return you get a list of strings, with a one-to-one
2319 correspondence to the "names" list. Each string is the value of
2320 the symbolic link.
2321 If the readlink(2) operation fails on any name, then the
2323 corresponding result string is the empty string "". However the
2324 whole operation is completed even if there were readlink(2) errors,
2325 and so you can call this function with names where you don't know
2326 if they are symbolic links already (albeit slightly less
2327 efficient).
2328 This call is intended for programs that want to efficiently list a
2330 directory contents without making many round-trips. Very long
2331 directory listings might cause the protocol message size to be
2332 exceeded, causing this call to fail. The caller must split up such
2333 requests into smaller groups of names.
2334 $rpath = $h->realpath ($path);
2336 Return the canonicalized absolute pathname of "path". The returned
2337 path has no ".", ".." or symbolic link path elements.
2338 $h->removexattr ($xattr, $path);
2340 This call removes the extended attribute named "xattr" of the file
2341 "path".
2342 See also: "$h->lremovexattr", attr(5).
2344 $h->resize2fs ($device);
2346 This resizes an ext2, ext3 or ext4 filesystem to match the size of
2347 the underlying device.
2348 Note: It is sometimes required that you run "$h->e2fsck_f" on the
2350 "device" before calling this command. For unknown reasons
2351 "resize2fs" sometimes gives an error about this and sometimes not.
2352 In any case, it is always safe to call "$h->e2fsck_f" before
2353 calling this function.
2354 $h->resize2fs_size ($device, $size);
2356 This command is the same as "$h->resize2fs" except that it allows
2357 you to specify the new size (in bytes) explicitly.
2358 $h->rm ($path);
2360 Remove the single file "path".
2361 $h->rm_rf ($path);
2363 Remove the file or directory "path", recursively removing the
2364 contents if its a directory. This is like the "rm -rf" shell
2365 command.
2366 $h->rmdir ($path);
2368 Remove the single directory "path".
2369 $h->rmmountpoint ($exemptpath);
2371 This calls removes a mountpoint that was previously created with
2372 "$h->mkmountpoint". See "$h->mkmountpoint" for full details.
2373 $h->scrub_device ($device);
2375 This command writes patterns over "device" to make data retrieval
2376 more difficult.
2377 It is an interface to the scrub(1) program. See that manual page
2379 for more details.
2380 This command is dangerous. Without careful use you can easily
2382 destroy all your data.
2383 $h->scrub_file ($file);
2385 This command writes patterns over a file to make data retrieval
2386 more difficult.
2387 The file is removed after scrubbing.
2389 It is an interface to the scrub(1) program. See that manual page
2391 for more details.
2392 $h->scrub_freespace ($dir);
2394 This command creates the directory "dir" and then fills it with
2395 files until the filesystem is full, and scrubs the files as for
2396 "$h->scrub_file", and deletes them. The intention is to scrub any
2397 free space on the partition containing "dir".
2398 It is an interface to the scrub(1) program. See that manual page
2400 for more details.
2401 $h->set_append ($append);
2403 This function is used to add additional options to the guest kernel
2404 command line.
2405 The default is "NULL" unless overridden by setting
2407 "LIBGUESTFS_APPEND" environment variable.
2408 Setting "append" to "NULL" means no additional options are passed
2410 (libguestfs always adds a few of its own).
2411 $h->set_autosync ($autosync);
2413 If "autosync" is true, this enables autosync. Libguestfs will make
2414 a best effort attempt to run "$h->umount_all" followed by
2415 "$h->sync" when the handle is closed (also if the program exits
2416 without closing handles).
2417 This is disabled by default (except in guestfish where it is
2419 enabled by default).
2420 $h->set_direct ($direct);
2422 If the direct appliance mode flag is enabled, then stdin and stdout
2423 are passed directly through to the appliance once it is launched.
2424 One consequence of this is that log messages aren't caught by the
2426 library and handled by "$h->set_log_message_callback", but go
2427 straight to stdout.
2428 You probably don't want to use this unless you know what you are
2430 doing.
2431 The default is disabled.
2433 $h->set_e2label ($device, $label);
2435 This sets the ext2/3/4 filesystem label of the filesystem on
2436 "device" to "label". Filesystem labels are limited to 16
2437 characters.
2438 You can use either "$h->tune2fs_l" or "$h->get_e2label" to return
2440 the existing label on a filesystem.
2441 $h->set_e2uuid ($device, $uuid);
2443 This sets the ext2/3/4 filesystem UUID of the filesystem on
2444 "device" to "uuid". The format of the UUID and alternatives such
2445 as "clear", "random" and "time" are described in the tune2fs(8)
2446 manpage.
2447 You can use either "$h->tune2fs_l" or "$h->get_e2uuid" to return
2449 the existing UUID of a filesystem.
2450 $h->set_memsize ($memsize);
2452 This sets the memory size in megabytes allocated to the qemu
2453 subprocess. This only has any effect if called before
2454 "$h->launch".
2455 You can also change this by setting the environment variable
2457 "LIBGUESTFS_MEMSIZE" before the handle is created.
2458 For more information on the architecture of libguestfs, see
2460 guestfs(3).
2461 $h->set_network ($network);
2463 If "network" is true, then the network is enabled in the libguestfs
2464 appliance. The default is false.
2465 This affects whether commands are able to access the network (see
2467 "RUNNING COMMANDS" in guestfs(3)).
2468 You must call this before calling "$h->launch", otherwise it has no
2470 effect.
2471 $h->set_path ($searchpath);
2473 Set the path that libguestfs searches for kernel and initrd.img.
2474 The default is "$libdir/guestfs" unless overridden by setting
2476 "LIBGUESTFS_PATH" environment variable.
2477 Setting "path" to "NULL" restores the default path.
2479 $h->set_qemu ($qemu);
2481 Set the qemu binary that we will use.
2482 The default is chosen when the library was compiled by the
2484 configure script.
2485 You can also override this by setting the "LIBGUESTFS_QEMU"
2487 environment variable.
2488 Setting "qemu" to "NULL" restores the default qemu binary.
2490 Note that you should call this function as early as possible after
2492 creating the handle. This is because some pre-launch operations
2493 depend on testing qemu features (by running "qemu -help"). If the
2494 qemu binary changes, we don't retest features, and so you might see
2495 inconsistent results. Using the environment variable
2496 "LIBGUESTFS_QEMU" is safest of all since that picks the qemu binary
2497 at the same time as the handle is created.
2498 $h->set_recovery_proc ($recoveryproc);
2500 If this is called with the parameter "false" then "$h->launch" does
2501 not create a recovery process. The purpose of the recovery process
2502 is to stop runaway qemu processes in the case where the main
2503 program aborts abruptly.
2504 This only has any effect if called before "$h->launch", and the
2506 default is true.
2507 About the only time when you would want to disable this is if the
2509 main process will fork itself into the background ("daemonize"
2510 itself). In this case the recovery process thinks that the main
2511 program has disappeared and so kills qemu, which is not very
2512 helpful.
2513 $h->set_selinux ($selinux);
2515 This sets the selinux flag that is passed to the appliance at boot
2516 time. The default is "selinux=0" (disabled).
2517 Note that if SELinux is enabled, it is always in Permissive mode
2519 ("enforcing=0").
2520 For more information on the architecture of libguestfs, see
2522 guestfs(3).
2523 $h->set_trace ($trace);
2525 If the command trace flag is set to 1, then commands are printed on
2526 stderr before they are executed in a format which is very similar
2527 to the one used by guestfish. In other words, you can run a
2528 program with this enabled, and you will get out a script which you
2529 can feed to guestfish to perform the same set of actions.
2530 If you want to trace C API calls into libguestfs (and other
2532 libraries) then possibly a better way is to use the external
2533 ltrace(1) command.
2534 Command traces are disabled unless the environment variable
2536 "LIBGUESTFS_TRACE" is defined and set to 1.
2537 $h->set_verbose ($verbose);
2539 If "verbose" is true, this turns on verbose messages (to "stderr").
2540 Verbose messages are disabled unless the environment variable
2542 "LIBGUESTFS_DEBUG" is defined and set to 1.
2543 $h->setcon ($context);
2545 This sets the SELinux security context of the daemon to the string
2546 "context".
2547 See the documentation about SELINUX in guestfs(3).
2549 $h->setxattr ($xattr, $val, $vallen, $path);
2551 This call sets the extended attribute named "xattr" of the file
2552 "path" to the value "val" (of length "vallen"). The value is
2553 arbitrary 8 bit data.
2554 See also: "$h->lsetxattr", attr(5).
2556 $h->sfdisk ($device, $cyls, $heads, $sectors, \@lines);
2558 This is a direct interface to the sfdisk(8) program for creating
2559 partitions on block devices.
2560 "device" should be a block device, for example "/dev/sda".
2562 "cyls", "heads" and "sectors" are the number of cylinders, heads
2564 and sectors on the device, which are passed directly to sfdisk as
2565 the -C, -H and -S parameters. If you pass 0 for any of these, then
2566 the corresponding parameter is omitted. Usually for 'large' disks,
2567 you can just pass 0 for these, but for small (floppy-sized) disks,
2568 sfdisk (or rather, the kernel) cannot work out the right geometry
2569 and you will need to tell it.
2570 "lines" is a list of lines that we feed to "sfdisk". For more
2572 information refer to the sfdisk(8) manpage.
2573 To create a single partition occupying the whole disk, you would
2575 pass "lines" as a single element list, when the single element
2576 being the string "," (comma).
2577 See also: "$h->sfdisk_l", "$h->sfdisk_N", "$h->part_init"
2579 This command is dangerous. Without careful use you can easily
2581 destroy all your data.
2582 $h->sfdiskM ($device, \@lines);
2584 This is a simplified interface to the "$h->sfdisk" command, where
2585 partition sizes are specified in megabytes only (rounded to the
2586 nearest cylinder) and you don't need to specify the cyls, heads and
2587 sectors parameters which were rarely if ever used anyway.
2588 See also: "$h->sfdisk", the sfdisk(8) manpage and "$h->part_disk"
2590 This command is dangerous. Without careful use you can easily
2592 destroy all your data.
2593 $h->sfdisk_N ($device, $partnum, $cyls, $heads, $sectors, $line);
2595 This runs sfdisk(8) option to modify just the single partition "n"
2596 (note: "n" counts from 1).
2597 For other parameters, see "$h->sfdisk". You should usually pass 0
2599 for the cyls/heads/sectors parameters.
2600 See also: "$h->part_add"
2602 This command is dangerous. Without careful use you can easily
2604 destroy all your data.
2605 $partitions = $h->sfdisk_disk_geometry ($device);
2607 This displays the disk geometry of "device" read from the partition
2608 table. Especially in the case where the underlying block device
2609 has been resized, this can be different from the kernel's idea of
2610 the geometry (see "$h->sfdisk_kernel_geometry").
2611 The result is in human-readable format, and not designed to be
2613 parsed.
2614 $partitions = $h->sfdisk_kernel_geometry ($device);
2616 This displays the kernel's idea of the geometry of "device".
2617 The result is in human-readable format, and not designed to be
2619 parsed.
2620 $partitions = $h->sfdisk_l ($device);
2622 This displays the partition table on "device", in the human-
2623 readable output of the sfdisk(8) command. It is not intended to be
2624 parsed.
2625 See also: "$h->part_list"
2627 $output = $h->sh ($command);
2629 This call runs a command from the guest filesystem via the guest's
2630 "/bin/sh".
2631 This is like "$h->command", but passes the command to:
2633 /bin/sh -c "command"
2635 Depending on the guest's shell, this usually results in wildcards
2637 being expanded, shell expressions being interpolated and so on.
2638 All the provisos about "$h->command" apply to this call.
2640 @lines = $h->sh_lines ($command);
2642 This is the same as "$h->sh", but splits the result into a list of
2643 lines.
2644 See also: "$h->command_lines"
2646 $h->sleep ($secs);
2648 Sleep for "secs" seconds.
2649 %statbuf = $h->stat ($path);
2651 Returns file information for the given "path".
2652 This is the same as the stat(2) system call.
2654 %statbuf = $h->statvfs ($path);
2656 Returns file system statistics for any mounted file system. "path"
2657 should be a file or directory in the mounted file system (typically
2658 it is the mount point itself, but it doesn't need to be).
2659 This is the same as the statvfs(2) system call.
2661 @stringsout = $h->strings ($path);
2663 This runs the strings(1) command on a file and returns the list of
2664 printable strings found.
2665 Because of the message protocol, there is a transfer limit of
2667 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2668 guestfs(3).
2669 @stringsout = $h->strings_e ($encoding, $path);
2671 This is like the "$h->strings" command, but allows you to specify
2672 the encoding of strings that are looked for in the source file
2673 "path".
2674 Allowed encodings are:
2676 s Single 7-bit-byte characters like ASCII and the ASCII-
2678 compatible parts of ISO-8859-X (this is what "$h->strings"
2679 uses).
2680 S Single 8-bit-byte characters.
2682 b 16-bit big endian strings such as those encoded in UTF-16BE or
2684 UCS-2BE.
2685 l (lower case letter L)
2687 16-bit little endian such as UTF-16LE and UCS-2LE. This is
2688 useful for examining binaries in Windows guests.
2689 B 32-bit big endian such as UCS-4BE.
2691 L 32-bit little endian such as UCS-4LE.
2693 The returned strings are transcoded to UTF-8.
2695 Because of the message protocol, there is a transfer limit of
2697 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2698 guestfs(3).
2699 $h->swapoff_device ($device);
2701 This command disables the libguestfs appliance swap device or
2702 partition named "device". See "$h->swapon_device".
2703 $h->swapoff_file ($file);
2705 This command disables the libguestfs appliance swap on file.
2706 $h->swapoff_label ($label);
2708 This command disables the libguestfs appliance swap on labeled swap
2709 partition.
2710 $h->swapoff_uuid ($uuid);
2712 This command disables the libguestfs appliance swap partition with
2713 the given UUID.
2714 $h->swapon_device ($device);
2716 This command enables the libguestfs appliance to use the swap
2717 device or partition named "device". The increased memory is made
2718 available for all commands, for example those run using
2719 "$h->command" or "$h->sh".
2720 Note that you should not swap to existing guest swap partitions
2722 unless you know what you are doing. They may contain hibernation
2723 information, or other information that the guest doesn't want you
2724 to trash. You also risk leaking information about the host to the
2725 guest this way. Instead, attach a new host device to the guest and
2726 swap on that.
2727 $h->swapon_file ($file);
2729 This command enables swap to a file. See "$h->swapon_device" for
2730 other notes.
2731 $h->swapon_label ($label);
2733 This command enables swap to a labeled swap partition. See
2734 "$h->swapon_device" for other notes.
2735 $h->swapon_uuid ($uuid);
2737 This command enables swap to a swap partition with the given UUID.
2738 See "$h->swapon_device" for other notes.
2739 $h->sync ();
2741 This syncs the disk, so that any writes are flushed through to the
2742 underlying disk image.
2743 You should always call this if you have modified a disk image,
2745 before closing the handle.
2746 @lines = $h->tail ($path);
2748 This command returns up to the last 10 lines of a file as a list of
2749 strings.
2750 Because of the message protocol, there is a transfer limit of
2752 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2753 guestfs(3).
2754 @lines = $h->tail_n ($nrlines, $path);
2756 If the parameter "nrlines" is a positive number, this returns the
2757 last "nrlines" lines of the file "path".
2758 If the parameter "nrlines" is a negative number, this returns lines
2760 from the file "path", starting with the "-nrlines"th line.
2761 If the parameter "nrlines" is zero, this returns an empty list.
2763 Because of the message protocol, there is a transfer limit of
2765 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2766 guestfs(3).
2767 $h->tar_in ($tarfile, $directory);
2769 This command uploads and unpacks local file "tarfile" (an
2770 uncompressed tar file) into "directory".
2771 To upload a compressed tarball, use "$h->tgz_in" or "$h->txz_in".
2773 $h->tar_out ($directory, $tarfile);
2775 This command packs the contents of "directory" and downloads it to
2776 local file "tarfile".
2777 To download a compressed tarball, use "$h->tgz_out" or
2779 "$h->txz_out".
2780 $h->tgz_in ($tarball, $directory);
2782 This command uploads and unpacks local file "tarball" (a gzip
2783 compressed tar file) into "directory".
2784 To upload an uncompressed tarball, use "$h->tar_in".
2786 $h->tgz_out ($directory, $tarball);
2788 This command packs the contents of "directory" and downloads it to
2789 local file "tarball".
2790 To download an uncompressed tarball, use "$h->tar_out".
2792 $h->touch ($path);
2794 Touch acts like the touch(1) command. It can be used to update the
2795 timestamps on a file, or, if the file does not exist, to create a
2796 new zero-length file.
2797 This command only works on regular files, and will fail on other
2799 file types such as directories, symbolic links, block special etc.
2800 $h->truncate ($path);
2802 This command truncates "path" to a zero-length file. The file must
2803 exist already.
2804 $h->truncate_size ($path, $size);
2806 This command truncates "path" to size "size" bytes. The file must
2807 exist already.
2808 If the current file size is less than "size" then the file is
2810 extended to the required size with zero bytes. This creates a
2811 sparse file (ie. disk blocks are not allocated for the file until
2812 you write to it). To create a non-sparse file of zeroes, use
2813 "$h->fallocate64" instead.
2814 %superblock = $h->tune2fs_l ($device);
2816 This returns the contents of the ext2, ext3 or ext4 filesystem
2817 superblock on "device".
2818 It is the same as running "tune2fs -l device". See tune2fs(8)
2820 manpage for more details. The list of fields returned isn't
2821 clearly defined, and depends on both the version of "tune2fs" that
2822 libguestfs was built against, and the filesystem itself.
2823 $h->txz_in ($tarball, $directory);
2825 This command uploads and unpacks local file "tarball" (an xz
2826 compressed tar file) into "directory".
2827 $h->txz_out ($directory, $tarball);
2829 This command packs the contents of "directory" and downloads it to
2830 local file "tarball" (as an xz compressed tar archive).
2831 $oldmask = $h->umask ($mask);
2833 This function sets the mask used for creating new files and device
2834 nodes to "mask & 0777".
2835 Typical umask values would be 022 which creates new files with
2837 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which
2838 creates new files with permissions like "-rw-rw-r--" or
2839 "-rwxrwxr-x".
2840 The default umask is 022. This is important because it means that
2842 directories and device nodes will be created with 0644 or 0755 mode
2843 even if you specify 0777.
2844 See also "$h->get_umask", umask(2), "$h->mknod", "$h->mkdir".
2846 This call returns the previous umask.
2848 $h->umount ($pathordevice);
2850 This unmounts the given filesystem. The filesystem may be
2851 specified either by its mountpoint (path) or the device which
2852 contains the filesystem.
2853 $h->umount_all ();
2855 This unmounts all mounted filesystems.
2856 Some internal mounts are not unmounted by this call.
2858 $h->upload ($filename, $remotefilename);
2860 Upload local file "filename" to "remotefilename" on the filesystem.
2861 "filename" can also be a named pipe.
2863 See also "$h->download".
2865 $h->upload_offset ($filename, $remotefilename, $offset);
2867 Upload local file "filename" to "remotefilename" on the filesystem.
2868 "remotefilename" is overwritten starting at the byte "offset"
2870 specified. The intention is to overwrite parts of existing files
2871 or devices, although if a non-existant file is specified then it is
2872 created with a "hole" before "offset". The size of the data
2873 written is implicit in the size of the source "filename".
2874 Note that there is no limit on the amount of data that can be
2876 uploaded with this call, unlike with "$h->pwrite", and this call
2877 always writes the full amount unless an error occurs.
2878 See also "$h->upload", "$h->pwrite".
2880 $h->utimens ($path, $atsecs, $atnsecs, $mtsecs, $mtnsecs);
2882 This command sets the timestamps of a file with nanosecond
2883 precision.
2884 "atsecs, atnsecs" are the last access time (atime) in secs and
2886 nanoseconds from the epoch.
2887 "mtsecs, mtnsecs" are the last modification time (mtime) in secs
2889 and nanoseconds from the epoch.
2890 If the *nsecs field contains the special value "-1" then the
2892 corresponding timestamp is set to the current time. (The *secs
2893 field is ignored in this case).
2894 If the *nsecs field contains the special value "-2" then the
2896 corresponding timestamp is left unchanged. (The *secs field is
2897 ignored in this case).
2898 %version = $h->version ();
2900 Return the libguestfs version number that the program is linked
2901 against.
2902 Note that because of dynamic linking this is not necessarily the
2904 version of libguestfs that you compiled against. You can compile
2905 the program, and then at runtime dynamically link against a
2906 completely different "libguestfs.so" library.
2907 This call was added in version 1.0.58. In previous versions of
2909 libguestfs there was no way to get the version number. From C code
2910 you can use dynamic linker functions to find out if this symbol
2911 exists (if it doesn't, then it's an earlier version).
2912 The call returns a structure with four elements. The first three
2914 ("major", "minor" and "release") are numbers and correspond to the
2915 usual version triplet. The fourth element ("extra") is a string
2916 and is normally empty, but may be used for distro-specific
2917 information.
2918 To construct the original version string:
2920 "$major.$minor.$release$extra"
2921 See also: "LIBGUESTFS VERSION NUMBERS" in guestfs(3).
2923 Note: Don't use this call to test for availability of features. In
2925 enterprise distributions we backport features from later versions
2926 into earlier versions, making this an unreliable way to test for
2927 features. Use "$h->available" instead.
2928 $label = $h->vfs_label ($device);
2930 This returns the filesystem label of the filesystem on "device".
2931 If the filesystem is unlabeled, this returns the empty string.
2933 To find a filesystem from the label, use "$h->findfs_label".
2935 $fstype = $h->vfs_type ($device);
2937 This command gets the filesystem type corresponding to the
2938 filesystem on "device".
2939 For most filesystems, the result is the name of the Linux VFS
2941 module which would be used to mount this filesystem if you mounted
2942 it without specifying the filesystem type. For example a string
2943 such as "ext3" or "ntfs".
2944 $uuid = $h->vfs_uuid ($device);
2946 This returns the filesystem UUID of the filesystem on "device".
2947 If the filesystem does not have a UUID, this returns the empty
2949 string.
2950 To find a filesystem from the UUID, use "$h->findfs_uuid".
2952 $h->vg_activate ($activate, \@volgroups);
2954 This command activates or (if "activate" is false) deactivates all
2955 logical volumes in the listed volume groups "volgroups". If
2956 activated, then they are made known to the kernel, ie. they appear
2957 as "/dev/mapper" devices. If deactivated, then those devices
2958 disappear.
2959 This command is the same as running "vgchange -a y|n volgroups..."
2961 Note that if "volgroups" is an empty list then all volume groups
2963 are activated or deactivated.
2964 $h->vg_activate_all ($activate);
2966 This command activates or (if "activate" is false) deactivates all
2967 logical volumes in all volume groups. If activated, then they are
2968 made known to the kernel, ie. they appear as "/dev/mapper" devices.
2969 If deactivated, then those devices disappear.
2970 This command is the same as running "vgchange -a y|n"
2972 $h->vgcreate ($volgroup, \@physvols);
2974 This creates an LVM volume group called "volgroup" from the non-
2975 empty list of physical volumes "physvols".
2976 @uuids = $h->vglvuuids ($vgname);
2978 Given a VG called "vgname", this returns the UUIDs of all the
2979 logical volumes created in this volume group.
2980 You can use this along with "$h->lvs" and "$h->lvuuid" calls to
2982 associate logical volumes and volume groups.
2983 See also "$h->vgpvuuids".
2985 @uuids = $h->vgpvuuids ($vgname);
2987 Given a VG called "vgname", this returns the UUIDs of all the
2988 physical volumes that this volume group resides on.
2989 You can use this along with "$h->pvs" and "$h->pvuuid" calls to
2991 associate physical volumes and volume groups.
2992 See also "$h->vglvuuids".
2994 $h->vgremove ($vgname);
2996 Remove an LVM volume group "vgname", (for example "VG").
2997 This also forcibly removes all logical volumes in the volume group
2999 (if any).
3000 $h->vgrename ($volgroup, $newvolgroup);
3002 Rename a volume group "volgroup" with the new name "newvolgroup".
3003 @volgroups = $h->vgs ();
3005 List all the volumes groups detected. This is the equivalent of
3006 the vgs(8) command.
3007 This returns a list of just the volume group names that were
3009 detected (eg. "VolGroup00").
3010 See also "$h->vgs_full".
3012 @volgroups = $h->vgs_full ();
3014 List all the volumes groups detected. This is the equivalent of
3015 the vgs(8) command. The "full" version includes all fields.
3016 $h->vgscan ();
3018 This rescans all block devices and rebuilds the list of LVM
3019 physical volumes, volume groups and logical volumes.
3020 $uuid = $h->vguuid ($vgname);
3022 This command returns the UUID of the LVM VG named "vgname".
3023 $h->wait_ready ();
3025 This function is a no op.
3026 In versions of the API < 1.0.71 you had to call this function just
3028 after calling "$h->launch" to wait for the launch to complete.
3029 However this is no longer necessary because "$h->launch" now does
3030 the waiting.
3031 If you see any calls to this function in code then you can just
3033 remove them, unless you want to retain compatibility with older
3034 versions of the API.
3035 $chars = $h->wc_c ($path);
3037 This command counts the characters in a file, using the "wc -c"
3038 external command.
3039 $lines = $h->wc_l ($path);
3041 This command counts the lines in a file, using the "wc -l" external
3042 command.
3043 $words = $h->wc_w ($path);
3045 This command counts the words in a file, using the "wc -w" external
3046 command.
3047 $h->write ($path, $content);
3049 This call creates a file called "path". The content of the file is
3050 the string "content" (which can contain any 8 bit data).
3051 Because of the message protocol, there is a transfer limit of
3053 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
3054 guestfs(3).
3055 $h->write_file ($path, $content, $size);
3057 This call creates a file called "path". The contents of the file
3058 is the string "content" (which can contain any 8 bit data), with
3059 length "size".
3060 As a special case, if "size" is 0 then the length is calculated
3062 using "strlen" (so in this case the content cannot contain embedded
3063 ASCII NULs).
3064 NB. Owing to a bug, writing content containing ASCII NUL characters
3066 does not work, even if the length is specified.
3067 Because of the message protocol, there is a transfer limit of
3069 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
3070 guestfs(3).
3071 This function is deprecated. In new code, use the "write" call
3073 instead.
3074 Deprecated functions will not be removed from the API, but the fact
3076 that they are deprecated indicates that there are problems with
3077 correct use of these functions.
3078 @lines = $h->zegrep ($regex, $path);
3080 This calls the external "zegrep" program and returns the matching
3081 lines.
3082 Because of the message protocol, there is a transfer limit of
3084 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
3085 guestfs(3).
3086 @lines = $h->zegrepi ($regex, $path);
3088 This calls the external "zegrep -i" program and returns the
3089 matching lines.
3090 Because of the message protocol, there is a transfer limit of
3092 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
3093 guestfs(3).
3094 $h->zero ($device);
3096 This command writes zeroes over the first few blocks of "device".
3097 How many blocks are zeroed isn't specified (but it's not enough to
3099 securely wipe the device). It should be sufficient to remove any
3100 partition tables, filesystem superblocks and so on.
3101 See also: "$h->zero_device", "$h->scrub_device".
3103 $h->zero_device ($device);
3105 This command writes zeroes over the entire "device". Compare with
3106 "$h->zero" which just zeroes the first few blocks of a device.
3107 This command is dangerous. Without careful use you can easily
3109 destroy all your data.
3110 $h->zerofree ($device);
3112 This runs the zerofree program on "device". This program claims to
3113 zero unused inodes and disk blocks on an ext2/3 filesystem, thus
3114 making it possible to compress the filesystem more effectively.
3115 You should not run this program if the filesystem is mounted.
3117 It is possible that using this program can damage the filesystem or
3119 data on the filesystem.
3120 @lines = $h->zfgrep ($pattern, $path);
3122 This calls the external "zfgrep" program and returns the matching
3123 lines.
3124 Because of the message protocol, there is a transfer limit of
3126 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
3127 guestfs(3).
3128 @lines = $h->zfgrepi ($pattern, $path);
3130 This calls the external "zfgrep -i" program and returns the
3131 matching lines.
3132 Because of the message protocol, there is a transfer limit of
3134 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
3135 guestfs(3).
3136 $description = $h->zfile ($meth, $path);
3138 This command runs "file" after first decompressing "path" using
3139 "method".
3140 "method" must be one of "gzip", "compress" or "bzip2".
3142 Since 1.0.63, use "$h->file" instead which can now process
3144 compressed files.
3145 This function is deprecated. In new code, use the "file" call
3147 instead.
3148 Deprecated functions will not be removed from the API, but the fact
3150 that they are deprecated indicates that there are problems with
3151 correct use of these functions.
3152 @lines = $h->zgrep ($regex, $path);
3154 This calls the external "zgrep" program and returns the matching
3155 lines.
3156 Because of the message protocol, there is a transfer limit of
3158 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
3159 guestfs(3).
3160 @lines = $h->zgrepi ($regex, $path);
3162 This calls the external "zgrep -i" program and returns the matching
3163 lines.
3164 Because of the message protocol, there is a transfer limit of
3166 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
3167 guestfs(3).
3168
3170 From time to time we add new libguestfs APIs. Also some libguestfs
3171 APIs won't be available in all builds of libguestfs (the Fedora build
3172 is full-featured, but other builds may disable features). How do you
3173 test whether the APIs that your Perl program needs are available in the
3174 version of "Sys::Guestfs" that you are using?
3175 To test if a particular function is available in the "Sys::Guestfs"
3177 class, use the ordinary Perl UNIVERSAL method "can(METHOD)" (see
3178 perlobj(1)). For example:
3179 use Sys::Guestfs;
3181 if (defined (Sys::Guestfs->can ("set_verbose"))) {
3182 print "\$h->set_verbose is available\n";
3183 }
3184 To test if particular features are supported by the current build, use
3186 the "available" method like the example below. Note that the appliance
3187 must be launched first.
3188 $h->available ( ["augeas"] );
3190 Since the "available" method croaks if the feature is not supported,
3192 you might also want to wrap this in an eval and return a boolean. In
3193 fact this has already been done for you: use "feature_available" in
3194 Sys::Guestfs::Lib(3).
3195 For further discussion on this topic, refer to "AVAILABILITY" in
3197 guestfs(3).
3198
3200 The handle returned from "new" is a hash reference. The hash normally
3201 contains a single element:
3202 {
3204 _g => [private data used by libguestfs]
3205 }
3206 Callers can add other elements to this hash to store data for their own
3208 purposes. The data lasts for the lifetime of the handle.
3209 Any fields whose names begin with an underscore are reserved for
3211 private use by libguestfs. We may add more in future.
3212 It is recommended that callers prefix the name of their field(s) with
3214 some unique string, to avoid conflicts with other users.
3215
3217 Copyright (C) 2009-2010 Red Hat Inc.
3218
3220 Please see the file COPYING.LIB for the full license.
3221
3223 guestfs(3), guestfish(1), <http://libguestfs.org>,
3224 Sys::Guestfs::Lib(3).
3225perl v5.12.2 2010-09-27 Sys::Guestfs(3)