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 $g = Sys::Guestfs->new ();
12 $g->add_drive_opts ('guest.img', format => 'raw');
13 $g->launch ();
14 $g->mount ('/dev/sda1', '/');
15 $g->touch ('/hello');
16 $g->shutdown ();
17 $g->close ();
18
20 The "Sys::Guestfs" module provides a Perl XS binding to the libguestfs
21 API for examining and modifying virtual machine disk images.
22 Amongst the things this is good for: making batch configuration changes
24 to guests, getting disk used/free statistics (see also: virt-df),
25 migrating between virtualization systems (see also: virt-p2v),
26 performing partial backups, performing partial guest clones, cloning
27 guests and changing registry/UUID/hostname info, and much else besides.
28 Libguestfs uses Linux kernel and qemu code, and can access any type of
30 guest filesystem that Linux and qemu can, including but not limited to:
31 ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
32 schemes, qcow, qcow2, vmdk.
33 Libguestfs provides ways to enumerate guest storage (eg. partitions,
35 LVs, what filesystem is in each LV, etc.). It can also run commands in
36 the context of the guest. Also you can access filesystems over FUSE.
37 See also Sys::Guestfs::Lib(3) for a set of useful library functions for
39 using libguestfs from Perl, including integration with libvirt.
40
42 All errors turn into calls to "croak" (see Carp(3)).
43 The error string from libguestfs is directly available from $@. Use
45 the "last_errno" method if you want to get the errno.
46
48 $g = Sys::Guestfs->new ([environment => 0,] [close_on_exit => 0]);
49 Create a new guestfs handle.
50 If the optional argument "environment" is false, then the
52 "GUESTFS_CREATE_NO_ENVIRONMENT" flag is set.
53 If the optional argument "close_on_exit" is false, then the
55 "GUESTFS_CREATE_NO_CLOSE_ON_EXIT" flag is set.
56 $g->close ();
58 Explicitly close the guestfs handle.
59 Note: You should not usually call this function. The handle will
61 be closed implicitly when its reference count goes to zero (eg.
62 when it goes out of scope or the program ends). This call is only
63 required in some exceptional cases, such as where the program may
64 contain cached references to the handle 'somewhere' and you really
65 have to have the close happen right away. After calling "close"
66 the program must not call any method (including "close") on the
67 handle (but the implicit call to "DESTROY" that happens when the
68 final reference is cleaned up is OK).
69 $Sys::Guestfs::EVENT_CLOSE
71 See "GUESTFS_EVENT_CLOSE" in guestfs(3).
72 $Sys::Guestfs::EVENT_SUBPROCESS_QUIT
74 See "GUESTFS_EVENT_SUBPROCESS_QUIT" in guestfs(3).
75 $Sys::Guestfs::EVENT_LAUNCH_DONE
77 See "GUESTFS_EVENT_LAUNCH_DONE" in guestfs(3).
78 $Sys::Guestfs::EVENT_PROGRESS
80 See "GUESTFS_EVENT_PROGRESS" in guestfs(3).
81 $Sys::Guestfs::EVENT_APPLIANCE
83 See "GUESTFS_EVENT_APPLIANCE" in guestfs(3).
84 $Sys::Guestfs::EVENT_LIBRARY
86 See "GUESTFS_EVENT_LIBRARY" in guestfs(3).
87 $Sys::Guestfs::EVENT_TRACE
89 See "GUESTFS_EVENT_TRACE" in guestfs(3).
90 $Sys::Guestfs::EVENT_ENTER
92 See "GUESTFS_EVENT_ENTER" in guestfs(3).
93 $Sys::Guestfs::EVENT_LIBVIRT_AUTH
95 See "GUESTFS_EVENT_LIBVIRT_AUTH" in guestfs(3).
96 $Sys::Guestfs::EVENT_ALL
98 See "GUESTFS_EVENT_ALL" in guestfs(3).
99 $event_handle = $g->set_event_callback (\&cb, $event_bitmask);
101 Register "cb" as a callback function for all of the events in
102 $event_bitmask (one or more "$Sys::Guestfs::EVENT_*" flags
103 logically or'd together).
104 This function returns an event handle which can be used to delete
106 the callback using "delete_event_callback".
107 The callback function receives 4 parameters:
109 &cb ($event, $event_handle, $buf, $array)
111 $event
113 The event which happened (equal to one of
114 "$Sys::Guestfs::EVENT_*").
115 $event_handle
117 The event handle.
118 $buf
120 For some event types, this is a message buffer (ie. a string).
121 $array
123 For some event types (notably progress events), this is an
124 array of integers.
125 You should carefully read the documentation for
127 "guestfs_set_event_callback" in guestfs(3) before using this
128 function.
129 $g->delete_event_callback ($event_handle);
131 This removes the callback which was previously registered using
132 "set_event_callback".
133 $errnum = $g->last_errno ();
135 This returns the last error number (errno) that happened on the
136 handle $g.
137 If successful, an errno integer not equal to zero is returned.
139 If no error number is available, this returns 0. See
141 "guestfs_last_errno" in guestfs(3) for more details of why this can
142 happen.
143 You can use the standard Perl module Errno(3) to compare the
145 numeric error returned from this call with symbolic errnos:
146 $g->mkdir ("/foo");
148 if ($g->last_errno() == Errno::EEXIST()) {
149 # mkdir failed because the directory exists already.
150 }
151 $g->acl_delete_def_file ($dir);
153 This function deletes the default POSIX Access Control List (ACL)
154 attached to directory "dir".
155 $acl = $g->acl_get_file ($path, $acltype);
157 This function returns the POSIX Access Control List (ACL) attached
158 to "path". The ACL is returned in "long text form" (see acl(5)).
159 The "acltype" parameter may be:
161 "access"
163 Return the ordinary (access) ACL for any file, directory or
164 other filesystem object.
165 "default"
167 Return the default ACL. Normally this only makes sense if
168 "path" is a directory.
169 $g->acl_set_file ($path, $acltype, $acl);
171 This function sets the POSIX Access Control List (ACL) attached to
172 "path".
173 The "acltype" parameter may be:
175 "access"
177 Set the ordinary (access) ACL for any file, directory or other
178 filesystem object.
179 "default"
181 Set the default ACL. Normally this only makes sense if "path"
182 is a directory.
183 The "acl" parameter is the new ACL in either "long text form" or
185 "short text form" (see acl(5)). The new ACL completely replaces
186 any previous ACL on the file. The ACL must contain the full Unix
187 permissions (eg. "u::rwx,g::rx,o::rx").
188 If you are specifying individual users or groups, then the mask
190 field is also required (eg. "m::rwx"), followed by the "u:ID:..."
191 and/or "g:ID:..." field(s). A full ACL string might therefore look
192 like this:
193 u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx
195 \ Unix permissions / \mask/ \ ACL /
196 You should use numeric UIDs and GIDs. To map usernames and
198 groupnames to the correct numeric ID in the context of the guest,
199 use the Augeas functions (see "$g->aug_init").
200 $g->add_cdrom ($filename);
202 This function adds a virtual CD-ROM disk image to the guest.
203 Do not use this function! ISO files are just ordinary read-only
205 disk images. Use "$g->add_drive_ro" instead.
206 This function is deprecated. In new code, use the "add_drive" call
208 instead.
209 Deprecated functions will not be removed from the API, but the fact
211 that they are deprecated indicates that there are problems with
212 correct use of these functions.
213 $nrdisks = $g->add_domain ($dom [, libvirturi => $libvirturi] [,
215 readonly => $readonly] [, iface => $iface] [, live => $live] [,
216 allowuuid => $allowuuid] [, readonlydisk => $readonlydisk]);
217 This function adds the disk(s) attached to the named libvirt domain
218 "dom". It works by connecting to libvirt, requesting the domain
219 and domain XML from libvirt, parsing it for disks, and calling
220 "$g->add_drive_opts" on each one.
221 The number of disks added is returned. This operation is atomic:
223 if an error is returned, then no disks are added.
224 This function does some minimal checks to make sure the libvirt
226 domain is not running (unless "readonly" is true). In a future
227 version we will try to acquire the libvirt lock on each disk.
228 Disks must be accessible locally. This often means that adding
230 disks from a remote libvirt connection (see
231 <http://libvirt.org/remote.html>) will fail unless those disks are
232 accessible via the same device path locally too.
233 The optional "libvirturi" parameter sets the libvirt URI (see
235 <http://libvirt.org/uri.html>). If this is not set then we connect
236 to the default libvirt URI (or one set through an environment
237 variable, see the libvirt documentation for full details).
238 The optional "live" flag controls whether this call will try to
240 connect to a running virtual machine "guestfsd" process if it sees
241 a suitable <channel> element in the libvirt XML definition. The
242 default (if the flag is omitted) is never to try. See "ATTACHING
243 TO RUNNING DAEMONS" in guestfs(3) for more information.
244 If the "allowuuid" flag is true (default is false) then a UUID may
246 be passed instead of the domain name. The "dom" string is treated
247 as a UUID first and looked up, and if that lookup fails then we
248 treat "dom" as a name as usual.
249 The optional "readonlydisk" parameter controls what we do for disks
251 which are marked <readonly/> in the libvirt XML. Possible values
252 are:
253 readonlydisk = "error"
255 If "readonly" is false:
256 The whole call is aborted with an error if any disk with the
258 <readonly/> flag is found.
259 If "readonly" is true:
261 Disks with the <readonly/> flag are added read-only.
263 readonlydisk = "read"
265 If "readonly" is false:
266 Disks with the <readonly/> flag are added read-only. Other
268 disks are added read/write.
269 If "readonly" is true:
271 Disks with the <readonly/> flag are added read-only.
273 readonlydisk = "write" (default)
275 If "readonly" is false:
276 Disks with the <readonly/> flag are added read/write.
278 If "readonly" is true:
280 Disks with the <readonly/> flag are added read-only.
282 readonlydisk = "ignore"
284 If "readonly" is true or false:
285 Disks with the <readonly/> flag are skipped.
287 The other optional parameters are passed directly through to
289 "$g->add_drive_opts".
290 $g->add_drive ($filename [, readonly => $readonly] [, format =>
292 $format] [, iface => $iface] [, name => $name] [, label => $label] [,
293 cachemode => $cachemode]);
294 This function adds a disk image called "filename" to the handle.
295 "filename" may be a regular host file or a host device.
296 When this function is called before "$g->launch" (the usual case)
298 then the first time you call this function, the disk appears in the
299 API as "/dev/sda", the second time as "/dev/sdb", and so on.
300 In libguestfs X 1.20 you can also call this function after launch
302 (with some restrictions). This is called "hotplugging". When
303 hotplugging, you must specify a "label" so that the new disk gets a
304 predictable name. For more information see "HOTPLUGGING" in
305 guestfs(3).
306 You don't necessarily need to be root when using libguestfs.
308 However you obviously do need sufficient permissions to access the
309 filename for whatever operations you want to perform (ie. read
310 access if you just want to read the image or write access if you
311 want to modify the image).
312 This call checks that "filename" exists.
314 "filename" may be the special string "/dev/null". See "NULL DISKS"
316 in guestfs(3).
317 The optional arguments are:
319 "readonly"
321 If true then the image is treated as read-only. Writes are
322 still allowed, but they are stored in a temporary snapshot
323 overlay which is discarded at the end. The disk that you add
324 is not modified.
325 "format"
327 This forces the image format. If you omit this (or use
328 "$g->add_drive" or "$g->add_drive_ro") then the format is
329 automatically detected. Possible formats include "raw" and
330 "qcow2".
331 Automatic detection of the format opens you up to a potential
333 security hole when dealing with untrusted raw-format images.
334 See CVE-2010-3851 and RHBZ#642934. Specifying the format
335 closes this security hole.
336 "iface"
338 This rarely-used option lets you emulate the behaviour of the
339 deprecated "$g->add_drive_with_if" call (q.v.)
340 "name"
342 The name the drive had in the original guest, e.g. "/dev/sdb".
343 This is used as a hint to the guest inspection process if it is
344 available.
345 "label"
347 Give the disk a label. The label should be a unique, short
348 string using only ASCII characters "[a-zA-Z]". As well as its
349 usual name in the API (such as "/dev/sda"), the drive will also
350 be named "/dev/disk/guestfs/label".
351 See "DISK LABELS" in guestfs(3).
353 "cachemode"
355 Choose whether or not libguestfs will obey sync operations
356 (safe but slow) or not (unsafe but fast). The possible values
357 for this string are:
358 "cachemode = "writeback""
360 This is the default.
361 Write operations in the API do not return until a write(2)
363 call has completed in the host [but note this does not
364 imply that anything gets written to disk].
365 Sync operations in the API, including implicit syncs caused
367 by filesystem journalling, will not return until an
368 fdatasync(2) call has completed in the host, indicating
369 that data has been committed to disk.
370 "cachemode = "unsafe""
372 In this mode, there are no guarantees. Libguestfs may
373 cache anything and ignore sync requests. This is suitable
374 only for scratch or temporary disks.
375 $g->add_drive_opts ($filename [, readonly => $readonly] [, format =>
377 $format] [, iface => $iface] [, name => $name] [, label => $label] [,
378 cachemode => $cachemode]);
379 This is an alias of "add_drive".
380 $g->add_drive_ro ($filename);
382 This function is the equivalent of calling "$g->add_drive_opts"
383 with the optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set
384 to 1, so the disk is added read-only, with the format being
385 detected automatically.
386 $g->add_drive_ro_with_if ($filename, $iface);
388 This is the same as "$g->add_drive_ro" but it allows you to specify
389 the QEMU interface emulation to use at run time.
390 This function is deprecated. In new code, use the "add_drive" call
392 instead.
393 Deprecated functions will not be removed from the API, but the fact
395 that they are deprecated indicates that there are problems with
396 correct use of these functions.
397 $g->add_drive_with_if ($filename, $iface);
399 This is the same as "$g->add_drive" but it allows you to specify
400 the QEMU interface emulation to use at run time.
401 This function is deprecated. In new code, use the "add_drive" call
403 instead.
404 Deprecated functions will not be removed from the API, but the fact
406 that they are deprecated indicates that there are problems with
407 correct use of these functions.
408 $g->aug_clear ($augpath);
410 Set the value associated with "path" to "NULL". This is the same
411 as the augtool(1) "clear" command.
412 $g->aug_close ();
414 Close the current Augeas handle and free up any resources used by
415 it. After calling this, you have to call "$g->aug_init" again
416 before you can use any other Augeas functions.
417 %nrnodescreated = $g->aug_defnode ($name, $expr, $val);
419 Defines a variable "name" whose value is the result of evaluating
420 "expr".
421 If "expr" evaluates to an empty nodeset, a node is created,
423 equivalent to calling "$g->aug_set" "expr", "value". "name" will
424 be the nodeset containing that single node.
425 On success this returns a pair containing the number of nodes in
427 the nodeset, and a boolean flag if a node was created.
428 $nrnodes = $g->aug_defvar ($name, $expr);
430 Defines an Augeas variable "name" whose value is the result of
431 evaluating "expr". If "expr" is NULL, then "name" is undefined.
432 On success this returns the number of nodes in "expr", or 0 if
434 "expr" evaluates to something which is not a nodeset.
435 $val = $g->aug_get ($augpath);
437 Look up the value associated with "path". If "path" matches
438 exactly one node, the "value" is returned.
439 $g->aug_init ($root, $flags);
441 Create a new Augeas handle for editing configuration files. If
442 there was any previous Augeas handle associated with this guestfs
443 session, then it is closed.
444 You must call this before using any other "$g->aug_*" commands.
446 "root" is the filesystem root. "root" must not be NULL, use "/"
448 instead.
449 The flags are the same as the flags defined in <augeas.h>, the
451 logical or of the following integers:
452 "AUG_SAVE_BACKUP" = 1
454 Keep the original file with a ".augsave" extension.
455 "AUG_SAVE_NEWFILE" = 2
457 Save changes into a file with extension ".augnew", and do not
458 overwrite original. Overrides "AUG_SAVE_BACKUP".
459 "AUG_TYPE_CHECK" = 4
461 Typecheck lenses.
462 This option is only useful when debugging Augeas lenses. Use
464 of this option may require additional memory for the libguestfs
465 appliance. You may need to set the "LIBGUESTFS_MEMSIZE"
466 environment variable or call "$g->set_memsize".
467 "AUG_NO_STDINC" = 8
469 Do not use standard load path for modules.
470 "AUG_SAVE_NOOP" = 16
472 Make save a no-op, just record what would have been changed.
473 "AUG_NO_LOAD" = 32
475 Do not load the tree in "$g->aug_init".
476 To close the handle, you can call "$g->aug_close".
478 To find out more about Augeas, see <http://augeas.net/>.
480 $g->aug_insert ($augpath, $label, $before);
482 Create a new sibling "label" for "path", inserting it into the tree
483 before or after "path" (depending on the boolean flag "before").
484 "path" must match exactly one existing node in the tree, and
486 "label" must be a label, ie. not contain "/", "*" or end with a
487 bracketed index "[N]".
488 $g->aug_load ();
490 Load files into the tree.
491 See "aug_load" in the Augeas documentation for the full gory
493 details.
494 @matches = $g->aug_ls ($augpath);
496 This is just a shortcut for listing "$g->aug_match" "path/*" and
497 sorting the resulting nodes into alphabetical order.
498 @matches = $g->aug_match ($augpath);
500 Returns a list of paths which match the path expression "path".
501 The returned paths are sufficiently qualified so that they match
502 exactly one node in the current tree.
503 $g->aug_mv ($src, $dest);
505 Move the node "src" to "dest". "src" must match exactly one node.
506 "dest" is overwritten if it exists.
507 $nrnodes = $g->aug_rm ($augpath);
509 Remove "path" and all of its children.
510 On success this returns the number of entries which were removed.
512 $g->aug_save ();
514 This writes all pending changes to disk.
515 The flags which were passed to "$g->aug_init" affect exactly how
517 files are saved.
518 $g->aug_set ($augpath, $val);
520 Set the value associated with "path" to "val".
521 In the Augeas API, it is possible to clear a node by setting the
523 value to NULL. Due to an oversight in the libguestfs API you
524 cannot do that with this call. Instead you must use the
525 "$g->aug_clear" call.
526 $g->available (\@groups);
528 This command is used to check the availability of some groups of
529 functionality in the appliance, which not all builds of the
530 libguestfs appliance will be able to provide.
531 The libguestfs groups, and the functions that those groups
533 correspond to, are listed in "AVAILABILITY" in guestfs(3). You can
534 also fetch this list at runtime by calling
535 "$g->available_all_groups".
536 The argument "groups" is a list of group names, eg: "["inotify",
538 "augeas"]" would check for the availability of the Linux inotify
539 functions and Augeas (configuration file editing) functions.
540 The command returns no error if all requested groups are available.
542 It fails with an error if one or more of the requested groups is
544 unavailable in the appliance.
545 If an unknown group name is included in the list of groups then an
547 error is always returned.
548 Notes:
550 ยท You must call "$g->launch" before calling this function.
552 The reason is because we don't know what groups are supported
554 by the appliance/daemon until it is running and can be queried.
555 ยท If a group of functions is available, this does not necessarily
557 mean that they will work. You still have to check for errors
558 when calling individual API functions even if they are
559 available.
560 ยท It is usually the job of distro packagers to build complete
562 functionality into the libguestfs appliance. Upstream
563 libguestfs, if built from source with all requirements
564 satisfied, will support everything.
565 ยท This call was added in version 1.0.80. In previous versions of
567 libguestfs all you could do would be to speculatively execute a
568 command to find out if the daemon implemented it. See also
569 "$g->version".
570 See also "$g->filesystem_available".
572 @groups = $g->available_all_groups ();
574 This command returns a list of all optional groups that this daemon
575 knows about. Note this returns both supported and unsupported
576 groups. To find out which ones the daemon can actually support you
577 have to call "$g->available" on each member of the returned list.
578 See also "$g->available" and "AVAILABILITY" in guestfs(3).
580 $g->base64_in ($base64file, $filename);
582 This command uploads base64-encoded data from "base64file" to
583 "filename".
584 $g->base64_out ($filename, $base64file);
586 This command downloads the contents of "filename", writing it out
587 to local file "base64file" encoded as base64.
588 %info = $g->blkid ($device);
590 This command returns block device attributes for "device". The
591 following fields are usually present in the returned hash. Other
592 fields may also be present.
593 "UUID"
595 The uuid of this device.
596 "LABEL"
598 The label of this device.
599 "VERSION"
601 The version of blkid command.
602 "TYPE"
604 The filesystem type or RAID of this device.
605 "USAGE"
607 The usage of this device, for example "filesystem" or "raid".
608 $g->blockdev_flushbufs ($device);
610 This tells the kernel to flush internal buffers associated with
611 "device".
612 This uses the blockdev(8) command.
614 $blocksize = $g->blockdev_getbsz ($device);
616 This returns the block size of a device.
617 Note: this is different from both size in blocks and filesystem
619 block size. Also this setting is not really used by anything. You
620 should probably not use it for anything. Filesystems have their
621 own idea about what block size to choose.
622 This uses the blockdev(8) command.
624 $ro = $g->blockdev_getro ($device);
626 Returns a boolean indicating if the block device is read-only (true
627 if read-only, false if not).
628 This uses the blockdev(8) command.
630 $sizeinbytes = $g->blockdev_getsize64 ($device);
632 This returns the size of the device in bytes.
633 See also "$g->blockdev_getsz".
635 This uses the blockdev(8) command.
637 $sectorsize = $g->blockdev_getss ($device);
639 This returns the size of sectors on a block device. Usually 512,
640 but can be larger for modern devices.
641 (Note, this is not the size in sectors, use "$g->blockdev_getsz"
643 for that).
644 This uses the blockdev(8) command.
646 $sizeinsectors = $g->blockdev_getsz ($device);
648 This returns the size of the device in units of 512-byte sectors
649 (even if the sectorsize isn't 512 bytes ... weird).
650 See also "$g->blockdev_getss" for the real sector size of the
652 device, and "$g->blockdev_getsize64" for the more useful size in
653 bytes.
654 This uses the blockdev(8) command.
656 $g->blockdev_rereadpt ($device);
658 Reread the partition table on "device".
659 This uses the blockdev(8) command.
661 $g->blockdev_setbsz ($device, $blocksize);
663 This call does nothing and has never done anything because of a bug
664 in blockdev. Do not use it.
665 If you need to set the filesystem block size, use the "blocksize"
667 option of "$g->mkfs".
668 This function is deprecated. In new code, use the "mkfs" call
670 instead.
671 Deprecated functions will not be removed from the API, but the fact
673 that they are deprecated indicates that there are problems with
674 correct use of these functions.
675 $g->blockdev_setro ($device);
677 Sets the block device named "device" to read-only.
678 This uses the blockdev(8) command.
680 $g->blockdev_setrw ($device);
682 Sets the block device named "device" to read-write.
683 This uses the blockdev(8) command.
685 $g->btrfs_device_add (\@devices, $fs);
687 Add the list of device(s) in "devices" to the btrfs filesystem
688 mounted at "fs". If "devices" is an empty list, this does nothing.
689 $g->btrfs_device_delete (\@devices, $fs);
691 Remove the "devices" from the btrfs filesystem mounted at "fs". If
692 "devices" is an empty list, this does nothing.
693 $g->btrfs_filesystem_balance ($fs);
695 Balance the chunks in the btrfs filesystem mounted at "fs" across
696 the underlying devices.
697 $g->btrfs_filesystem_resize ($mountpoint [, size => $size]);
699 This command resizes a btrfs filesystem.
700 Note that unlike other resize calls, the filesystem has to be
702 mounted and the parameter is the mountpoint not the device (this is
703 a requirement of btrfs itself).
704 The optional parameters are:
706 "size"
708 The new size (in bytes) of the filesystem. If omitted, the
709 filesystem is resized to the maximum size.
710 See also btrfs(8).
712 $g->btrfs_filesystem_sync ($fs);
714 Force sync on the btrfs filesystem mounted at "fs".
715 $g->btrfs_fsck ($device [, superblock => $superblock] [, repair =>
717 $repair]);
718 Used to check a btrfs filesystem, "device" is the device file where
719 the filesystem is stored.
720 $g->btrfs_set_seeding ($device, $seeding);
722 Enable or disable the seeding feature of a device that contains a
723 btrfs filesystem.
724 $g->btrfs_subvolume_create ($dest);
726 Create a btrfs subvolume. The "dest" argument is the destination
727 directory and the name of the snapshot, in the form
728 "/path/to/dest/name".
729 $g->btrfs_subvolume_delete ($subvolume);
731 Delete the named btrfs subvolume.
732 @subvolumes = $g->btrfs_subvolume_list ($fs);
734 List the btrfs snapshots and subvolumes of the btrfs filesystem
735 which is mounted at "fs".
736 $g->btrfs_subvolume_set_default ($id, $fs);
738 Set the subvolume of the btrfs filesystem "fs" which will be
739 mounted by default. See "$g->btrfs_subvolume_list" to get a list
740 of subvolumes.
741 $g->btrfs_subvolume_snapshot ($source, $dest);
743 Create a writable snapshot of the btrfs subvolume "source". The
744 "dest" argument is the destination directory and the name of the
745 snapshot, in the form "/path/to/dest/name".
746 $canonical = $g->canonical_device_name ($device);
748 This utility function is useful when displaying device names to the
749 user. It takes a number of irregular device names and returns them
750 in a consistent format:
751 "/dev/hdX"
753 "/dev/vdX"
754 These are returned as "/dev/sdX". Note this works for device
755 names and partition names. This is approximately the reverse
756 of the algorithm described in "BLOCK DEVICE NAMING" in
757 guestfs(3).
758 "/dev/mapper/VG-LV"
760 "/dev/dm-N"
761 Converted to "/dev/VG/LV" form using
762 "$g->lvm_canonical_lvm_name".
763 Other strings are returned unmodified.
765 $cap = $g->cap_get_file ($path);
767 This function returns the Linux capabilities attached to "path".
768 The capabilities set is returned in text form (see cap_to_text(3)).
769 If no capabilities are attached to a file, an empty string is
771 returned.
772 $g->cap_set_file ($path, $cap);
774 This function sets the Linux capabilities attached to "path". The
775 capabilities set "cap" should be passed in text form (see
776 cap_from_text(3)).
777 $rpath = $g->case_sensitive_path ($path);
779 This can be used to resolve case insensitive paths on a filesystem
780 which is case sensitive. The use case is to resolve paths which
781 you have read from Windows configuration files or the Windows
782 Registry, to the true path.
783 The command handles a peculiarity of the Linux ntfs-3g filesystem
785 driver (and probably others), which is that although the underlying
786 filesystem is case-insensitive, the driver exports the filesystem
787 to Linux as case-sensitive.
788 One consequence of this is that special directories such as
790 "c:\windows" may appear as "/WINDOWS" or "/windows" (or other
791 things) depending on the precise details of how they were created.
792 In Windows itself this would not be a problem.
793 Bug or feature? You decide:
795 <http://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1>
796 This function resolves the true case of each element in the path
798 and returns the case-sensitive path.
799 Thus "$g->case_sensitive_path" ("/Windows/System32") might return
801 "/WINDOWS/system32" (the exact return value would depend on details
802 of how the directories were originally created under Windows).
803 Note: This function does not handle drive names, backslashes etc.
805 See also "$g->realpath".
807 $content = $g->cat ($path);
809 Return the contents of the file named "path".
810 Because, in C, this function returns a "char *", there is no way to
812 differentiate between a "\0" character in a file and end of string.
813 To handle binary files, use the "$g->read_file" or "$g->download"
814 functions.
815 $checksum = $g->checksum ($csumtype, $path);
817 This call computes the MD5, SHAx or CRC checksum of the file named
818 "path".
819 The type of checksum to compute is given by the "csumtype"
821 parameter which must have one of the following values:
822 "crc"
824 Compute the cyclic redundancy check (CRC) specified by POSIX
825 for the "cksum" command.
826 "md5"
828 Compute the MD5 hash (using the "md5sum" program).
829 "sha1"
831 Compute the SHA1 hash (using the "sha1sum" program).
832 "sha224"
834 Compute the SHA224 hash (using the "sha224sum" program).
835 "sha256"
837 Compute the SHA256 hash (using the "sha256sum" program).
838 "sha384"
840 Compute the SHA384 hash (using the "sha384sum" program).
841 "sha512"
843 Compute the SHA512 hash (using the "sha512sum" program).
844 The checksum is returned as a printable string.
846 To get the checksum for a device, use "$g->checksum_device".
848 To get the checksums for many files, use "$g->checksums_out".
850 $checksum = $g->checksum_device ($csumtype, $device);
852 This call computes the MD5, SHAx or CRC checksum of the contents of
853 the device named "device". For the types of checksums supported
854 see the "$g->checksum" command.
855 $g->checksums_out ($csumtype, $directory, $sumsfile);
857 This command computes the checksums of all regular files in
858 "directory" and then emits a list of those checksums to the local
859 output file "sumsfile".
860 This can be used for verifying the integrity of a virtual machine.
862 However to be properly secure you should pay attention to the
863 output of the checksum command (it uses the ones from GNU
864 coreutils). In particular when the filename is not printable,
865 coreutils uses a special backslash syntax. For more information,
866 see the GNU coreutils info file.
867 $g->chmod ($mode, $path);
869 Change the mode (permissions) of "path" to "mode". Only numeric
870 modes are supported.
871 Note: When using this command from guestfish, "mode" by default
873 would be decimal, unless you prefix it with 0 to get octal, ie. use
874 0700 not 700.
875 The mode actually set is affected by the umask.
877 $g->chown ($owner, $group, $path);
879 Change the file owner to "owner" and group to "group".
880 Only numeric uid and gid are supported. If you want to use names,
882 you will need to locate and parse the password file yourself
883 (Augeas support makes this relatively easy).
884 $output = $g->command (\@arguments);
886 This call runs a command from the guest filesystem. The filesystem
887 must be mounted, and must contain a compatible operating system
888 (ie. something Linux, with the same or compatible processor
889 architecture).
890 The single parameter is an argv-style list of arguments. The first
892 element is the name of the program to run. Subsequent elements are
893 parameters. The list must be non-empty (ie. must contain a program
894 name). Note that the command runs directly, and is not invoked via
895 the shell (see "$g->sh").
896 The return value is anything printed to stdout by the command.
898 If the command returns a non-zero exit status, then this function
900 returns an error message. The error message string is the content
901 of stderr from the command.
902 The $PATH environment variable will contain at least "/usr/bin" and
904 "/bin". If you require a program from another location, you should
905 provide the full path in the first parameter.
906 Shared libraries and data files required by the program must be
908 available on filesystems which are mounted in the correct places.
909 It is the caller's responsibility to ensure all filesystems that
910 are needed are mounted at the right locations.
911 Because of the message protocol, there is a transfer limit of
913 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
914 guestfs(3).
915 @lines = $g->command_lines (\@arguments);
917 This is the same as "$g->command", but splits the result into a
918 list of lines.
919 See also: "$g->sh_lines"
921 Because of the message protocol, there is a transfer limit of
923 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
924 guestfs(3).
925 $g->compress_device_out ($ctype, $device, $zdevice [, level =>
927 $level]);
928 This command compresses "device" and writes it out to the local
929 file "zdevice".
930 The "ctype" and optional "level" parameters have the same meaning
932 as in "$g->compress_out".
933 $g->compress_out ($ctype, $file, $zfile [, level => $level]);
935 This command compresses "file" and writes it out to the local file
936 "zfile".
937 The compression program used is controlled by the "ctype"
939 parameter. Currently this includes: "compress", "gzip", "bzip2",
940 "xz" or "lzop". Some compression types may not be supported by
941 particular builds of libguestfs, in which case you will get an
942 error containing the substring "not supported".
943 The optional "level" parameter controls compression level. The
945 meaning and default for this parameter depends on the compression
946 program being used.
947 $g->config ($qemuparam, $qemuvalue);
949 This can be used to add arbitrary qemu command line parameters of
950 the form -param value. Actually it's not quite arbitrary - we
951 prevent you from setting some parameters which would interfere with
952 parameters that we use.
953 The first character of "qemuparam" string must be a "-" (dash).
955 "qemuvalue" can be NULL.
957 $g->copy_device_to_device ($src, $dest [, srcoffset => $srcoffset] [,
959 destoffset => $destoffset] [, size => $size]);
960 The four calls "$g->copy_device_to_device",
961 "$g->copy_device_to_file", "$g->copy_file_to_device", and
962 "$g->copy_file_to_file" let you copy from a source (device|file) to
963 a destination (device|file).
964 Partial copies can be made since you can specify optionally the
966 source offset, destination offset and size to copy. These values
967 are all specified in bytes. If not given, the offsets both default
968 to zero, and the size defaults to copying as much as possible until
969 we hit the end of the source.
970 The source and destination may be the same object. However
972 overlapping regions may not be copied correctly.
973 If the destination is a file, it is created if required. If the
975 destination file is not large enough, it is extended.
976 $g->copy_device_to_file ($src, $dest [, srcoffset => $srcoffset] [,
978 destoffset => $destoffset] [, size => $size]);
979 See "$g->copy_device_to_device" for a general overview of this
980 call.
981 $g->copy_file_to_device ($src, $dest [, srcoffset => $srcoffset] [,
983 destoffset => $destoffset] [, size => $size]);
984 See "$g->copy_device_to_device" for a general overview of this
985 call.
986 $g->copy_file_to_file ($src, $dest [, srcoffset => $srcoffset] [,
988 destoffset => $destoffset] [, size => $size]);
989 See "$g->copy_device_to_device" for a general overview of this
990 call.
991 This is not the function you want for copying files. This is for
993 copying blocks within existing files. See "$g->cp", "$g->cp_a" and
994 "$g->mv" for general file copying and moving functions.
995 $g->copy_size ($src, $dest, $size);
997 This command copies exactly "size" bytes from one source device or
998 file "src" to another destination device or file "dest".
999 Note this will fail if the source is too short or if the
1001 destination is not large enough.
1002 This function is deprecated. In new code, use the
1004 "copy_device_to_device" call instead.
1005 Deprecated functions will not be removed from the API, but the fact
1007 that they are deprecated indicates that there are problems with
1008 correct use of these functions.
1009 $g->cp ($src, $dest);
1011 This copies a file from "src" to "dest" where "dest" is either a
1012 destination filename or destination directory.
1013 $g->cp_a ($src, $dest);
1015 This copies a file or directory from "src" to "dest" recursively
1016 using the "cp -a" command.
1017 $g->dd ($src, $dest);
1019 This command copies from one source device or file "src" to another
1020 destination device or file "dest". Normally you would use this to
1021 copy to or from a device or partition, for example to duplicate a
1022 filesystem.
1023 If the destination is a device, it must be as large or larger than
1025 the source file or device, otherwise the copy will fail. This
1026 command cannot do partial copies (see "$g->copy_device_to_device").
1027 This function is deprecated. In new code, use the
1029 "copy_device_to_device" call instead.
1030 Deprecated functions will not be removed from the API, but the fact
1032 that they are deprecated indicates that there are problems with
1033 correct use of these functions.
1034 $index = $g->device_index ($device);
1036 This function takes a device name (eg. "/dev/sdb") and returns the
1037 index of the device in the list of devices.
1038 Index numbers start from 0. The named device must exist, for
1040 example as a string returned from "$g->list_devices".
1041 See also "$g->list_devices", "$g->part_to_dev".
1043 $output = $g->df ();
1045 This command runs the "df" command to report disk space used.
1046 This command is mostly useful for interactive sessions. It is not
1048 intended that you try to parse the output string. Use
1049 "$g->statvfs" from programs.
1050 $output = $g->df_h ();
1052 This command runs the "df -h" command to report disk space used in
1053 human-readable format.
1054 This command is mostly useful for interactive sessions. It is not
1056 intended that you try to parse the output string. Use
1057 "$g->statvfs" from programs.
1058 $format = $g->disk_format ($filename);
1060 Detect and return the format of the disk image called "filename".
1061 "filename" can also be a host device, etc. If the format of the
1062 image could not be detected, then "unknown" is returned.
1063 Note that detecting the disk format can be insecure under some
1065 circumstances. See "CVE-2010-3851" in guestfs(3).
1066 See also: "DISK IMAGE FORMATS" in guestfs(3)
1068 $backingfile = $g->disk_has_backing_file ($filename);
1070 Detect and return whether the disk image "filename" has a backing
1071 file.
1072 Note that detecting disk features can be insecure under some
1074 circumstances. See "CVE-2010-3851" in guestfs(3).
1075 $size = $g->disk_virtual_size ($filename);
1077 Detect and return the virtual size in bytes of the disk image
1078 called "filename".
1079 Note that detecting disk features can be insecure under some
1081 circumstances. See "CVE-2010-3851" in guestfs(3).
1082 $kmsgs = $g->dmesg ();
1084 This returns the kernel messages ("dmesg" output) from the guest
1085 kernel. This is sometimes useful for extended debugging of
1086 problems.
1087 Another way to get the same information is to enable verbose
1089 messages with "$g->set_verbose" or by setting the environment
1090 variable "LIBGUESTFS_DEBUG=1" before running the program.
1091 $g->download ($remotefilename, $filename);
1093 Download file "remotefilename" and save it as "filename" on the
1094 local machine.
1095 "filename" can also be a named pipe.
1097 See also "$g->upload", "$g->cat".
1099 $g->download_offset ($remotefilename, $filename, $offset, $size);
1101 Download file "remotefilename" and save it as "filename" on the
1102 local machine.
1103 "remotefilename" is read for "size" bytes starting at "offset"
1105 (this region must be within the file or device).
1106 Note that there is no limit on the amount of data that can be
1108 downloaded with this call, unlike with "$g->pread", and this call
1109 always reads the full amount unless an error occurs.
1110 See also "$g->download", "$g->pread".
1112 $g->drop_caches ($whattodrop);
1114 This instructs the guest kernel to drop its page cache, and/or
1115 dentries and inode caches. The parameter "whattodrop" tells the
1116 kernel what precisely to drop, see
1117 <http://linux-mm.org/Drop_Caches>
1118 Setting "whattodrop" to 3 should drop everything.
1120 This automatically calls sync(2) before the operation, so that the
1122 maximum guest memory is freed.
1123 $sizekb = $g->du ($path);
1125 This command runs the "du -s" command to estimate file space usage
1126 for "path".
1127 "path" can be a file or a directory. If "path" is a directory then
1129 the estimate includes the contents of the directory and all
1130 subdirectories (recursively).
1131 The result is the estimated size in kilobytes (ie. units of 1024
1133 bytes).
1134 $g->e2fsck ($device [, correct => $correct] [, forceall => $forceall]);
1136 This runs the ext2/ext3 filesystem checker on "device". It can
1137 take the following optional arguments:
1138 "correct"
1140 Automatically repair the file system. This option will cause
1141 e2fsck to automatically fix any filesystem problems that can be
1142 safely fixed without human intervention.
1143 This option may not be specified at the same time as the
1145 "forceall" option.
1146 "forceall"
1148 Assume an answer of 'yes' to all questions; allows e2fsck to be
1149 used non-interactively.
1150 This option may not be specified at the same time as the
1152 "correct" option.
1153 $g->e2fsck_f ($device);
1155 This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
1156 checker on "device", noninteractively (-p), even if the filesystem
1157 appears to be clean (-f).
1158 This function is deprecated. In new code, use the "e2fsck" call
1160 instead.
1161 Deprecated functions will not be removed from the API, but the fact
1163 that they are deprecated indicates that there are problems with
1164 correct use of these functions.
1165 $output = $g->echo_daemon (\@words);
1167 This command concatenates the list of "words" passed with single
1168 spaces between them and returns the resulting string.
1169 You can use this command to test the connection through to the
1171 daemon.
1172 See also "$g->ping_daemon".
1174 @lines = $g->egrep ($regex, $path);
1176 This calls the external "egrep" program and returns the matching
1177 lines.
1178 Because of the message protocol, there is a transfer limit of
1180 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1181 guestfs(3).
1182 This function is deprecated. In new code, use the "grep" call
1184 instead.
1185 Deprecated functions will not be removed from the API, but the fact
1187 that they are deprecated indicates that there are problems with
1188 correct use of these functions.
1189 @lines = $g->egrepi ($regex, $path);
1191 This calls the external "egrep -i" program and returns the matching
1192 lines.
1193 Because of the message protocol, there is a transfer limit of
1195 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1196 guestfs(3).
1197 This function is deprecated. In new code, use the "grep" call
1199 instead.
1200 Deprecated functions will not be removed from the API, but the fact
1202 that they are deprecated indicates that there are problems with
1203 correct use of these functions.
1204 $equality = $g->equal ($file1, $file2);
1206 This compares the two files "file1" and "file2" and returns true if
1207 their content is exactly equal, or false otherwise.
1208 The external cmp(1) program is used for the comparison.
1210 $existsflag = $g->exists ($path);
1212 This returns "true" if and only if there is a file, directory (or
1213 anything) with the given "path" name.
1214 See also "$g->is_file", "$g->is_dir", "$g->stat".
1216 $g->fallocate ($path, $len);
1218 This command preallocates a file (containing zero bytes) named
1219 "path" of size "len" bytes. If the file exists already, it is
1220 overwritten.
1221 Do not confuse this with the guestfish-specific "alloc" command
1223 which allocates a file in the host and attaches it as a device.
1224 This function is deprecated. In new code, use the "fallocate64"
1226 call instead.
1227 Deprecated functions will not be removed from the API, but the fact
1229 that they are deprecated indicates that there are problems with
1230 correct use of these functions.
1231 $g->fallocate64 ($path, $len);
1233 This command preallocates a file (containing zero bytes) named
1234 "path" of size "len" bytes. If the file exists already, it is
1235 overwritten.
1236 Note that this call allocates disk blocks for the file. To create
1238 a sparse file use "$g->truncate_size" instead.
1239 The deprecated call "$g->fallocate" does the same, but owing to an
1241 oversight it only allowed 30 bit lengths to be specified,
1242 effectively limiting the maximum size of files created through that
1243 call to 1GB.
1244 Do not confuse this with the guestfish-specific "alloc" and
1246 "sparse" commands which create a file in the host and attach it as
1247 a device.
1248 @lines = $g->fgrep ($pattern, $path);
1250 This calls the external "fgrep" program and returns the matching
1251 lines.
1252 Because of the message protocol, there is a transfer limit of
1254 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1255 guestfs(3).
1256 This function is deprecated. In new code, use the "grep" call
1258 instead.
1259 Deprecated functions will not be removed from the API, but the fact
1261 that they are deprecated indicates that there are problems with
1262 correct use of these functions.
1263 @lines = $g->fgrepi ($pattern, $path);
1265 This calls the external "fgrep -i" program and returns the matching
1266 lines.
1267 Because of the message protocol, there is a transfer limit of
1269 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1270 guestfs(3).
1271 This function is deprecated. In new code, use the "grep" call
1273 instead.
1274 Deprecated functions will not be removed from the API, but the fact
1276 that they are deprecated indicates that there are problems with
1277 correct use of these functions.
1278 $description = $g->file ($path);
1280 This call uses the standard file(1) command to determine the type
1281 or contents of the file.
1282 This call will also transparently look inside various types of
1284 compressed file.
1285 The exact command which runs is "file -zb path". Note in
1287 particular that the filename is not prepended to the output (the -b
1288 option).
1289 The output depends on the output of the underlying file(1) command
1291 and it can change in future in ways beyond our control. In other
1292 words, the output is not guaranteed by the ABI.
1293 See also: file(1), "$g->vfs_type", "$g->lstat", "$g->is_file",
1295 "$g->is_blockdev" (etc), "$g->is_zero".
1296 $arch = $g->file_architecture ($filename);
1298 This detects the architecture of the binary "filename", and returns
1299 it if known.
1300 Currently defined architectures are:
1302 "i386"
1304 This string is returned for all 32 bit i386, i486, i586, i686
1305 binaries irrespective of the precise processor requirements of
1306 the binary.
1307 "x86_64"
1309 64 bit x86-64.
1310 "sparc"
1312 32 bit SPARC.
1313 "sparc64"
1315 64 bit SPARC V9 and above.
1316 "ia64"
1318 Intel Itanium.
1319 "ppc"
1321 32 bit Power PC.
1322 "ppc64"
1324 64 bit Power PC.
1325 Libguestfs may return other architecture strings in future.
1327 The function works on at least the following types of files:
1329 ยท many types of Un*x and Linux binary
1331 ยท many types of Un*x and Linux shared library
1333 ยท Windows Win32 and Win64 binaries
1335 ยท Windows Win32 and Win64 DLLs
1337 Win32 binaries and DLLs return "i386".
1339 Win64 binaries and DLLs return "x86_64".
1341 ยท Linux kernel modules
1343 ยท Linux new-style initrd images
1345 ยท some non-x86 Linux vmlinuz kernels
1347 What it can't do currently:
1349 ยท static libraries (libfoo.a)
1351 ยท Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
1353 ยท x86 Linux vmlinuz kernels
1355 x86 vmlinuz images (bzImage format) consist of a mix of 16-,
1357 32- and compressed code, and are horribly hard to unpack. If
1358 you want to find the architecture of a kernel, use the
1359 architecture of the associated initrd or kernel module(s)
1360 instead.
1361 $size = $g->filesize ($file);
1363 This command returns the size of "file" in bytes.
1364 To get other stats about a file, use "$g->stat", "$g->lstat",
1366 "$g->is_dir", "$g->is_file" etc. To get the size of block devices,
1367 use "$g->blockdev_getsize64".
1368 $fsavail = $g->filesystem_available ($filesystem);
1370 Check whether libguestfs supports the named filesystem. The
1371 argument "filesystem" is a filesystem name, such as "ext3".
1372 You must call "$g->launch" before using this command.
1374 This is mainly useful as a negative test. If this returns true, it
1376 doesn't mean that a particular filesystem can be created or
1377 mounted, since filesystems can fail for other reasons such as it
1378 being a later version of the filesystem, or having incompatible
1379 features, or lacking the right mkfs.<fs> tool.
1380 See also "$g->available", "AVAILABILITY" in guestfs(3).
1382 $g->fill ($c, $len, $path);
1384 This command creates a new file called "path". The initial content
1385 of the file is "len" octets of "c", where "c" must be a number in
1386 the range "[0..255]".
1387 To fill a file with zero bytes (sparsely), it is much more
1389 efficient to use "$g->truncate_size". To create a file with a
1390 pattern of repeating bytes use "$g->fill_pattern".
1391 $g->fill_dir ($dir, $nr);
1393 This function, useful for testing filesystems, creates "nr" empty
1394 files in the directory "dir" with names 00000000 through "nr-1"
1395 (ie. each file name is 8 digits long padded with zeroes).
1396 $g->fill_pattern ($pattern, $len, $path);
1398 This function is like "$g->fill" except that it creates a new file
1399 of length "len" containing the repeating pattern of bytes in
1400 "pattern". The pattern is truncated if necessary to ensure the
1401 length of the file is exactly "len" bytes.
1402 @names = $g->find ($directory);
1404 This command lists out all files and directories, recursively,
1405 starting at "directory". It is essentially equivalent to running
1406 the shell command "find directory -print" but some post-processing
1407 happens on the output, described below.
1408 This returns a list of strings without any prefix. Thus if the
1410 directory structure was:
1411 /tmp/a
1413 /tmp/b
1414 /tmp/c/d
1415 then the returned list from "$g->find" "/tmp" would be 4 elements:
1417 a
1419 b
1420 c
1421 c/d
1422 If "directory" is not a directory, then this command returns an
1424 error.
1425 The returned list is sorted.
1427 $g->find0 ($directory, $files);
1429 This command lists out all files and directories, recursively,
1430 starting at "directory", placing the resulting list in the external
1431 file called "files".
1432 This command works the same way as "$g->find" with the following
1434 exceptions:
1435 ยท The resulting list is written to an external file.
1437 ยท Items (filenames) in the result are separated by "\0"
1439 characters. See find(1) option -print0.
1440 ยท The result list is not sorted.
1442 $device = $g->findfs_label ($label);
1444 This command searches the filesystems and returns the one which has
1445 the given label. An error is returned if no such filesystem can be
1446 found.
1447 To find the label of a filesystem, use "$g->vfs_label".
1449 $device = $g->findfs_uuid ($uuid);
1451 This command searches the filesystems and returns the one which has
1452 the given UUID. An error is returned if no such filesystem can be
1453 found.
1454 To find the UUID of a filesystem, use "$g->vfs_uuid".
1456 $status = $g->fsck ($fstype, $device);
1458 This runs the filesystem checker (fsck) on "device" which should
1459 have filesystem type "fstype".
1460 The returned integer is the status. See fsck(8) for the list of
1462 status codes from "fsck".
1463 Notes:
1465 ยท Multiple status codes can be summed together.
1467 ยท A non-zero return code can mean "success", for example if
1469 errors have been corrected on the filesystem.
1470 ยท Checking or repairing NTFS volumes is not supported (by linux-
1472 ntfs).
1473 This command is entirely equivalent to running "fsck -a -t fstype
1475 device".
1476 $append = $g->get_append ();
1478 Return the additional kernel options which are added to the
1479 libguestfs appliance kernel command line.
1480 If "NULL" then no options are added.
1482 $attachmethod = $g->get_attach_method ();
1484 Return the current attach method.
1485 See "$g->set_attach_method" and "ATTACH METHOD" in guestfs(3).
1487 $autosync = $g->get_autosync ();
1489 Get the autosync flag.
1490 $cachedir = $g->get_cachedir ();
1492 Get the directory used by the handle to store the appliance cache.
1493 $direct = $g->get_direct ();
1495 Return the direct appliance mode flag.
1496 $attrs = $g->get_e2attrs ($file);
1498 This returns the file attributes associated with "file".
1499 The attributes are a set of bits associated with each inode which
1501 affect the behaviour of the file. The attributes are returned as a
1502 string of letters (described below). The string may be empty,
1503 indicating that no file attributes are set for this file.
1504 These attributes are only present when the file is located on an
1506 ext2/3/4 filesystem. Using this call on other filesystem types
1507 will result in an error.
1508 The characters (file attributes) in the returned string are
1510 currently:
1511 'A' When the file is accessed, its atime is not modified.
1513 'a' The file is append-only.
1515 'c' The file is compressed on-disk.
1517 'D' (Directories only.) Changes to this directory are written
1519 synchronously to disk.
1520 'd' The file is not a candidate for backup (see dump(8)).
1522 'E' The file has compression errors.
1524 'e' The file is using extents.
1526 'h' The file is storing its blocks in units of the filesystem
1528 blocksize instead of sectors.
1529 'I' (Directories only.) The directory is using hashed trees.
1531 'i' The file is immutable. It cannot be modified, deleted or
1533 renamed. No link can be created to this file.
1534 'j' The file is data-journaled.
1536 's' When the file is deleted, all its blocks will be zeroed.
1538 'S' Changes to this file are written synchronously to disk.
1540 'T' (Directories only.) This is a hint to the block allocator that
1542 subdirectories contained in this directory should be spread
1543 across blocks. If not present, the block allocator will try to
1544 group subdirectories together.
1545 't' For a file, this disables tail-merging. (Not used by upstream
1547 implementations of ext2.)
1548 'u' When the file is deleted, its blocks will be saved, allowing
1550 the file to be undeleted.
1551 'X' The raw contents of the compressed file may be accessed.
1553 'Z' The compressed file is dirty.
1555 More file attributes may be added to this list later. Not all file
1557 attributes may be set for all kinds of files. For detailed
1558 information, consult the chattr(1) man page.
1559 See also "$g->set_e2attrs".
1561 Don't confuse these attributes with extended attributes (see
1563 "$g->getxattr").
1564 $generation = $g->get_e2generation ($file);
1566 This returns the ext2 file generation of a file. The generation
1567 (which used to be called the "version") is a number associated with
1568 an inode. This is most commonly used by NFS servers.
1569 The generation is only present when the file is located on an
1571 ext2/3/4 filesystem. Using this call on other filesystem types
1572 will result in an error.
1573 See "$g->set_e2generation".
1575 $label = $g->get_e2label ($device);
1577 This returns the ext2/3/4 filesystem label of the filesystem on
1578 "device".
1579 This function is deprecated. In new code, use the "vfs_label" call
1581 instead.
1582 Deprecated functions will not be removed from the API, but the fact
1584 that they are deprecated indicates that there are problems with
1585 correct use of these functions.
1586 $uuid = $g->get_e2uuid ($device);
1588 This returns the ext2/3/4 filesystem UUID of the filesystem on
1589 "device".
1590 This function is deprecated. In new code, use the "vfs_uuid" call
1592 instead.
1593 Deprecated functions will not be removed from the API, but the fact
1595 that they are deprecated indicates that there are problems with
1596 correct use of these functions.
1597 $challenge = $g->get_libvirt_requested_credential_challenge ($index);
1599 Get the challenge (provided by libvirt) for the "index"'th
1600 requested credential. If libvirt did not provide a challenge, this
1601 returns the empty string "".
1602 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
1604 example code.
1605 $defresult = $g->get_libvirt_requested_credential_defresult ($index);
1607 Get the default result (provided by libvirt) for the "index"'th
1608 requested credential. If libvirt did not provide a default result,
1609 this returns the empty string "".
1610 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
1612 example code.
1613 $prompt = $g->get_libvirt_requested_credential_prompt ($index);
1615 Get the prompt (provided by libvirt) for the "index"'th requested
1616 credential. If libvirt did not provide a prompt, this returns the
1617 empty string "".
1618 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
1620 example code.
1621 @creds = $g->get_libvirt_requested_credentials ();
1623 This should only be called during the event callback for events of
1624 type "GUESTFS_EVENT_LIBVIRT_AUTH".
1625 Return the list of credentials requested by libvirt. Possible
1627 values are a subset of the strings provided when you called
1628 "$g->set_libvirt_supported_credentials".
1629 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
1631 example code.
1632 $memsize = $g->get_memsize ();
1634 This gets the memory size in megabytes allocated to the qemu
1635 subprocess.
1636 If "$g->set_memsize" was not called on this handle, and if
1638 "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
1639 default value for memsize.
1640 For more information on the architecture of libguestfs, see
1642 guestfs(3).
1643 $network = $g->get_network ();
1645 This returns the enable network flag.
1646 $path = $g->get_path ();
1648 Return the current search path.
1649 This is always non-NULL. If it wasn't set already, then this will
1651 return the default path.
1652 $pgroup = $g->get_pgroup ();
1654 This returns the process group flag.
1655 $pid = $g->get_pid ();
1657 Return the process ID of the qemu subprocess. If there is no qemu
1658 subprocess, then this will return an error.
1659 This is an internal call used for debugging and testing.
1661 $qemu = $g->get_qemu ();
1663 Return the current qemu binary.
1664 This is always non-NULL. If it wasn't set already, then this will
1666 return the default qemu binary name.
1667 $recoveryproc = $g->get_recovery_proc ();
1669 Return the recovery process enabled flag.
1670 $selinux = $g->get_selinux ();
1672 This returns the current setting of the selinux flag which is
1673 passed to the appliance at boot time. See "$g->set_selinux".
1674 For more information on the architecture of libguestfs, see
1676 guestfs(3).
1677 $smp = $g->get_smp ();
1679 This returns the number of virtual CPUs assigned to the appliance.
1680 $state = $g->get_state ();
1682 This returns the current state as an opaque integer. This is only
1683 useful for printing debug and internal error messages.
1684 For more information on states, see guestfs(3).
1686 $tmpdir = $g->get_tmpdir ();
1688 Get the directory used by the handle to store temporary files.
1689 $trace = $g->get_trace ();
1691 Return the command trace flag.
1692 $mask = $g->get_umask ();
1694 Return the current umask. By default the umask is 022 unless it
1695 has been set by calling "$g->umask".
1696 $verbose = $g->get_verbose ();
1698 This returns the verbose messages flag.
1699 $context = $g->getcon ();
1701 This gets the SELinux security context of the daemon.
1702 See the documentation about SELINUX in guestfs(3), and "$g->setcon"
1704 $xattr = $g->getxattr ($path, $name);
1706 Get a single extended attribute from file "path" named "name".
1707 This call follows symlinks. If you want to lookup an extended
1708 attribute for the symlink itself, use "$g->lgetxattr".
1709 Normally it is better to get all extended attributes from a file in
1711 one go by calling "$g->getxattrs". However some Linux filesystem
1712 implementations are buggy and do not provide a way to list out
1713 attributes. For these filesystems (notably ntfs-3g) you have to
1714 know the names of the extended attributes you want in advance and
1715 call this function.
1716 Extended attribute values are blobs of binary data. If there is no
1718 extended attribute named "name", this returns an error.
1719 See also: "$g->getxattrs", "$g->lgetxattr", attr(5).
1721 @xattrs = $g->getxattrs ($path);
1723 This call lists the extended attributes of the file or directory
1724 "path".
1725 At the system call level, this is a combination of the listxattr(2)
1727 and getxattr(2) calls.
1728 See also: "$g->lgetxattrs", attr(5).
1730 @paths = $g->glob_expand ($pattern);
1732 This command searches for all the pathnames matching "pattern"
1733 according to the wildcard expansion rules used by the shell.
1734 If no paths match, then this returns an empty list (note: not an
1736 error).
1737 It is just a wrapper around the C glob(3) function with flags
1739 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
1740 Notice that there is no equivalent command for expanding a device
1742 name (eg. "/dev/sd*"). Use "$g->list_devices",
1743 "$g->list_partitions" etc functions instead.
1744 @lines = $g->grep ($regex, $path [, extended => $extended] [, fixed =>
1746 $fixed] [, insensitive => $insensitive] [, compressed => $compressed]);
1747 This calls the external "grep" program and returns the matching
1748 lines.
1749 The optional flags are:
1751 "extended"
1753 Use extended regular expressions. This is the same as using
1754 the -E flag.
1755 "fixed"
1757 Match fixed (don't use regular expressions). This is the same
1758 as using the -F flag.
1759 "insensitive"
1761 Match case-insensitive. This is the same as using the -i flag.
1762 "compressed"
1764 Use "zgrep" instead of "grep". This allows the input to be
1765 compress- or gzip-compressed.
1766 Because of the message protocol, there is a transfer limit of
1768 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1769 guestfs(3).
1770 @lines = $g->grep_opts ($regex, $path [, extended => $extended] [,
1772 fixed => $fixed] [, insensitive => $insensitive] [, compressed =>
1773 $compressed]);
1774 This is an alias of "grep".
1775 @lines = $g->grepi ($regex, $path);
1777 This calls the external "grep -i" program and returns the matching
1778 lines.
1779 Because of the message protocol, there is a transfer limit of
1781 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1782 guestfs(3).
1783 This function is deprecated. In new code, use the "grep" call
1785 instead.
1786 Deprecated functions will not be removed from the API, but the fact
1788 that they are deprecated indicates that there are problems with
1789 correct use of these functions.
1790 $g->grub_install ($root, $device);
1792 This command installs GRUB 1 (the Grand Unified Bootloader) on
1793 "device", with the root directory being "root".
1794 Notes:
1796 ยท There is currently no way in the API to install grub2, which is
1798 used by most modern Linux guests. It is possible to run the
1799 grub2 command from the guest, although see the caveats in
1800 "RUNNING COMMANDS" in guestfs(3).
1801 ยท This uses "grub-install" from the host. Unfortunately grub is
1803 not always compatible with itself, so this only works in rather
1804 narrow circumstances. Careful testing with each guest version
1805 is advisable.
1806 ยท If grub-install reports the error "No suitable drive was found
1808 in the generated device map." it may be that you need to
1809 create a "/boot/grub/device.map" file first that contains the
1810 mapping between grub device names and Linux device names. It
1811 is usually sufficient to create a file containing:
1812 (hd0) /dev/vda
1814 replacing "/dev/vda" with the name of the installation device.
1816 @lines = $g->head ($path);
1818 This command returns up to the first 10 lines of a file as a list
1819 of strings.
1820 Because of the message protocol, there is a transfer limit of
1822 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1823 guestfs(3).
1824 @lines = $g->head_n ($nrlines, $path);
1826 If the parameter "nrlines" is a positive number, this returns the
1827 first "nrlines" lines of the file "path".
1828 If the parameter "nrlines" is a negative number, this returns lines
1830 from the file "path", excluding the last "nrlines" lines.
1831 If the parameter "nrlines" is zero, this returns an empty list.
1833 Because of the message protocol, there is a transfer limit of
1835 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1836 guestfs(3).
1837 $dump = $g->hexdump ($path);
1839 This runs "hexdump -C" on the given "path". The result is the
1840 human-readable, canonical hex dump of the file.
1841 Because of the message protocol, there is a transfer limit of
1843 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1844 guestfs(3).
1845 $g->hivex_close ();
1847 Close the current hivex handle.
1848 This is a wrapper around the hivex(3) call of the same name.
1850 $g->hivex_commit ($filename);
1852 Commit (write) changes to the hive.
1853 If the optional "filename" parameter is null, then the changes are
1855 written back to the same hive that was opened. If this is not null
1856 then they are written to the alternate filename given and the
1857 original hive is left untouched.
1858 This is a wrapper around the hivex(3) call of the same name.
1860 $nodeh = $g->hivex_node_add_child ($parent, $name);
1862 Add a child node to "parent" named "name".
1863 This is a wrapper around the hivex(3) call of the same name.
1865 @nodehs = $g->hivex_node_children ($nodeh);
1867 Return the list of nodes which are subkeys of "nodeh".
1868 This is a wrapper around the hivex(3) call of the same name.
1870 $g->hivex_node_delete_child ($nodeh);
1872 Delete "nodeh", recursively if necessary.
1873 This is a wrapper around the hivex(3) call of the same name.
1875 $child = $g->hivex_node_get_child ($nodeh, $name);
1877 Return the child of "nodeh" with the name "name", if it exists.
1878 This can return 0 meaning the name was not found.
1879 This is a wrapper around the hivex(3) call of the same name.
1881 $valueh = $g->hivex_node_get_value ($nodeh, $key);
1883 Return the value attached to "nodeh" which has the name "key", if
1884 it exists. This can return 0 meaning the key was not found.
1885 This is a wrapper around the hivex(3) call of the same name.
1887 $name = $g->hivex_node_name ($nodeh);
1889 Return the name of "nodeh".
1890 This is a wrapper around the hivex(3) call of the same name.
1892 $parent = $g->hivex_node_parent ($nodeh);
1894 Return the parent node of "nodeh".
1895 This is a wrapper around the hivex(3) call of the same name.
1897 $g->hivex_node_set_value ($nodeh, $key, $t, $val);
1899 Set or replace a single value under the node "nodeh". The "key" is
1900 the name, "t" is the type, and "val" is the data.
1901 This is a wrapper around the hivex(3) call of the same name.
1903 @valuehs = $g->hivex_node_values ($nodeh);
1905 Return the array of (key, datatype, data) tuples attached to
1906 "nodeh".
1907 This is a wrapper around the hivex(3) call of the same name.
1909 $g->hivex_open ($filename [, verbose => $verbose] [, debug => $debug]
1911 [, write => $write]);
1912 Open the Windows Registry hive file named "filename". If there was
1913 any previous hivex handle associated with this guestfs session,
1914 then it is closed.
1915 This is a wrapper around the hivex(3) call of the same name.
1917 $nodeh = $g->hivex_root ();
1919 Return the root node of the hive.
1920 This is a wrapper around the hivex(3) call of the same name.
1922 $key = $g->hivex_value_key ($valueh);
1924 Return the key (name) field of a (key, datatype, data) tuple.
1925 This is a wrapper around the hivex(3) call of the same name.
1927 $datatype = $g->hivex_value_type ($valueh);
1929 Return the data type field from a (key, datatype, data) tuple.
1930 This is a wrapper around the hivex(3) call of the same name.
1932 $databuf = $g->hivex_value_utf8 ($valueh);
1934 This calls "$g->hivex_value_value" (which returns the data field
1935 from a hivex value tuple). It then assumes that the field is a
1936 UTF-16LE string and converts the result to UTF-8 (or if this is not
1937 possible, it returns an error).
1938 This is useful for reading strings out of the Windows registry.
1940 However it is not foolproof because the registry is not strongly-
1941 typed and fields can contain arbitrary or unexpected data.
1942 $databuf = $g->hivex_value_value ($valueh);
1944 Return the data field of a (key, datatype, data) tuple.
1945 This is a wrapper around the hivex(3) call of the same name.
1947 See also: "$g->hivex_value_utf8".
1949 $content = $g->initrd_cat ($initrdpath, $filename);
1951 This command unpacks the file "filename" from the initrd file
1952 called "initrdpath". The filename must be given without the
1953 initial "/" character.
1954 For example, in guestfish you could use the following command to
1956 examine the boot script (usually called "/init") contained in a
1957 Linux initrd or initramfs image:
1958 initrd-cat /boot/initrd-<version>.img init
1960 See also "$g->initrd_list".
1962 Because of the message protocol, there is a transfer limit of
1964 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1965 guestfs(3).
1966 @filenames = $g->initrd_list ($path);
1968 This command lists out files contained in an initrd.
1969 The files are listed without any initial "/" character. The files
1971 are listed in the order they appear (not necessarily alphabetical).
1972 Directory names are listed as separate items.
1973 Old Linux kernels (2.4 and earlier) used a compressed ext2
1975 filesystem as initrd. We only support the newer initramfs format
1976 (compressed cpio files).
1977 $wd = $g->inotify_add_watch ($path, $mask);
1979 Watch "path" for the events listed in "mask".
1980 Note that if "path" is a directory then events within that
1982 directory are watched, but this does not happen recursively (in
1983 subdirectories).
1984 Note for non-C or non-Linux callers: the inotify events are defined
1986 by the Linux kernel ABI and are listed in
1987 "/usr/include/sys/inotify.h".
1988 $g->inotify_close ();
1990 This closes the inotify handle which was previously opened by
1991 inotify_init. It removes all watches, throws away any pending
1992 events, and deallocates all resources.
1993 @paths = $g->inotify_files ();
1995 This function is a helpful wrapper around "$g->inotify_read" which
1996 just returns a list of pathnames of objects that were touched. The
1997 returned pathnames are sorted and deduplicated.
1998 $g->inotify_init ($maxevents);
2000 This command creates a new inotify handle. The inotify subsystem
2001 can be used to notify events which happen to objects in the guest
2002 filesystem.
2003 "maxevents" is the maximum number of events which will be queued up
2005 between calls to "$g->inotify_read" or "$g->inotify_files". If
2006 this is passed as 0, then the kernel (or previously set) default is
2007 used. For Linux 2.6.29 the default was 16384 events. Beyond this
2008 limit, the kernel throws away events, but records the fact that it
2009 threw them away by setting a flag "IN_Q_OVERFLOW" in the returned
2010 structure list (see "$g->inotify_read").
2011 Before any events are generated, you have to add some watches to
2013 the internal watch list. See: "$g->inotify_add_watch" and
2014 "$g->inotify_rm_watch".
2015 Queued up events should be read periodically by calling
2017 "$g->inotify_read" (or "$g->inotify_files" which is just a helpful
2018 wrapper around "$g->inotify_read"). If you don't read the events
2019 out often enough then you risk the internal queue overflowing.
2020 The handle should be closed after use by calling
2022 "$g->inotify_close". This also removes any watches automatically.
2023 See also inotify(7) for an overview of the inotify interface as
2025 exposed by the Linux kernel, which is roughly what we expose via
2026 libguestfs. Note that there is one global inotify handle per
2027 libguestfs instance.
2028 @events = $g->inotify_read ();
2030 Return the complete queue of events that have happened since the
2031 previous read call.
2032 If no events have happened, this returns an empty list.
2034 Note: In order to make sure that all events have been read, you
2036 must call this function repeatedly until it returns an empty list.
2037 The reason is that the call will read events up to the maximum
2038 appliance-to-host message size and leave remaining events in the
2039 queue.
2040 $g->inotify_rm_watch ($wd);
2042 Remove a previously defined inotify watch. See
2043 "$g->inotify_add_watch".
2044 $arch = $g->inspect_get_arch ($root);
2046 This returns the architecture of the inspected operating system.
2047 The possible return values are listed under
2048 "$g->file_architecture".
2049 If the architecture could not be determined, then the string
2051 "unknown" is returned.
2052 Please read "INSPECTION" in guestfs(3) for more details.
2054 $distro = $g->inspect_get_distro ($root);
2056 This returns the distro (distribution) of the inspected operating
2057 system.
2058 Currently defined distros are:
2060 "archlinux"
2062 Arch Linux.
2063 "buildroot"
2065 Buildroot-derived distro, but not one we specifically
2066 recognize.
2067 "centos"
2069 CentOS.
2070 "cirros"
2072 Cirros.
2073 "debian"
2075 Debian.
2076 "fedora"
2078 Fedora.
2079 "freedos"
2081 FreeDOS.
2082 "gentoo"
2084 Gentoo.
2085 "linuxmint"
2087 Linux Mint.
2088 "mageia"
2090 Mageia.
2091 "mandriva"
2093 Mandriva.
2094 "meego"
2096 MeeGo.
2097 "openbsd"
2099 OpenBSD.
2100 "opensuse"
2102 OpenSUSE.
2103 "pardus"
2105 Pardus.
2106 "redhat-based"
2108 Some Red Hat-derived distro.
2109 "rhel"
2111 Red Hat Enterprise Linux.
2112 "scientificlinux"
2114 Scientific Linux.
2115 "slackware"
2117 Slackware.
2118 "sles"
2120 SuSE Linux Enterprise Server or Desktop.
2121 "suse-based"
2123 Some openSuSE-derived distro.
2124 "ttylinux"
2126 ttylinux.
2127 "ubuntu"
2129 Ubuntu.
2130 "unknown"
2132 The distro could not be determined.
2133 "windows"
2135 Windows does not have distributions. This string is returned
2136 if the OS type is Windows.
2137 Future versions of libguestfs may return other strings here. The
2139 caller should be prepared to handle any string.
2140 Please read "INSPECTION" in guestfs(3) for more details.
2142 %drives = $g->inspect_get_drive_mappings ($root);
2144 This call is useful for Windows which uses a primitive system of
2145 assigning drive letters (like "C:") to partitions. This inspection
2146 API examines the Windows Registry to find out how disks/partitions
2147 are mapped to drive letters, and returns a hash table as in the
2148 example below:
2149 C => /dev/vda2
2151 E => /dev/vdb1
2152 F => /dev/vdc1
2153 Note that keys are drive letters. For Windows, the key is case
2155 insensitive and just contains the drive letter, without the
2156 customary colon separator character.
2157 In future we may support other operating systems that also used
2159 drive letters, but the keys for those might not be case insensitive
2160 and might be longer than 1 character. For example in OS-9, hard
2161 drives were named "h0", "h1" etc.
2162 For Windows guests, currently only hard drive mappings are
2164 returned. Removable disks (eg. DVD-ROMs) are ignored.
2165 For guests that do not use drive mappings, or if the drive mappings
2167 could not be determined, this returns an empty hash table.
2168 Please read "INSPECTION" in guestfs(3) for more details. See also
2170 "$g->inspect_get_mountpoints", "$g->inspect_get_filesystems".
2171 @filesystems = $g->inspect_get_filesystems ($root);
2173 This returns a list of all the filesystems that we think are
2174 associated with this operating system. This includes the root
2175 filesystem, other ordinary filesystems, and non-mounted devices
2176 like swap partitions.
2177 In the case of a multi-boot virtual machine, it is possible for a
2179 filesystem to be shared between operating systems.
2180 Please read "INSPECTION" in guestfs(3) for more details. See also
2182 "$g->inspect_get_mountpoints".
2183 $format = $g->inspect_get_format ($root);
2185 This returns the format of the inspected operating system. You can
2186 use it to detect install images, live CDs and similar.
2187 Currently defined formats are:
2189 "installed"
2191 This is an installed operating system.
2192 "installer"
2194 The disk image being inspected is not an installed operating
2195 system, but a bootable install disk, live CD, or similar.
2196 "unknown"
2198 The format of this disk image is not known.
2199 Future versions of libguestfs may return other strings here. The
2201 caller should be prepared to handle any string.
2202 Please read "INSPECTION" in guestfs(3) for more details.
2204 $hostname = $g->inspect_get_hostname ($root);
2206 This function returns the hostname of the operating system as found
2207 by inspection of the guest's configuration files.
2208 If the hostname could not be determined, then the string "unknown"
2210 is returned.
2211 Please read "INSPECTION" in guestfs(3) for more details.
2213 $icon = $g->inspect_get_icon ($root [, favicon => $favicon] [,
2215 highquality => $highquality]);
2216 This function returns an icon corresponding to the inspected
2217 operating system. The icon is returned as a buffer containing a
2218 PNG image (re-encoded to PNG if necessary).
2219 If it was not possible to get an icon this function returns a zero-
2221 length (non-NULL) buffer. Callers must check for this case.
2222 Libguestfs will start by looking for a file called
2224 "/etc/favicon.png" or "C:\etc\favicon.png" and if it has the
2225 correct format, the contents of this file will be returned. You
2226 can disable favicons by passing the optional "favicon" boolean as
2227 false (default is true).
2228 If finding the favicon fails, then we look in other places in the
2230 guest for a suitable icon.
2231 If the optional "highquality" boolean is true then only high
2233 quality icons are returned, which means only icons of high
2234 resolution with an alpha channel. The default (false) is to return
2235 any icon we can, even if it is of substandard quality.
2236 Notes:
2238 ยท Unlike most other inspection API calls, the guest's disks must
2240 be mounted up before you call this, since it needs to read
2241 information from the guest filesystem during the call.
2242 ยท Security: The icon data comes from the untrusted guest, and
2244 should be treated with caution. PNG files have been known to
2245 contain exploits. Ensure that libpng (or other relevant
2246 libraries) are fully up to date before trying to process or
2247 display the icon.
2248 ยท The PNG image returned can be any size. It might not be
2250 square. Libguestfs tries to return the largest, highest
2251 quality icon available. The application must scale the icon to
2252 the required size.
2253 ยท Extracting icons from Windows guests requires the external
2255 "wrestool" program from the "icoutils" package, and several
2256 programs ("bmptopnm", "pnmtopng", "pamcut") from the "netpbm"
2257 package. These must be installed separately.
2258 ยท Operating system icons are usually trademarks. Seek legal
2260 advice before using trademarks in applications.
2261 $major = $g->inspect_get_major_version ($root);
2263 This returns the major version number of the inspected operating
2264 system.
2265 Windows uses a consistent versioning scheme which is not reflected
2267 in the popular public names used by the operating system. Notably
2268 the operating system known as "Windows 7" is really version 6.1
2269 (ie. major = 6, minor = 1). You can find out the real versions
2270 corresponding to releases of Windows by consulting Wikipedia or
2271 MSDN.
2272 If the version could not be determined, then 0 is returned.
2274 Please read "INSPECTION" in guestfs(3) for more details.
2276 $minor = $g->inspect_get_minor_version ($root);
2278 This returns the minor version number of the inspected operating
2279 system.
2280 If the version could not be determined, then 0 is returned.
2282 Please read "INSPECTION" in guestfs(3) for more details. See also
2284 "$g->inspect_get_major_version".
2285 %mountpoints = $g->inspect_get_mountpoints ($root);
2287 This returns a hash of where we think the filesystems associated
2288 with this operating system should be mounted. Callers should note
2289 that this is at best an educated guess made by reading
2290 configuration files such as "/etc/fstab". In particular note that
2291 this may return filesystems which are non-existent or not mountable
2292 and callers should be prepared to handle or ignore failures if they
2293 try to mount them.
2294 Each element in the returned hashtable has a key which is the path
2296 of the mountpoint (eg. "/boot") and a value which is the filesystem
2297 that would be mounted there (eg. "/dev/sda1").
2298 Non-mounted devices such as swap devices are not returned in this
2300 list.
2301 For operating systems like Windows which still use drive letters,
2303 this call will only return an entry for the first drive "mounted
2304 on" "/". For information about the mapping of drive letters to
2305 partitions, see "$g->inspect_get_drive_mappings".
2306 Please read "INSPECTION" in guestfs(3) for more details. See also
2308 "$g->inspect_get_filesystems".
2309 $packageformat = $g->inspect_get_package_format ($root);
2311 This function and "$g->inspect_get_package_management" return the
2312 package format and package management tool used by the inspected
2313 operating system. For example for Fedora these functions would
2314 return "rpm" (package format) and "yum" (package management).
2315 This returns the string "unknown" if we could not determine the
2317 package format or if the operating system does not have a real
2318 packaging system (eg. Windows).
2319 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
2321 "pkgsrc". Future versions of libguestfs may return other strings.
2322 Please read "INSPECTION" in guestfs(3) for more details.
2324 $packagemanagement = $g->inspect_get_package_management ($root);
2326 "$g->inspect_get_package_format" and this function return the
2327 package format and package management tool used by the inspected
2328 operating system. For example for Fedora these functions would
2329 return "rpm" (package format) and "yum" (package management).
2330 This returns the string "unknown" if we could not determine the
2332 package management tool or if the operating system does not have a
2333 real packaging system (eg. Windows).
2334 Possible strings include: "yum", "up2date", "apt" (for all Debian
2336 derivatives), "portage", "pisi", "pacman", "urpmi", "zypper".
2337 Future versions of libguestfs may return other strings.
2338 Please read "INSPECTION" in guestfs(3) for more details.
2340 $product = $g->inspect_get_product_name ($root);
2342 This returns the product name of the inspected operating system.
2343 The product name is generally some freeform string which can be
2344 displayed to the user, but should not be parsed by programs.
2345 If the product name could not be determined, then the string
2347 "unknown" is returned.
2348 Please read "INSPECTION" in guestfs(3) for more details.
2350 $variant = $g->inspect_get_product_variant ($root);
2352 This returns the product variant of the inspected operating system.
2353 For Windows guests, this returns the contents of the Registry key
2355 "HKLM\Software\Microsoft\Windows NT\CurrentVersion"
2356 "InstallationType" which is usually a string such as "Client" or
2357 "Server" (other values are possible). This can be used to
2358 distinguish consumer and enterprise versions of Windows that have
2359 the same version number (for example, Windows 7 and Windows 2008
2360 Server are both version 6.1, but the former is "Client" and the
2361 latter is "Server").
2362 For enterprise Linux guests, in future we intend this to return the
2364 product variant such as "Desktop", "Server" and so on. But this is
2365 not implemented at present.
2366 If the product variant could not be determined, then the string
2368 "unknown" is returned.
2369 Please read "INSPECTION" in guestfs(3) for more details. See also
2371 "$g->inspect_get_product_name", "$g->inspect_get_major_version".
2372 @roots = $g->inspect_get_roots ();
2374 This function is a convenient way to get the list of root devices,
2375 as returned from a previous call to "$g->inspect_os", but without
2376 redoing the whole inspection process.
2377 This returns an empty list if either no root devices were found or
2379 the caller has not called "$g->inspect_os".
2380 Please read "INSPECTION" in guestfs(3) for more details.
2382 $name = $g->inspect_get_type ($root);
2384 This returns the type of the inspected operating system. Currently
2385 defined types are:
2386 "linux"
2388 Any Linux-based operating system.
2389 "windows"
2391 Any Microsoft Windows operating system.
2392 "freebsd"
2394 FreeBSD.
2395 "netbsd"
2397 NetBSD.
2398 "openbsd"
2400 OpenBSD.
2401 "hurd"
2403 GNU/Hurd.
2404 "dos"
2406 MS-DOS, FreeDOS and others.
2407 "unknown"
2409 The operating system type could not be determined.
2410 Future versions of libguestfs may return other strings here. The
2412 caller should be prepared to handle any string.
2413 Please read "INSPECTION" in guestfs(3) for more details.
2415 $controlset = $g->inspect_get_windows_current_control_set ($root);
2417 This returns the Windows CurrentControlSet of the inspected guest.
2418 The CurrentControlSet is a registry key name such as
2419 "ControlSet001".
2420 This call assumes that the guest is Windows and that the Registry
2422 could be examined by inspection. If this is not the case then an
2423 error is returned.
2424 Please read "INSPECTION" in guestfs(3) for more details.
2426 $systemroot = $g->inspect_get_windows_systemroot ($root);
2428 This returns the Windows systemroot of the inspected guest. The
2429 systemroot is a directory path such as "/WINDOWS".
2430 This call assumes that the guest is Windows and that the systemroot
2432 could be determined by inspection. If this is not the case then an
2433 error is returned.
2434 Please read "INSPECTION" in guestfs(3) for more details.
2436 $live = $g->inspect_is_live ($root);
2438 If "$g->inspect_get_format" returns "installer" (this is an install
2439 disk), then this returns true if a live image was detected on the
2440 disk.
2441 Please read "INSPECTION" in guestfs(3) for more details.
2443 $multipart = $g->inspect_is_multipart ($root);
2445 If "$g->inspect_get_format" returns "installer" (this is an install
2446 disk), then this returns true if the disk is part of a set.
2447 Please read "INSPECTION" in guestfs(3) for more details.
2449 $netinst = $g->inspect_is_netinst ($root);
2451 If "$g->inspect_get_format" returns "installer" (this is an install
2452 disk), then this returns true if the disk is a network installer,
2453 ie. not a self-contained install CD but one which is likely to
2454 require network access to complete the install.
2455 Please read "INSPECTION" in guestfs(3) for more details.
2457 @applications = $g->inspect_list_applications ($root);
2459 Return the list of applications installed in the operating system.
2460 Note: This call works differently from other parts of the
2462 inspection API. You have to call "$g->inspect_os", then
2463 "$g->inspect_get_mountpoints", then mount up the disks, before
2464 calling this. Listing applications is a significantly more
2465 difficult operation which requires access to the full filesystem.
2466 Also note that unlike the other "$g->inspect_get_*" calls which are
2467 just returning data cached in the libguestfs handle, this call
2468 actually reads parts of the mounted filesystems during the call.
2469 This returns an empty list if the inspection code was not able to
2471 determine the list of applications.
2472 The application structure contains the following fields:
2474 "app_name"
2476 The name of the application. For Red Hat-derived and Debian-
2477 derived Linux guests, this is the package name.
2478 "app_display_name"
2480 The display name of the application, sometimes localized to the
2481 install language of the guest operating system.
2482 If unavailable this is returned as an empty string "". Callers
2484 needing to display something can use "app_name" instead.
2485 "app_epoch"
2487 For package managers which use epochs, this contains the epoch
2488 of the package (an integer). If unavailable, this is returned
2489 as 0.
2490 "app_version"
2492 The version string of the application or package. If
2493 unavailable this is returned as an empty string "".
2494 "app_release"
2496 The release string of the application or package, for package
2497 managers that use this. If unavailable this is returned as an
2498 empty string "".
2499 "app_install_path"
2501 The installation path of the application (on operating systems
2502 such as Windows which use installation paths). This path is in
2503 the format used by the guest operating system, it is not a
2504 libguestfs path.
2505 If unavailable this is returned as an empty string "".
2507 "app_trans_path"
2509 The install path translated into a libguestfs path. If
2510 unavailable this is returned as an empty string "".
2511 "app_publisher"
2513 The name of the publisher of the application, for package
2514 managers that use this. If unavailable this is returned as an
2515 empty string "".
2516 "app_url"
2518 The URL (eg. upstream URL) of the application. If unavailable
2519 this is returned as an empty string "".
2520 "app_source_package"
2522 For packaging systems which support this, the name of the
2523 source package. If unavailable this is returned as an empty
2524 string "".
2525 "app_summary"
2527 A short (usually one line) description of the application or
2528 package. If unavailable this is returned as an empty string
2529 "".
2530 "app_description"
2532 A longer description of the application or package. If
2533 unavailable this is returned as an empty string "".
2534 Please read "INSPECTION" in guestfs(3) for more details.
2536 This function is deprecated. In new code, use the
2538 "inspect_list_applications2" call instead.
2539 Deprecated functions will not be removed from the API, but the fact
2541 that they are deprecated indicates that there are problems with
2542 correct use of these functions.
2543 @applications2 = $g->inspect_list_applications2 ($root);
2545 Return the list of applications installed in the operating system.
2546 Note: This call works differently from other parts of the
2548 inspection API. You have to call "$g->inspect_os", then
2549 "$g->inspect_get_mountpoints", then mount up the disks, before
2550 calling this. Listing applications is a significantly more
2551 difficult operation which requires access to the full filesystem.
2552 Also note that unlike the other "$g->inspect_get_*" calls which are
2553 just returning data cached in the libguestfs handle, this call
2554 actually reads parts of the mounted filesystems during the call.
2555 This returns an empty list if the inspection code was not able to
2557 determine the list of applications.
2558 The application structure contains the following fields:
2560 "app2_name"
2562 The name of the application. For Red Hat-derived and Debian-
2563 derived Linux guests, this is the package name.
2564 "app2_display_name"
2566 The display name of the application, sometimes localized to the
2567 install language of the guest operating system.
2568 If unavailable this is returned as an empty string "". Callers
2570 needing to display something can use "app2_name" instead.
2571 "app2_epoch"
2573 For package managers which use epochs, this contains the epoch
2574 of the package (an integer). If unavailable, this is returned
2575 as 0.
2576 "app2_version"
2578 The version string of the application or package. If
2579 unavailable this is returned as an empty string "".
2580 "app2_release"
2582 The release string of the application or package, for package
2583 managers that use this. If unavailable this is returned as an
2584 empty string "".
2585 "app2_arch"
2587 The architecture string of the application or package, for
2588 package managers that use this. If unavailable this is
2589 returned as an empty string "".
2590 "app2_install_path"
2592 The installation path of the application (on operating systems
2593 such as Windows which use installation paths). This path is in
2594 the format used by the guest operating system, it is not a
2595 libguestfs path.
2596 If unavailable this is returned as an empty string "".
2598 "app2_trans_path"
2600 The install path translated into a libguestfs path. If
2601 unavailable this is returned as an empty string "".
2602 "app2_publisher"
2604 The name of the publisher of the application, for package
2605 managers that use this. If unavailable this is returned as an
2606 empty string "".
2607 "app2_url"
2609 The URL (eg. upstream URL) of the application. If unavailable
2610 this is returned as an empty string "".
2611 "app2_source_package"
2613 For packaging systems which support this, the name of the
2614 source package. If unavailable this is returned as an empty
2615 string "".
2616 "app2_summary"
2618 A short (usually one line) description of the application or
2619 package. If unavailable this is returned as an empty string
2620 "".
2621 "app2_description"
2623 A longer description of the application or package. If
2624 unavailable this is returned as an empty string "".
2625 Please read "INSPECTION" in guestfs(3) for more details.
2627 @roots = $g->inspect_os ();
2629 This function uses other libguestfs functions and certain
2630 heuristics to inspect the disk(s) (usually disks belonging to a
2631 virtual machine), looking for operating systems.
2632 The list returned is empty if no operating systems were found.
2634 If one operating system was found, then this returns a list with a
2636 single element, which is the name of the root filesystem of this
2637 operating system. It is also possible for this function to return
2638 a list containing more than one element, indicating a dual-boot or
2639 multi-boot virtual machine, with each element being the root
2640 filesystem of one of the operating systems.
2641 You can pass the root string(s) returned to other
2643 "$g->inspect_get_*" functions in order to query further information
2644 about each operating system, such as the name and version.
2645 This function uses other libguestfs features such as "$g->mount_ro"
2647 and "$g->umount_all" in order to mount and unmount filesystems and
2648 look at the contents. This should be called with no disks
2649 currently mounted. The function may also use Augeas, so any
2650 existing Augeas handle will be closed.
2651 This function cannot decrypt encrypted disks. The caller must do
2653 that first (supplying the necessary keys) if the disk is encrypted.
2654 Please read "INSPECTION" in guestfs(3) for more details.
2656 See also "$g->list_filesystems".
2658 $flag = $g->is_blockdev ($path);
2660 This returns "true" if and only if there is a block device with the
2661 given "path" name.
2662 See also "$g->stat".
2664 $busy = $g->is_busy ();
2666 This always returns false. This function is deprecated with no
2667 replacement. Do not use this function.
2668 For more information on states, see guestfs(3).
2670 $flag = $g->is_chardev ($path);
2672 This returns "true" if and only if there is a character device with
2673 the given "path" name.
2674 See also "$g->stat".
2676 $config = $g->is_config ();
2678 This returns true iff this handle is being configured (in the
2679 "CONFIG" state).
2680 For more information on states, see guestfs(3).
2682 $dirflag = $g->is_dir ($path);
2684 This returns "true" if and only if there is a directory with the
2685 given "path" name. Note that it returns false for other objects
2686 like files.
2687 See also "$g->stat".
2689 $flag = $g->is_fifo ($path);
2691 This returns "true" if and only if there is a FIFO (named pipe)
2692 with the given "path" name.
2693 See also "$g->stat".
2695 $fileflag = $g->is_file ($path);
2697 This returns "true" if and only if there is a regular file with the
2698 given "path" name. Note that it returns false for other objects
2699 like directories.
2700 See also "$g->stat".
2702 $launching = $g->is_launching ();
2704 This returns true iff this handle is launching the subprocess (in
2705 the "LAUNCHING" state).
2706 For more information on states, see guestfs(3).
2708 $lvflag = $g->is_lv ($device);
2710 This command tests whether "device" is a logical volume, and
2711 returns true iff this is the case.
2712 $ready = $g->is_ready ();
2714 This returns true iff this handle is ready to accept commands (in
2715 the "READY" state).
2716 For more information on states, see guestfs(3).
2718 $flag = $g->is_socket ($path);
2720 This returns "true" if and only if there is a Unix domain socket
2721 with the given "path" name.
2722 See also "$g->stat".
2724 $flag = $g->is_symlink ($path);
2726 This returns "true" if and only if there is a symbolic link with
2727 the given "path" name.
2728 See also "$g->stat".
2730 $zeroflag = $g->is_zero ($path);
2732 This returns true iff the file exists and the file is empty or it
2733 contains all zero bytes.
2734 $zeroflag = $g->is_zero_device ($device);
2736 This returns true iff the device exists and contains all zero
2737 bytes.
2738 Note that for large devices this can take a long time to run.
2740 %isodata = $g->isoinfo ($isofile);
2742 This is the same as "$g->isoinfo_device" except that it works for
2743 an ISO file located inside some other mounted filesystem. Note
2744 that in the common case where you have added an ISO file as a
2745 libguestfs device, you would not call this. Instead you would call
2746 "$g->isoinfo_device".
2747 %isodata = $g->isoinfo_device ($device);
2749 "device" is an ISO device. This returns a struct of information
2750 read from the primary volume descriptor (the ISO equivalent of the
2751 superblock) of the device.
2752 Usually it is more efficient to use the isoinfo(1) command with the
2754 -d option on the host to analyze ISO files, instead of going
2755 through libguestfs.
2756 For information on the primary volume descriptor fields, see
2758 <http://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor>
2759 $g->kill_subprocess ();
2761 This kills the qemu subprocess.
2762 Do not call this. See: "$g->shutdown" instead.
2764 This function is deprecated. In new code, use the "shutdown" call
2766 instead.
2767 Deprecated functions will not be removed from the API, but the fact
2769 that they are deprecated indicates that there are problems with
2770 correct use of these functions.
2771 $g->launch ();
2773 Internally libguestfs is implemented by running a virtual machine
2774 using qemu(1).
2775 You should call this after configuring the handle (eg. adding
2777 drives) but before performing any actions.
2778 Do not call "$g->launch" twice on the same handle. Although it
2780 will not give an error (for historical reasons), the precise
2781 behaviour when you do this is not well defined. Handles are very
2782 cheap to create, so create a new one for each launch.
2783 $g->lchown ($owner, $group, $path);
2785 Change the file owner to "owner" and group to "group". This is
2786 like "$g->chown" but if "path" is a symlink then the link itself is
2787 changed, not the target.
2788 Only numeric uid and gid are supported. If you want to use names,
2790 you will need to locate and parse the password file yourself
2791 (Augeas support makes this relatively easy).
2792 $g->ldmtool_create_all ();
2794 This function scans all block devices looking for Windows dynamic
2795 disk volumes and partitions, and creates devices for any that were
2796 found.
2797 Call "$g->list_ldm_volumes" and "$g->list_ldm_partitions" to return
2799 all devices.
2800 Note that you don't normally need to call this explicitly, since it
2802 is done automatically at "$g->launch" time. However you might want
2803 to call this function if you have hotplugged disks or have just
2804 created a Windows dynamic disk.
2805 @disks = $g->ldmtool_diskgroup_disks ($diskgroup);
2807 Return the disks in a Windows dynamic disk group. The "diskgroup"
2808 parameter should be the GUID of a disk group, one element from the
2809 list returned by "$g->ldmtool_scan".
2810 $name = $g->ldmtool_diskgroup_name ($diskgroup);
2812 Return the name of a Windows dynamic disk group. The "diskgroup"
2813 parameter should be the GUID of a disk group, one element from the
2814 list returned by "$g->ldmtool_scan".
2815 @volumes = $g->ldmtool_diskgroup_volumes ($diskgroup);
2817 Return the volumes in a Windows dynamic disk group. The
2818 "diskgroup" parameter should be the GUID of a disk group, one
2819 element from the list returned by "$g->ldmtool_scan".
2820 $g->ldmtool_remove_all ();
2822 This is essentially the opposite of "$g->ldmtool_create_all". It
2823 removes the device mapper mappings for all Windows dynamic disk
2824 volumes
2825 @guids = $g->ldmtool_scan ();
2827 This function scans for Windows dynamic disks. It returns a list
2828 of identifiers (GUIDs) for all disk groups that were found. These
2829 identifiers can be passed to other "$g->ldmtool_*" functions.
2830 This function scans all block devices. To scan a subset of block
2832 devices, call "$g->ldmtool_scan_devices" instead.
2833 @guids = $g->ldmtool_scan_devices (\@devices);
2835 This function scans for Windows dynamic disks. It returns a list
2836 of identifiers (GUIDs) for all disk groups that were found. These
2837 identifiers can be passed to other "$g->ldmtool_*" functions.
2838 The parameter "devices" is a list of block devices which are
2840 scanned. If this list is empty, all block devices are scanned.
2841 $hint = $g->ldmtool_volume_hint ($diskgroup, $volume);
2843 Return the hint field of the volume named "volume" in the disk
2844 group with GUID "diskgroup". This may not be defined, in which
2845 case the empty string is returned. The hint field is often, though
2846 not always, the name of a Windows drive, eg. "E:".
2847 @partitions = $g->ldmtool_volume_partitions ($diskgroup, $volume);
2849 Return the list of partitions in the volume named "volume" in the
2850 disk group with GUID "diskgroup".
2851 $voltype = $g->ldmtool_volume_type ($diskgroup, $volume);
2853 Return the type of the volume named "volume" in the disk group with
2854 GUID "diskgroup".
2855 Possible volume types that can be returned here include: "simple",
2857 "spanned", "striped", "mirrored", "raid5". Other types may also be
2858 returned.
2859 $xattr = $g->lgetxattr ($path, $name);
2861 Get a single extended attribute from file "path" named "name". If
2862 "path" is a symlink, then this call returns an extended attribute
2863 from the symlink.
2864 Normally it is better to get all extended attributes from a file in
2866 one go by calling "$g->getxattrs". However some Linux filesystem
2867 implementations are buggy and do not provide a way to list out
2868 attributes. For these filesystems (notably ntfs-3g) you have to
2869 know the names of the extended attributes you want in advance and
2870 call this function.
2871 Extended attribute values are blobs of binary data. If there is no
2873 extended attribute named "name", this returns an error.
2874 See also: "$g->lgetxattrs", "$g->getxattr", attr(5).
2876 @xattrs = $g->lgetxattrs ($path);
2878 This is the same as "$g->getxattrs", but if "path" is a symbolic
2879 link, then it returns the extended attributes of the link itself.
2880 @devices = $g->list_devices ();
2882 List all the block devices.
2883 The full block device names are returned, eg. "/dev/sda".
2885 See also "$g->list_filesystems".
2887 %labels = $g->list_disk_labels ();
2889 If you add drives using the optional "label" parameter of
2890 "$g->add_drive_opts", you can use this call to map between disk
2891 labels, and raw block device and partition names (like "/dev/sda"
2892 and "/dev/sda1").
2893 This returns a hashtable, where keys are the disk labels (without
2895 the "/dev/disk/guestfs" prefix), and the values are the full raw
2896 block device and partition names (eg. "/dev/sda" and "/dev/sda1").
2897 @devices = $g->list_dm_devices ();
2899 List all device mapper devices.
2900 The returned list contains "/dev/mapper/*" devices, eg. ones
2902 created by a previous call to "$g->luks_open".
2903 Device mapper devices which correspond to logical volumes are not
2905 returned in this list. Call "$g->lvs" if you want to list logical
2906 volumes.
2907 %fses = $g->list_filesystems ();
2909 This inspection command looks for filesystems on partitions, block
2910 devices and logical volumes, returning a list of devices containing
2911 filesystems and their type.
2912 The return value is a hash, where the keys are the devices
2914 containing filesystems, and the values are the filesystem types.
2915 For example:
2916 "/dev/sda1" => "ntfs"
2918 "/dev/sda2" => "ext2"
2919 "/dev/vg_guest/lv_root" => "ext4"
2920 "/dev/vg_guest/lv_swap" => "swap"
2921 The value can have the special value "unknown", meaning the content
2923 of the device is undetermined or empty. "swap" means a Linux swap
2924 partition.
2925 This command runs other libguestfs commands, which might include
2927 "$g->mount" and "$g->umount", and therefore you should use this
2928 soon after launch and only when nothing is mounted.
2929 Not all of the filesystems returned will be mountable. In
2931 particular, swap partitions are returned in the list. Also this
2932 command does not check that each filesystem found is valid and
2933 mountable, and some filesystems might be mountable but require
2934 special options. Filesystems may not all belong to a single
2935 logical operating system (use "$g->inspect_os" to look for OSes).
2936 @devices = $g->list_ldm_partitions ();
2938 This function returns all Windows dynamic disk partitions that were
2939 found at launch time. It returns a list of device names.
2940 @devices = $g->list_ldm_volumes ();
2942 This function returns all Windows dynamic disk volumes that were
2943 found at launch time. It returns a list of device names.
2944 @devices = $g->list_md_devices ();
2946 List all Linux md devices.
2947 @partitions = $g->list_partitions ();
2949 List all the partitions detected on all block devices.
2950 The full partition device names are returned, eg. "/dev/sda1"
2952 This does not return logical volumes. For that you will need to
2954 call "$g->lvs".
2955 See also "$g->list_filesystems".
2957 $listing = $g->ll ($directory);
2959 List the files in "directory" (relative to the root directory,
2960 there is no cwd) in the format of 'ls -la'.
2961 This command is mostly useful for interactive sessions. It is not
2963 intended that you try to parse the output string.
2964 $listing = $g->llz ($directory);
2966 List the files in "directory" in the format of 'ls -laZ'.
2967 This command is mostly useful for interactive sessions. It is not
2969 intended that you try to parse the output string.
2970 $g->ln ($target, $linkname);
2972 This command creates a hard link using the "ln" command.
2973 $g->ln_f ($target, $linkname);
2975 This command creates a hard link using the "ln -f" command. The -f
2976 option removes the link ("linkname") if it exists already.
2977 $g->ln_s ($target, $linkname);
2979 This command creates a symbolic link using the "ln -s" command.
2980 $g->ln_sf ($target, $linkname);
2982 This command creates a symbolic link using the "ln -sf" command,
2983 The -f option removes the link ("linkname") if it exists already.
2984 $g->lremovexattr ($xattr, $path);
2986 This is the same as "$g->removexattr", but if "path" is a symbolic
2987 link, then it removes an extended attribute of the link itself.
2988 @listing = $g->ls ($directory);
2990 List the files in "directory" (relative to the root directory,
2991 there is no cwd). The '.' and '..' entries are not returned, but
2992 hidden files are shown.
2993 $g->ls0 ($dir, $filenames);
2995 This specialized command is used to get a listing of the filenames
2996 in the directory "dir". The list of filenames is written to the
2997 local file "filenames" (on the host).
2998 In the output file, the filenames are separated by "\0" characters.
3000 "." and ".." are not returned. The filenames are not sorted.
3002 $g->lsetxattr ($xattr, $val, $vallen, $path);
3004 This is the same as "$g->setxattr", but if "path" is a symbolic
3005 link, then it sets an extended attribute of the link itself.
3006 %statbuf = $g->lstat ($path);
3008 Returns file information for the given "path".
3009 This is the same as "$g->stat" except that if "path" is a symbolic
3011 link, then the link is stat-ed, not the file it refers to.
3012 This is the same as the lstat(2) system call.
3014 @statbufs = $g->lstatlist ($path, \@names);
3016 This call allows you to perform the "$g->lstat" operation on
3017 multiple files, where all files are in the directory "path".
3018 "names" is the list of files from this directory.
3019 On return you get a list of stat structs, with a one-to-one
3021 correspondence to the "names" list. If any name did not exist or
3022 could not be lstat'd, then the "ino" field of that structure is set
3023 to "-1".
3024 This call is intended for programs that want to efficiently list a
3026 directory contents without making many round-trips. See also
3027 "$g->lxattrlist" for a similarly efficient call for getting
3028 extended attributes.
3029 $g->luks_add_key ($device, $key, $newkey, $keyslot);
3031 This command adds a new key on LUKS device "device". "key" is any
3032 existing key, and is used to access the device. "newkey" is the
3033 new key to add. "keyslot" is the key slot that will be replaced.
3034 Note that if "keyslot" already contains a key, then this command
3036 will fail. You have to use "$g->luks_kill_slot" first to remove
3037 that key.
3038 $g->luks_close ($device);
3040 This closes a LUKS device that was created earlier by
3041 "$g->luks_open" or "$g->luks_open_ro". The "device" parameter must
3042 be the name of the LUKS mapping device (ie. "/dev/mapper/mapname")
3043 and not the name of the underlying block device.
3044 $g->luks_format ($device, $key, $keyslot);
3046 This command erases existing data on "device" and formats the
3047 device as a LUKS encrypted device. "key" is the initial key, which
3048 is added to key slot "slot". (LUKS supports 8 key slots, numbered
3049 0-7).
3050 $g->luks_format_cipher ($device, $key, $keyslot, $cipher);
3052 This command is the same as "$g->luks_format" but it also allows
3053 you to set the "cipher" used.
3054 $g->luks_kill_slot ($device, $key, $keyslot);
3056 This command deletes the key in key slot "keyslot" from the
3057 encrypted LUKS device "device". "key" must be one of the other
3058 keys.
3059 $g->luks_open ($device, $key, $mapname);
3061 This command opens a block device which has been encrypted
3062 according to the Linux Unified Key Setup (LUKS) standard.
3063 "device" is the encrypted block device or partition.
3065 The caller must supply one of the keys associated with the LUKS
3067 block device, in the "key" parameter.
3068 This creates a new block device called "/dev/mapper/mapname".
3070 Reads and writes to this block device are decrypted from and
3071 encrypted to the underlying "device" respectively.
3072 If this block device contains LVM volume groups, then calling
3074 "$g->vgscan" followed by "$g->vg_activate_all" will make them
3075 visible.
3076 Use "$g->list_dm_devices" to list all device mapper devices.
3078 $g->luks_open_ro ($device, $key, $mapname);
3080 This is the same as "$g->luks_open" except that a read-only mapping
3081 is created.
3082 $g->lvcreate ($logvol, $volgroup, $mbytes);
3084 This creates an LVM logical volume called "logvol" on the volume
3085 group "volgroup", with "size" megabytes.
3086 $g->lvcreate_free ($logvol, $volgroup, $percent);
3088 Create an LVM logical volume called "/dev/volgroup/logvol", using
3089 approximately "percent" % of the free space remaining in the volume
3090 group. Most usefully, when "percent" is 100 this will create the
3091 largest possible LV.
3092 $lv = $g->lvm_canonical_lv_name ($lvname);
3094 This converts alternative naming schemes for LVs that you might
3095 find to the canonical name. For example, "/dev/mapper/VG-LV" is
3096 converted to "/dev/VG/LV".
3097 This command returns an error if the "lvname" parameter does not
3099 refer to a logical volume.
3100 See also "$g->is_lv", "$g->canonical_device_name".
3102 $g->lvm_clear_filter ();
3104 This undoes the effect of "$g->lvm_set_filter". LVM will be able
3105 to see every block device.
3106 This command also clears the LVM cache and performs a volume group
3108 scan.
3109 $g->lvm_remove_all ();
3111 This command removes all LVM logical volumes, volume groups and
3112 physical volumes.
3113 $g->lvm_set_filter (\@devices);
3115 This sets the LVM device filter so that LVM will only be able to
3116 "see" the block devices in the list "devices", and will ignore all
3117 other attached block devices.
3118 Where disk image(s) contain duplicate PVs or VGs, this command is
3120 useful to get LVM to ignore the duplicates, otherwise LVM can get
3121 confused. Note also there are two types of duplication possible:
3122 either cloned PVs/VGs which have identical UUIDs; or VGs that are
3123 not cloned but just happen to have the same name. In normal
3124 operation you cannot create this situation, but you can do it
3125 outside LVM, eg. by cloning disk images or by bit twiddling inside
3126 the LVM metadata.
3127 This command also clears the LVM cache and performs a volume group
3129 scan.
3130 You can filter whole block devices or individual partitions.
3132 You cannot use this if any VG is currently in use (eg. contains a
3134 mounted filesystem), even if you are not filtering out that VG.
3135 $g->lvremove ($device);
3137 Remove an LVM logical volume "device", where "device" is the path
3138 to the LV, such as "/dev/VG/LV".
3139 You can also remove all LVs in a volume group by specifying the VG
3141 name, "/dev/VG".
3142 $g->lvrename ($logvol, $newlogvol);
3144 Rename a logical volume "logvol" with the new name "newlogvol".
3145 $g->lvresize ($device, $mbytes);
3147 This resizes (expands or shrinks) an existing LVM logical volume to
3148 "mbytes". When reducing, data in the reduced part is lost.
3149 $g->lvresize_free ($lv, $percent);
3151 This expands an existing logical volume "lv" so that it fills "pc"%
3152 of the remaining free space in the volume group. Commonly you
3153 would call this with pc = 100 which expands the logical volume as
3154 much as possible, using all remaining free space in the volume
3155 group.
3156 @logvols = $g->lvs ();
3158 List all the logical volumes detected. This is the equivalent of
3159 the lvs(8) command.
3160 This returns a list of the logical volume device names (eg.
3162 "/dev/VolGroup00/LogVol00").
3163 See also "$g->lvs_full", "$g->list_filesystems".
3165 @logvols = $g->lvs_full ();
3167 List all the logical volumes detected. This is the equivalent of
3168 the lvs(8) command. The "full" version includes all fields.
3169 $uuid = $g->lvuuid ($device);
3171 This command returns the UUID of the LVM LV "device".
3172 @xattrs = $g->lxattrlist ($path, \@names);
3174 This call allows you to get the extended attributes of multiple
3175 files, where all files are in the directory "path". "names" is the
3176 list of files from this directory.
3177 On return you get a flat list of xattr structs which must be
3179 interpreted sequentially. The first xattr struct always has a
3180 zero-length "attrname". "attrval" in this struct is zero-length to
3181 indicate there was an error doing "lgetxattr" for this file, or is
3182 a C string which is a decimal number (the number of following
3183 attributes for this file, which could be "0"). Then after the
3184 first xattr struct are the zero or more attributes for the first
3185 named file. This repeats for the second and subsequent files.
3186 This call is intended for programs that want to efficiently list a
3188 directory contents without making many round-trips. See also
3189 "$g->lstatlist" for a similarly efficient call for getting standard
3190 stats.
3191 $disks = $g->max_disks ();
3193 Return the maximum number of disks that may be added to a handle
3194 (eg. by "$g->add_drive_opts" and similar calls).
3195 This function was added in libguestfs 1.19.7. In previous versions
3197 of libguestfs the limit was 25.
3198 See "MAXIMUM NUMBER OF DISKS" in guestfs(3) for additional
3200 information on this topic.
3201 $g->md_create ($name, \@devices [, missingbitmap => $missingbitmap] [,
3203 nrdevices => $nrdevices] [, spare => $spare] [, chunk => $chunk] [,
3204 level => $level]);
3205 Create a Linux md (RAID) device named "name" on the devices in the
3206 list "devices".
3207 The optional parameters are:
3209 "missingbitmap"
3211 A bitmap of missing devices. If a bit is set it means that a
3212 missing device is added to the array. The least significant
3213 bit corresponds to the first device in the array.
3214 As examples:
3216 If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
3218 resulting array would be "[<missing>, "/dev/sda"]".
3219 If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
3221 resulting array would be "["/dev/sda", <missing>]".
3222 This defaults to 0 (no missing devices).
3224 The length of "devices" + the number of bits set in
3226 "missingbitmap" must equal "nrdevices" + "spare".
3227 "nrdevices"
3229 The number of active RAID devices.
3230 If not set, this defaults to the length of "devices" plus the
3232 number of bits set in "missingbitmap".
3233 "spare"
3235 The number of spare devices.
3236 If not set, this defaults to 0.
3238 "chunk"
3240 The chunk size in bytes.
3241 "level"
3243 The RAID level, which can be one of: linear, raid0, 0, stripe,
3244 raid1, 1, mirror, raid4, 4, raid5, 5, raid6, 6, raid10, 10.
3245 Some of these are synonymous, and more levels may be added in
3246 future.
3247 If not set, this defaults to "raid1".
3249 %info = $g->md_detail ($md);
3251 This command exposes the output of 'mdadm -DY <md>'. The following
3252 fields are usually present in the returned hash. Other fields may
3253 also be present.
3254 "level"
3256 The raid level of the MD device.
3257 "devices"
3259 The number of underlying devices in the MD device.
3260 "metadata"
3262 The metadata version used.
3263 "uuid"
3265 The UUID of the MD device.
3266 "name"
3268 The name of the MD device.
3269 @devices = $g->md_stat ($md);
3271 This call returns a list of the underlying devices which make up
3272 the single software RAID array device "md".
3273 To get a list of software RAID devices, call "$g->list_md_devices".
3275 Each structure returned corresponds to one device along with
3277 additional status information:
3278 "mdstat_device"
3280 The name of the underlying device.
3281 "mdstat_index"
3283 The index of this device within the array.
3284 "mdstat_flags"
3286 Flags associated with this device. This is a string containing
3287 (in no specific order) zero or more of the following flags:
3288 "W" write-mostly
3290 "F" device is faulty
3292 "S" device is a RAID spare
3294 "R" replacement
3296 $g->md_stop ($md);
3298 This command deactivates the MD array named "md". The device is
3299 stopped, but it is not destroyed or zeroed.
3300 $g->mkdir ($path);
3302 Create a directory named "path".
3303 $g->mkdir_mode ($path, $mode);
3305 This command creates a directory, setting the initial permissions
3306 of the directory to "mode".
3307 For common Linux filesystems, the actual mode which is set will be
3309 "mode & ~umask & 01777". Non-native-Linux filesystems may
3310 interpret the mode in other ways.
3311 See also "$g->mkdir", "$g->umask"
3313 $g->mkdir_p ($path);
3315 Create a directory named "path", creating any parent directories as
3316 necessary. This is like the "mkdir -p" shell command.
3317 $dir = $g->mkdtemp ($tmpl);
3319 This command creates a temporary directory. The "tmpl" parameter
3320 should be a full pathname for the temporary directory name with the
3321 final six characters being "XXXXXX".
3322 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the
3324 second one being suitable for Windows filesystems.
3325 The name of the temporary directory that was created is returned.
3327 The temporary directory is created with mode 0700 and is owned by
3329 root.
3330 The caller is responsible for deleting the temporary directory and
3332 its contents after use.
3333 See also: mkdtemp(3)
3335 $g->mke2fs ($device [, blockscount => $blockscount] [, blocksize =>
3337 $blocksize] [, fragsize => $fragsize] [, blockspergroup =>
3338 $blockspergroup] [, numberofgroups => $numberofgroups] [, bytesperinode
3339 => $bytesperinode] [, inodesize => $inodesize] [, journalsize =>
3340 $journalsize] [, numberofinodes => $numberofinodes] [, stridesize =>
3341 $stridesize] [, stripewidth => $stripewidth] [, maxonlineresize =>
3342 $maxonlineresize] [, reservedblockspercentage =>
3343 $reservedblockspercentage] [, mmpupdateinterval => $mmpupdateinterval]
3344 [, journaldevice => $journaldevice] [, label => $label] [,
3345 lastmounteddir => $lastmounteddir] [, creatoros => $creatoros] [,
3346 fstype => $fstype] [, usagetype => $usagetype] [, uuid => $uuid] [,
3347 forcecreate => $forcecreate] [, writesbandgrouponly =>
3348 $writesbandgrouponly] [, lazyitableinit => $lazyitableinit] [,
3349 lazyjournalinit => $lazyjournalinit] [, testfs => $testfs] [, discard
3350 => $discard] [, quotatype => $quotatype] [, extent => $extent] [,
3351 filetype => $filetype] [, flexbg => $flexbg] [, hasjournal =>
3352 $hasjournal] [, journaldev => $journaldev] [, largefile => $largefile]
3353 [, quota => $quota] [, resizeinode => $resizeinode] [, sparsesuper =>
3354 $sparsesuper] [, uninitbg => $uninitbg]);
3355 "mke2fs" is used to create an ext2, ext3, or ext4 filesystem on
3356 "device".
3357 The optional "blockscount" is the size of the filesystem in blocks.
3359 If omitted it defaults to the size of "device". Note if the
3360 filesystem is too small to contain a journal, "mke2fs" will
3361 silently create an ext2 filesystem instead.
3362 $g->mke2fs_J ($fstype, $blocksize, $device, $journal);
3364 This creates an ext2/3/4 filesystem on "device" with an external
3365 journal on "journal". It is equivalent to the command:
3366 mke2fs -t fstype -b blocksize -J device=<journal> <device>
3368 See also "$g->mke2journal".
3370 This function is deprecated. In new code, use the "mke2fs" call
3372 instead.
3373 Deprecated functions will not be removed from the API, but the fact
3375 that they are deprecated indicates that there are problems with
3376 correct use of these functions.
3377 $g->mke2fs_JL ($fstype, $blocksize, $device, $label);
3379 This creates an ext2/3/4 filesystem on "device" with an external
3380 journal on the journal labeled "label".
3381 See also "$g->mke2journal_L".
3383 This function is deprecated. In new code, use the "mke2fs" call
3385 instead.
3386 Deprecated functions will not be removed from the API, but the fact
3388 that they are deprecated indicates that there are problems with
3389 correct use of these functions.
3390 $g->mke2fs_JU ($fstype, $blocksize, $device, $uuid);
3392 This creates an ext2/3/4 filesystem on "device" with an external
3393 journal on the journal with UUID "uuid".
3394 See also "$g->mke2journal_U".
3396 This function is deprecated. In new code, use the "mke2fs" call
3398 instead.
3399 Deprecated functions will not be removed from the API, but the fact
3401 that they are deprecated indicates that there are problems with
3402 correct use of these functions.
3403 $g->mke2journal ($blocksize, $device);
3405 This creates an ext2 external journal on "device". It is
3406 equivalent to the command:
3407 mke2fs -O journal_dev -b blocksize device
3409 This function is deprecated. In new code, use the "mke2fs" call
3411 instead.
3412 Deprecated functions will not be removed from the API, but the fact
3414 that they are deprecated indicates that there are problems with
3415 correct use of these functions.
3416 $g->mke2journal_L ($blocksize, $label, $device);
3418 This creates an ext2 external journal on "device" with label
3419 "label".
3420 This function is deprecated. In new code, use the "mke2fs" call
3422 instead.
3423 Deprecated functions will not be removed from the API, but the fact
3425 that they are deprecated indicates that there are problems with
3426 correct use of these functions.
3427 $g->mke2journal_U ($blocksize, $uuid, $device);
3429 This creates an ext2 external journal on "device" with UUID "uuid".
3430 This function is deprecated. In new code, use the "mke2fs" call
3432 instead.
3433 Deprecated functions will not be removed from the API, but the fact
3435 that they are deprecated indicates that there are problems with
3436 correct use of these functions.
3437 $g->mkfifo ($mode, $path);
3439 This call creates a FIFO (named pipe) called "path" with mode
3440 "mode". It is just a convenient wrapper around "$g->mknod".
3441 The mode actually set is affected by the umask.
3443 $g->mkfs ($fstype, $device [, blocksize => $blocksize] [, features =>
3445 $features] [, inode => $inode] [, sectorsize => $sectorsize]);
3446 This function creates a filesystem on "device". The filesystem
3447 type is "fstype", for example "ext3".
3448 The optional arguments are:
3450 "blocksize"
3452 The filesystem block size. Supported block sizes depend on the
3453 filesystem type, but typically they are 1024, 2048 or 4096 for
3454 Linux ext2/3 filesystems.
3455 For VFAT and NTFS the "blocksize" parameter is treated as the
3457 requested cluster size.
3458 For UFS block sizes, please see mkfs.ufs(8).
3460 "features"
3462 This passes the -O parameter to the external mkfs program.
3463 For certain filesystem types, this allows extra filesystem
3465 features to be selected. See mke2fs(8) and mkfs.ufs(8) for
3466 more details.
3467 You cannot use this optional parameter with the "gfs" or "gfs2"
3469 filesystem type.
3470 "inode"
3472 This passes the -I parameter to the external mke2fs(8) program
3473 which sets the inode size (only for ext2/3/4 filesystems at
3474 present).
3475 "sectorsize"
3477 This passes the -S parameter to external mkfs.ufs(8) program,
3478 which sets sector size for ufs filesystem.
3479 $g->mkfs_opts ($fstype, $device [, blocksize => $blocksize] [, features
3481 => $features] [, inode => $inode] [, sectorsize => $sectorsize]);
3482 This is an alias of "mkfs".
3483 $g->mkfs_b ($fstype, $blocksize, $device);
3485 This call is similar to "$g->mkfs", but it allows you to control
3486 the block size of the resulting filesystem. Supported block sizes
3487 depend on the filesystem type, but typically they are 1024, 2048 or
3488 4096 only.
3489 For VFAT and NTFS the "blocksize" parameter is treated as the
3491 requested cluster size.
3492 This function is deprecated. In new code, use the "mkfs" call
3494 instead.
3495 Deprecated functions will not be removed from the API, but the fact
3497 that they are deprecated indicates that there are problems with
3498 correct use of these functions.
3499 $g->mkfs_btrfs (\@devices [, allocstart => $allocstart] [, bytecount =>
3501 $bytecount] [, datatype => $datatype] [, leafsize => $leafsize] [,
3502 label => $label] [, metadata => $metadata] [, nodesize => $nodesize] [,
3503 sectorsize => $sectorsize]);
3504 Create a btrfs filesystem, allowing all configurables to be set.
3505 For more information on the optional arguments, see mkfs.btrfs(8).
3506 Since btrfs filesystems can span multiple devices, this takes a
3508 non-empty list of devices.
3509 To create general filesystems, use "$g->mkfs".
3511 $g->mklost_and_found ($mountpoint);
3513 Make the "lost+found" directory, normally in the root directory of
3514 an ext2/3/4 filesystem. "mountpoint" is the directory under which
3515 we try to create the "lost+found" directory.
3516 $g->mkmountpoint ($exemptpath);
3518 "$g->mkmountpoint" and "$g->rmmountpoint" are specialized calls
3519 that can be used to create extra mountpoints before mounting the
3520 first filesystem.
3521 These calls are only necessary in some very limited circumstances,
3523 mainly the case where you want to mount a mix of unrelated and/or
3524 read-only filesystems together.
3525 For example, live CDs often contain a "Russian doll" nest of
3527 filesystems, an ISO outer layer, with a squashfs image inside, with
3528 an ext2/3 image inside that. You can unpack this as follows in
3529 guestfish:
3530 add-ro Fedora-11-i686-Live.iso
3532 run
3533 mkmountpoint /cd
3534 mkmountpoint /sqsh
3535 mkmountpoint /ext3fs
3536 mount /dev/sda /cd
3537 mount-loop /cd/LiveOS/squashfs.img /sqsh
3538 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
3539 The inner filesystem is now unpacked under the /ext3fs mountpoint.
3541 "$g->mkmountpoint" is not compatible with "$g->umount_all". You
3543 may get unexpected errors if you try to mix these calls. It is
3544 safest to manually unmount filesystems and remove mountpoints after
3545 use.
3546 "$g->umount_all" unmounts filesystems by sorting the paths longest
3548 first, so for this to work for manual mountpoints, you must ensure
3549 that the innermost mountpoints have the longest pathnames, as in
3550 the example code above.
3551 For more details see
3553 <https://bugzilla.redhat.com/show_bug.cgi?id=599503>
3554 Autosync [see "$g->set_autosync", this is set by default on
3556 handles] can cause "$g->umount_all" to be called when the handle is
3557 closed which can also trigger these issues.
3558 $g->mknod ($mode, $devmajor, $devminor, $path);
3560 This call creates block or character special devices, or named
3561 pipes (FIFOs).
3562 The "mode" parameter should be the mode, using the standard
3564 constants. "devmajor" and "devminor" are the device major and
3565 minor numbers, only used when creating block and character special
3566 devices.
3567 Note that, just like mknod(2), the mode must be bitwise OR'd with
3569 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just
3570 creates a regular file). These constants are available in the
3571 standard Linux header files, or you can use "$g->mknod_b",
3572 "$g->mknod_c" or "$g->mkfifo" which are wrappers around this
3573 command which bitwise OR in the appropriate constant for you.
3574 The mode actually set is affected by the umask.
3576 $g->mknod_b ($mode, $devmajor, $devminor, $path);
3578 This call creates a block device node called "path" with mode
3579 "mode" and device major/minor "devmajor" and "devminor". It is
3580 just a convenient wrapper around "$g->mknod".
3581 The mode actually set is affected by the umask.
3583 $g->mknod_c ($mode, $devmajor, $devminor, $path);
3585 This call creates a char device node called "path" with mode "mode"
3586 and device major/minor "devmajor" and "devminor". It is just a
3587 convenient wrapper around "$g->mknod".
3588 The mode actually set is affected by the umask.
3590 $g->mkswap ($device [, label => $label] [, uuid => $uuid]);
3592 Create a Linux swap partition on "device".
3593 The option arguments "label" and "uuid" allow you to set the label
3595 and/or UUID of the new swap partition.
3596 $g->mkswap_opts ($device [, label => $label] [, uuid => $uuid]);
3598 This is an alias of "mkswap".
3599 $g->mkswap_L ($label, $device);
3601 Create a swap partition on "device" with label "label".
3602 Note that you cannot attach a swap label to a block device (eg.
3604 "/dev/sda"), just to a partition. This appears to be a limitation
3605 of the kernel or swap tools.
3606 This function is deprecated. In new code, use the "mkswap" call
3608 instead.
3609 Deprecated functions will not be removed from the API, but the fact
3611 that they are deprecated indicates that there are problems with
3612 correct use of these functions.
3613 $g->mkswap_U ($uuid, $device);
3615 Create a swap partition on "device" with UUID "uuid".
3616 This function is deprecated. In new code, use the "mkswap" call
3618 instead.
3619 Deprecated functions will not be removed from the API, but the fact
3621 that they are deprecated indicates that there are problems with
3622 correct use of these functions.
3623 $g->mkswap_file ($path);
3625 Create a swap file.
3626 This command just writes a swap file signature to an existing file.
3628 To create the file itself, use something like "$g->fallocate".
3629 $path = $g->mktemp ($tmpl [, suffix => $suffix]);
3631 This command creates a temporary file. The "tmpl" parameter should
3632 be a full pathname for the temporary directory name with the final
3633 six characters being "XXXXXX".
3634 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the
3636 second one being suitable for Windows filesystems.
3637 The name of the temporary file that was created is returned.
3639 The temporary file is created with mode 0600 and is owned by root.
3641 The caller is responsible for deleting the temporary file after
3643 use.
3644 If the optional "suffix" parameter is given, then the suffix (eg.
3646 ".txt") is appended to the temporary name.
3647 See also: "$g->mkdtemp".
3649 $g->modprobe ($modulename);
3651 This loads a kernel module in the appliance.
3652 The kernel module must have been whitelisted when libguestfs was
3654 built (see "appliance/kmod.whitelist.in" in the source).
3655 $g->mount ($device, $mountpoint);
3657 Mount a guest disk at a position in the filesystem. Block devices
3658 are named "/dev/sda", "/dev/sdb" and so on, as they were added to
3659 the guest. If those block devices contain partitions, they will
3660 have the usual names (eg. "/dev/sda1"). Also LVM
3661 "/dev/VG/LV"-style names can be used.
3662 The rules are the same as for mount(2): A filesystem must first be
3664 mounted on "/" before others can be mounted. Other filesystems can
3665 only be mounted on directories which already exist.
3666 The mounted filesystem is writable, if we have sufficient
3668 permissions on the underlying device.
3669 Before libguestfs 1.13.16, this call implicitly added the options
3671 "sync" and "noatime". The "sync" option greatly slowed writes and
3672 caused many problems for users. If your program might need to work
3673 with older versions of libguestfs, use "$g->mount_options" instead
3674 (using an empty string for the first parameter if you don't want
3675 any options).
3676 $g->mount_local ($localmountpoint [, readonly => $readonly] [, options
3678 => $options] [, cachetimeout => $cachetimeout] [, debugcalls =>
3679 $debugcalls]);
3680 This call exports the libguestfs-accessible filesystem to a local
3681 mountpoint (directory) called "localmountpoint". Ordinary reads
3682 and writes to files and directories under "localmountpoint" are
3683 redirected through libguestfs.
3684 If the optional "readonly" flag is set to true, then writes to the
3686 filesystem return error "EROFS".
3687 "options" is a comma-separated list of mount options. See
3689 guestmount(1) for some useful options.
3690 "cachetimeout" sets the timeout (in seconds) for cached directory
3692 entries. The default is 60 seconds. See guestmount(1) for further
3693 information.
3694 If "debugcalls" is set to true, then additional debugging
3696 information is generated for every FUSE call.
3697 When "$g->mount_local" returns, the filesystem is ready, but is not
3699 processing requests (access to it will block). You have to call
3700 "$g->mount_local_run" to run the main loop.
3701 See "MOUNT LOCAL" in guestfs(3) for full documentation.
3703 $g->mount_local_run ();
3705 Run the main loop which translates kernel calls to libguestfs
3706 calls.
3707 This should only be called after "$g->mount_local" returns
3709 successfully. The call will not return until the filesystem is
3710 unmounted.
3711 Note you must not make concurrent libguestfs calls on the same
3713 handle from another thread.
3714 You may call this from a different thread than the one which called
3716 "$g->mount_local", subject to the usual rules for threads and
3717 libguestfs (see "MULTIPLE HANDLES AND MULTIPLE THREADS" in
3718 guestfs(3)).
3719 See "MOUNT LOCAL" in guestfs(3) for full documentation.
3721 $g->mount_loop ($file, $mountpoint);
3723 This command lets you mount "file" (a filesystem image in a file)
3724 on a mount point. It is entirely equivalent to the command "mount
3725 -o loop file mountpoint".
3726 $g->mount_options ($options, $device, $mountpoint);
3728 This is the same as the "$g->mount" command, but it allows you to
3729 set the mount options as for the mount(8) -o flag.
3730 If the "options" parameter is an empty string, then no options are
3732 passed (all options default to whatever the filesystem uses).
3733 $g->mount_ro ($device, $mountpoint);
3735 This is the same as the "$g->mount" command, but it mounts the
3736 filesystem with the read-only (-o ro) flag.
3737 $g->mount_vfs ($options, $vfstype, $device, $mountpoint);
3739 This is the same as the "$g->mount" command, but it allows you to
3740 set both the mount options and the vfstype as for the mount(8) -o
3741 and -t flags.
3742 %mps = $g->mountpoints ();
3744 This call is similar to "$g->mounts". That call returns a list of
3745 devices. This one returns a hash table (map) of device name to
3746 directory where the device is mounted.
3747 @devices = $g->mounts ();
3749 This returns the list of currently mounted filesystems. It returns
3750 the list of devices (eg. "/dev/sda1", "/dev/VG/LV").
3751 Some internal mounts are not shown.
3753 See also: "$g->mountpoints"
3755 $g->mv ($src, $dest);
3757 This moves a file from "src" to "dest" where "dest" is either a
3758 destination filename or destination directory.
3759 See also: "$g->rename".
3761 $nrdisks = $g->nr_devices ();
3763 This returns the number of whole block devices that were added.
3764 This is the same as the number of devices that would be returned if
3765 you called "$g->list_devices".
3766 To find out the maximum number of devices that could be added, call
3768 "$g->max_disks".
3769 $status = $g->ntfs_3g_probe ($rw, $device);
3771 This command runs the ntfs-3g.probe(8) command which probes an NTFS
3772 "device" for mountability. (Not all NTFS volumes can be mounted
3773 read-write, and some cannot be mounted at all).
3774 "rw" is a boolean flag. Set it to true if you want to test if the
3776 volume can be mounted read-write. Set it to false if you want to
3777 test if the volume can be mounted read-only.
3778 The return value is an integer which 0 if the operation would
3780 succeed, or some non-zero value documented in the ntfs-3g.probe(8)
3781 manual page.
3782 $g->ntfsclone_in ($backupfile, $device);
3784 Restore the "backupfile" (from a previous call to
3785 "$g->ntfsclone_out") to "device", overwriting any existing contents
3786 of this device.
3787 $g->ntfsclone_out ($device, $backupfile [, metadataonly =>
3789 $metadataonly] [, rescue => $rescue] [, ignorefscheck =>
3790 $ignorefscheck] [, preservetimestamps => $preservetimestamps] [, force
3791 => $force]);
3792 Stream the NTFS filesystem "device" to the local file "backupfile".
3793 The format used for the backup file is a special format used by the
3794 ntfsclone(8) tool.
3795 If the optional "metadataonly" flag is true, then only the metadata
3797 is saved, losing all the user data (this is useful for diagnosing
3798 some filesystem problems).
3799 The optional "rescue", "ignorefscheck", "preservetimestamps" and
3801 "force" flags have precise meanings detailed in the ntfsclone(8)
3802 man page.
3803 Use "$g->ntfsclone_in" to restore the file back to a libguestfs
3805 device.
3806 $g->ntfsfix ($device [, clearbadsectors => $clearbadsectors]);
3808 This command repairs some fundamental NTFS inconsistencies, resets
3809 the NTFS journal file, and schedules an NTFS consistency check for
3810 the first boot into Windows.
3811 This is not an equivalent of Windows "chkdsk". It does not scan
3813 the filesystem for inconsistencies.
3814 The optional "clearbadsectors" flag clears the list of bad sectors.
3816 This is useful after cloning a disk with bad sectors to a new disk.
3817 $g->ntfsresize ($device [, size => $size] [, force => $force]);
3819 This command resizes an NTFS filesystem, expanding or shrinking it
3820 to the size of the underlying device.
3821 The optional parameters are:
3823 "size"
3825 The new size (in bytes) of the filesystem. If omitted, the
3826 filesystem is resized to fit the container (eg. partition).
3827 "force"
3829 If this option is true, then force the resize of the filesystem
3830 even if the filesystem is marked as requiring a consistency
3831 check.
3832 After the resize operation, the filesystem is always marked as
3834 requiring a consistency check (for safety). You have to boot
3835 into Windows to perform this check and clear this condition.
3836 If you don't set the "force" option then it is not possible to
3837 call "$g->ntfsresize" multiple times on a single filesystem
3838 without booting into Windows between each resize.
3839 See also ntfsresize(8).
3841 $g->ntfsresize_opts ($device [, size => $size] [, force => $force]);
3843 This is an alias of "ntfsresize".
3844 $g->ntfsresize_size ($device, $size);
3846 This command is the same as "$g->ntfsresize" except that it allows
3847 you to specify the new size (in bytes) explicitly.
3848 This function is deprecated. In new code, use the "ntfsresize"
3850 call instead.
3851 Deprecated functions will not be removed from the API, but the fact
3853 that they are deprecated indicates that there are problems with
3854 correct use of these functions.
3855 $g->parse_environment ();
3857 Parse the program's environment and set flags in the handle
3858 accordingly. For example if "LIBGUESTFS_DEBUG=1" then the
3859 'verbose' flag is set in the handle.
3860 Most programs do not need to call this. It is done implicitly when
3862 you call "$g->create".
3863 See "ENVIRONMENT VARIABLES" in guestfs(3) for a list of environment
3865 variables that can affect libguestfs handles. See also
3866 "guestfs_create_flags" in guestfs(3), and
3867 "$g->parse_environment_list".
3868 $g->parse_environment_list (\@environment);
3870 Parse the list of strings in the argument "environment" and set
3871 flags in the handle accordingly. For example if
3872 "LIBGUESTFS_DEBUG=1" is a string in the list, then the 'verbose'
3873 flag is set in the handle.
3874 This is the same as "$g->parse_environment" except that it parses
3876 an explicit list of strings instead of the program's environment.
3877 $g->part_add ($device, $prlogex, $startsect, $endsect);
3879 This command adds a partition to "device". If there is no
3880 partition table on the device, call "$g->part_init" first.
3881 The "prlogex" parameter is the type of partition. Normally you
3883 should pass "p" or "primary" here, but MBR partition tables also
3884 support "l" (or "logical") and "e" (or "extended") partition types.
3885 "startsect" and "endsect" are the start and end of the partition in
3887 sectors. "endsect" may be negative, which means it counts
3888 backwards from the end of the disk ("-1" is the last sector).
3889 Creating a partition which covers the whole disk is not so easy.
3891 Use "$g->part_disk" to do that.
3892 $g->part_del ($device, $partnum);
3894 This command deletes the partition numbered "partnum" on "device".
3895 Note that in the case of MBR partitioning, deleting an extended
3897 partition also deletes any logical partitions it contains.
3898 $g->part_disk ($device, $parttype);
3900 This command is simply a combination of "$g->part_init" followed by
3901 "$g->part_add" to create a single primary partition covering the
3902 whole disk.
3903 "parttype" is the partition table type, usually "mbr" or "gpt", but
3905 other possible values are described in "$g->part_init".
3906 $bootable = $g->part_get_bootable ($device, $partnum);
3908 This command returns true if the partition "partnum" on "device"
3909 has the bootable flag set.
3910 See also "$g->part_set_bootable".
3912 $guid = $g->part_get_gpt_type ($device, $partnum);
3914 Return the type GUID of numbered GPT partition "partnum". For MBR
3915 partitions, return an appropriate GUID corresponding to the MBR
3916 type. Behaviour is undefined for other partition types.
3917 $idbyte = $g->part_get_mbr_id ($device, $partnum);
3919 Returns the MBR type byte (also known as the ID byte) from the
3920 numbered partition "partnum".
3921 Note that only MBR (old DOS-style) partitions have type bytes. You
3923 will get undefined results for other partition table types (see
3924 "$g->part_get_parttype").
3925 $parttype = $g->part_get_parttype ($device);
3927 This command examines the partition table on "device" and returns
3928 the partition table type (format) being used.
3929 Common return values include: "msdos" (a DOS/Windows style MBR
3931 partition table), "gpt" (a GPT/EFI-style partition table). Other
3932 values are possible, although unusual. See "$g->part_init" for a
3933 full list.
3934 $g->part_init ($device, $parttype);
3936 This creates an empty partition table on "device" of one of the
3937 partition types listed below. Usually "parttype" should be either
3938 "msdos" or "gpt" (for large disks).
3939 Initially there are no partitions. Following this, you should call
3941 "$g->part_add" for each partition required.
3942 Possible values for "parttype" are:
3944 efi
3946 gpt Intel EFI / GPT partition table.
3947 This is recommended for >= 2 TB partitions that will be
3949 accessed from Linux and Intel-based Mac OS X. It also has
3950 limited backwards compatibility with the "mbr" format.
3951 mbr
3953 msdos
3954 The standard PC "Master Boot Record" (MBR) format used by MS-
3955 DOS and Windows. This partition type will only work for device
3956 sizes up to 2 TB. For large disks we recommend using "gpt".
3957 Other partition table types that may work but are not supported
3959 include:
3960 aix AIX disk labels.
3962 amiga
3964 rdb Amiga "Rigid Disk Block" format.
3965 bsd BSD disk labels.
3967 dasd
3969 DASD, used on IBM mainframes.
3970 dvh MIPS/SGI volumes.
3972 mac Old Mac partition format. Modern Macs use "gpt".
3974 pc98
3976 NEC PC-98 format, common in Japan apparently.
3977 sun Sun disk labels.
3979 @partitions = $g->part_list ($device);
3981 This command parses the partition table on "device" and returns the
3982 list of partitions found.
3983 The fields in the returned structure are:
3985 part_num
3987 Partition number, counting from 1.
3988 part_start
3990 Start of the partition in bytes. To get sectors you have to
3991 divide by the device's sector size, see "$g->blockdev_getss".
3992 part_end
3994 End of the partition in bytes.
3995 part_size
3997 Size of the partition in bytes.
3998 $g->part_set_bootable ($device, $partnum, $bootable);
4000 This sets the bootable flag on partition numbered "partnum" on
4001 device "device". Note that partitions are numbered from 1.
4002 The bootable flag is used by some operating systems (notably
4004 Windows) to determine which partition to boot from. It is by no
4005 means universally recognized.
4006 $g->part_set_gpt_type ($device, $partnum, $guid);
4008 Set the type GUID of numbered GPT partition "partnum" to "guid".
4009 Return an error if the partition table of "device" isn't GPT, or if
4010 "guid" is not a valid GUID.
4011 See
4013 <http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs>
4014 for a useful list of type GUIDs.
4015 $g->part_set_mbr_id ($device, $partnum, $idbyte);
4017 Sets the MBR type byte (also known as the ID byte) of the numbered
4018 partition "partnum" to "idbyte". Note that the type bytes quoted
4019 in most documentation are in fact hexadecimal numbers, but usually
4020 documented without any leading "0x" which might be confusing.
4021 Note that only MBR (old DOS-style) partitions have type bytes. You
4023 will get undefined results for other partition table types (see
4024 "$g->part_get_parttype").
4025 $g->part_set_name ($device, $partnum, $name);
4027 This sets the partition name on partition numbered "partnum" on
4028 device "device". Note that partitions are numbered from 1.
4029 The partition name can only be set on certain types of partition
4031 table. This works on "gpt" but not on "mbr" partitions.
4032 $device = $g->part_to_dev ($partition);
4034 This function takes a partition name (eg. "/dev/sdb1") and removes
4035 the partition number, returning the device name (eg. "/dev/sdb").
4036 The named partition must exist, for example as a string returned
4038 from "$g->list_partitions".
4039 See also "$g->part_to_partnum", "$g->device_index".
4041 $partnum = $g->part_to_partnum ($partition);
4043 This function takes a partition name (eg. "/dev/sdb1") and returns
4044 the partition number (eg. 1).
4045 The named partition must exist, for example as a string returned
4047 from "$g->list_partitions".
4048 See also "$g->part_to_dev".
4050 $g->ping_daemon ();
4052 This is a test probe into the guestfs daemon running inside the
4053 qemu subprocess. Calling this function checks that the daemon
4054 responds to the ping message, without affecting the daemon or
4055 attached block device(s) in any other way.
4056 $content = $g->pread ($path, $count, $offset);
4058 This command lets you read part of a file. It reads "count" bytes
4059 of the file, starting at "offset", from file "path".
4060 This may read fewer bytes than requested. For further details see
4062 the pread(2) system call.
4063 See also "$g->pwrite", "$g->pread_device".
4065 Because of the message protocol, there is a transfer limit of
4067 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
4068 guestfs(3).
4069 $content = $g->pread_device ($device, $count, $offset);
4071 This command lets you read part of a block device. It reads
4072 "count" bytes of "device", starting at "offset".
4073 This may read fewer bytes than requested. For further details see
4075 the pread(2) system call.
4076 See also "$g->pread".
4078 Because of the message protocol, there is a transfer limit of
4080 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
4081 guestfs(3).
4082 $g->pvchange_uuid ($device);
4084 Generate a new random UUID for the physical volume "device".
4085 $g->pvchange_uuid_all ();
4087 Generate new random UUIDs for all physical volumes.
4088 $g->pvcreate ($device);
4090 This creates an LVM physical volume on the named "device", where
4091 "device" should usually be a partition name such as "/dev/sda1".
4092 $g->pvremove ($device);
4094 This wipes a physical volume "device" so that LVM will no longer
4095 recognise it.
4096 The implementation uses the "pvremove" command which refuses to
4098 wipe physical volumes that contain any volume groups, so you have
4099 to remove those first.
4100 $g->pvresize ($device);
4102 This resizes (expands or shrinks) an existing LVM physical volume
4103 to match the new size of the underlying device.
4104 $g->pvresize_size ($device, $size);
4106 This command is the same as "$g->pvresize" except that it allows
4107 you to specify the new size (in bytes) explicitly.
4108 @physvols = $g->pvs ();
4110 List all the physical volumes detected. This is the equivalent of
4111 the pvs(8) command.
4112 This returns a list of just the device names that contain PVs (eg.
4114 "/dev/sda2").
4115 See also "$g->pvs_full".
4117 @physvols = $g->pvs_full ();
4119 List all the physical volumes detected. This is the equivalent of
4120 the pvs(8) command. The "full" version includes all fields.
4121 $uuid = $g->pvuuid ($device);
4123 This command returns the UUID of the LVM PV "device".
4124 $nbytes = $g->pwrite ($path, $content, $offset);
4126 This command writes to part of a file. It writes the data buffer
4127 "content" to the file "path" starting at offset "offset".
4128 This command implements the pwrite(2) system call, and like that
4130 system call it may not write the full data requested. The return
4131 value is the number of bytes that were actually written to the
4132 file. This could even be 0, although short writes are unlikely for
4133 regular files in ordinary circumstances.
4134 See also "$g->pread", "$g->pwrite_device".
4136 Because of the message protocol, there is a transfer limit of
4138 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
4139 guestfs(3).
4140 $nbytes = $g->pwrite_device ($device, $content, $offset);
4142 This command writes to part of a device. It writes the data buffer
4143 "content" to "device" starting at offset "offset".
4144 This command implements the pwrite(2) system call, and like that
4146 system call it may not write the full data requested (although
4147 short writes to disk devices and partitions are probably impossible
4148 with standard Linux kernels).
4149 See also "$g->pwrite".
4151 Because of the message protocol, there is a transfer limit of
4153 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
4154 guestfs(3).
4155 $content = $g->read_file ($path);
4157 This calls returns the contents of the file "path" as a buffer.
4158 Unlike "$g->cat", this function can correctly handle files that
4160 contain embedded ASCII NUL characters.
4161 @lines = $g->read_lines ($path);
4163 Return the contents of the file named "path".
4164 The file contents are returned as a list of lines. Trailing "LF"
4166 and "CRLF" character sequences are not returned.
4167 Note that this function cannot correctly handle binary files
4169 (specifically, files containing "\0" character which is treated as
4170 end of string). For those you need to use the "$g->read_file"
4171 function and split the buffer into lines yourself.
4172 @entries = $g->readdir ($dir);
4174 This returns the list of directory entries in directory "dir".
4175 All entries in the directory are returned, including "." and "..".
4177 The entries are not sorted, but returned in the same order as the
4178 underlying filesystem.
4179 Also this call returns basic file type information about each file.
4181 The "ftyp" field will contain one of the following characters:
4182 'b' Block special
4184 'c' Char special
4186 'd' Directory
4188 'f' FIFO (named pipe)
4190 'l' Symbolic link
4192 'r' Regular file
4194 's' Socket
4196 'u' Unknown file type
4198 '?' The readdir(3) call returned a "d_type" field with an
4200 unexpected value
4201 This function is primarily intended for use by programs. To get a
4203 simple list of names, use "$g->ls". To get a printable directory
4204 for human consumption, use "$g->ll".
4205 Because of the message protocol, there is a transfer limit of
4207 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
4208 guestfs(3).
4209 $link = $g->readlink ($path);
4211 This command reads the target of a symbolic link.
4212 @links = $g->readlinklist ($path, \@names);
4214 This call allows you to do a "readlink" operation on multiple
4215 files, where all files are in the directory "path". "names" is the
4216 list of files from this directory.
4217 On return you get a list of strings, with a one-to-one
4219 correspondence to the "names" list. Each string is the value of
4220 the symbolic link.
4221 If the readlink(2) operation fails on any name, then the
4223 corresponding result string is the empty string "". However the
4224 whole operation is completed even if there were readlink(2) errors,
4225 and so you can call this function with names where you don't know
4226 if they are symbolic links already (albeit slightly less
4227 efficient).
4228 This call is intended for programs that want to efficiently list a
4230 directory contents without making many round-trips.
4231 $rpath = $g->realpath ($path);
4233 Return the canonicalized absolute pathname of "path". The returned
4234 path has no ".", ".." or symbolic link path elements.
4235 $g->remove_drive ($label);
4237 This function is conceptually the opposite of "$g->add_drive_opts".
4238 It removes the drive that was previously added with label "label".
4239 Note that in order to remove drives, you have to add them with
4241 labels (see the optional "label" argument to "$g->add_drive_opts").
4242 If you didn't use a label, then they cannot be removed.
4243 You can call this function before or after launching the handle.
4245 If called after launch, if the attach-method supports it, we try to
4246 hot unplug the drive: see "HOTPLUGGING" in guestfs(3). The disk
4247 must not be in use (eg. mounted) when you do this. We try to
4248 detect if the disk is in use and stop you from doing this.
4249 $g->removexattr ($xattr, $path);
4251 This call removes the extended attribute named "xattr" of the file
4252 "path".
4253 See also: "$g->lremovexattr", attr(5).
4255 $g->rename ($oldpath, $newpath);
4257 Rename a file to a new place on the same filesystem. This is the
4258 same as the Linux rename(2) system call. In most cases you are
4259 better to use "$g->mv" instead.
4260 $g->resize2fs ($device);
4262 This resizes an ext2, ext3 or ext4 filesystem to match the size of
4263 the underlying device.
4264 See also "RESIZE2FS ERRORS" in guestfs(3).
4266 $g->resize2fs_M ($device);
4268 This command is the same as "$g->resize2fs", but the filesystem is
4269 resized to its minimum size. This works like the -M option to the
4270 "resize2fs" command.
4271 To get the resulting size of the filesystem you should call
4273 "$g->tune2fs_l" and read the "Block size" and "Block count" values.
4274 These two numbers, multiplied together, give the resulting size of
4275 the minimal filesystem in bytes.
4276 See also "RESIZE2FS ERRORS" in guestfs(3).
4278 $g->resize2fs_size ($device, $size);
4280 This command is the same as "$g->resize2fs" except that it allows
4281 you to specify the new size (in bytes) explicitly.
4282 See also "RESIZE2FS ERRORS" in guestfs(3).
4284 $g->rm ($path);
4286 Remove the single file "path".
4287 $g->rm_f ($path);
4289 Remove the file "path".
4290 If the file doesn't exist, that error is ignored. (Other errors,
4292 eg. I/O errors or bad paths, are not ignored)
4293 This call cannot remove directories. Use "$g->rmdir" to remove an
4295 empty directory, or "$g->rm_rf" to remove directories recursively.
4296 $g->rm_rf ($path);
4298 Remove the file or directory "path", recursively removing the
4299 contents if its a directory. This is like the "rm -rf" shell
4300 command.
4301 $g->rmdir ($path);
4303 Remove the single directory "path".
4304 $g->rmmountpoint ($exemptpath);
4306 This calls removes a mountpoint that was previously created with
4307 "$g->mkmountpoint". See "$g->mkmountpoint" for full details.
4308 $g->rsync ($src, $dest [, archive => $archive] [, deletedest =>
4310 $deletedest]);
4311 This call may be used to copy or synchronize two directories under
4312 the same libguestfs handle. This uses the rsync(1) program which
4313 uses a fast algorithm that avoids copying files unnecessarily.
4314 "src" and "dest" are the source and destination directories. Files
4316 are copied from "src" to "dest".
4317 The optional arguments are:
4319 "archive"
4321 Turns on archive mode. This is the same as passing the
4322 --archive flag to "rsync".
4323 "deletedest"
4325 Delete files at the destination that do not exist at the
4326 source.
4327 $g->rsync_in ($remote, $dest [, archive => $archive] [, deletedest =>
4329 $deletedest]);
4330 This call may be used to copy or synchronize the filesystem on the
4331 host or on a remote computer with the filesystem within libguestfs.
4332 This uses the rsync(1) program which uses a fast algorithm that
4333 avoids copying files unnecessarily.
4334 This call only works if the network is enabled. See
4336 "$g->set_network" or the --network option to various tools like
4337 guestfish(1).
4338 Files are copied from the remote server and directory specified by
4340 "remote" to the destination directory "dest".
4341 The format of the remote server string is defined by rsync(1).
4343 Note that there is no way to supply a password or passphrase so the
4344 target must be set up not to require one.
4345 The optional arguments are the same as those of "$g->rsync".
4347 $g->rsync_out ($src, $remote [, archive => $archive] [, deletedest =>
4349 $deletedest]);
4350 This call may be used to copy or synchronize the filesystem within
4351 libguestfs with a filesystem on the host or on a remote computer.
4352 This uses the rsync(1) program which uses a fast algorithm that
4353 avoids copying files unnecessarily.
4354 This call only works if the network is enabled. See
4356 "$g->set_network" or the --network option to various tools like
4357 guestfish(1).
4358 Files are copied from the source directory "src" to the remote
4360 server and directory specified by "remote".
4361 The format of the remote server string is defined by rsync(1).
4363 Note that there is no way to supply a password or passphrase so the
4364 target must be set up not to require one.
4365 The optional arguments are the same as those of "$g->rsync".
4367 Globbing does not happen on the "src" parameter. In programs which
4369 use the API directly you have to expand wildcards yourself (see
4370 "$g->glob_expand"). In guestfish you can use the "glob" command
4371 (see "glob" in guestfish(1)), for example:
4372 ><fs> glob rsync-out /* rsync://remote/
4374 $g->scrub_device ($device);
4376 This command writes patterns over "device" to make data retrieval
4377 more difficult.
4378 It is an interface to the scrub(1) program. See that manual page
4380 for more details.
4381 $g->scrub_file ($file);
4383 This command writes patterns over a file to make data retrieval
4384 more difficult.
4385 The file is removed after scrubbing.
4387 It is an interface to the scrub(1) program. See that manual page
4389 for more details.
4390 $g->scrub_freespace ($dir);
4392 This command creates the directory "dir" and then fills it with
4393 files until the filesystem is full, and scrubs the files as for
4394 "$g->scrub_file", and deletes them. The intention is to scrub any
4395 free space on the partition containing "dir".
4396 It is an interface to the scrub(1) program. See that manual page
4398 for more details.
4399 $g->set_append ($append);
4401 This function is used to add additional options to the libguestfs
4402 appliance kernel command line.
4403 The default is "NULL" unless overridden by setting
4405 "LIBGUESTFS_APPEND" environment variable.
4406 Setting "append" to "NULL" means no additional options are passed
4408 (libguestfs always adds a few of its own).
4409 $g->set_attach_method ($attachmethod);
4411 Set the method that libguestfs uses to connect to the back end
4412 guestfsd daemon.
4413 See "ATTACH METHOD" in guestfs(3).
4415 $g->set_autosync ($autosync);
4417 If "autosync" is true, this enables autosync. Libguestfs will make
4418 a best effort attempt to make filesystems consistent and
4419 synchronized when the handle is closed (also if the program exits
4420 without closing handles).
4421 This is enabled by default (since libguestfs 1.5.24, previously it
4423 was disabled by default).
4424 $g->set_cachedir ($cachedir);
4426 Set the directory used by the handle to store the appliance cache,
4427 when using a supermin appliance. The appliance is cached and
4428 shared between all handles which have the same effective user ID.
4429 The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR"
4431 control the default value: If "LIBGUESTFS_CACHEDIR" is set, then
4432 that is the default. Else if "TMPDIR" is set, then that is the
4433 default. Else "/var/tmp" is the default.
4434 $g->set_direct ($direct);
4436 If the direct appliance mode flag is enabled, then stdin and stdout
4437 are passed directly through to the appliance once it is launched.
4438 One consequence of this is that log messages aren't caught by the
4440 library and handled by "$g->set_log_message_callback", but go
4441 straight to stdout.
4442 You probably don't want to use this unless you know what you are
4444 doing.
4445 The default is disabled.
4447 $g->set_e2attrs ($file, $attrs [, clear => $clear]);
4449 This sets or clears the file attributes "attrs" associated with the
4450 inode "file".
4451 "attrs" is a string of characters representing file attributes.
4453 See "$g->get_e2attrs" for a list of possible attributes. Not all
4454 attributes can be changed.
4455 If optional boolean "clear" is not present or false, then the
4457 "attrs" listed are set in the inode.
4458 If "clear" is true, then the "attrs" listed are cleared in the
4460 inode.
4461 In both cases, other attributes not present in the "attrs" string
4463 are left unchanged.
4464 These attributes are only present when the file is located on an
4466 ext2/3/4 filesystem. Using this call on other filesystem types
4467 will result in an error.
4468 $g->set_e2generation ($file, $generation);
4470 This sets the ext2 file generation of a file.
4471 See "$g->get_e2generation".
4473 $g->set_e2label ($device, $label);
4475 This sets the ext2/3/4 filesystem label of the filesystem on
4476 "device" to "label". Filesystem labels are limited to 16
4477 characters.
4478 You can use either "$g->tune2fs_l" or "$g->get_e2label" to return
4480 the existing label on a filesystem.
4481 This function is deprecated. In new code, use the "set_label" call
4483 instead.
4484 Deprecated functions will not be removed from the API, but the fact
4486 that they are deprecated indicates that there are problems with
4487 correct use of these functions.
4488 $g->set_e2uuid ($device, $uuid);
4490 This sets the ext2/3/4 filesystem UUID of the filesystem on
4491 "device" to "uuid". The format of the UUID and alternatives such
4492 as "clear", "random" and "time" are described in the tune2fs(8)
4493 manpage.
4494 You can use either "$g->tune2fs_l" or "$g->get_e2uuid" to return
4496 the existing UUID of a filesystem.
4497 $g->set_label ($device, $label);
4499 Set the filesystem label on "device" to "label".
4500 Only some filesystem types support labels, and libguestfs supports
4502 setting labels on only a subset of these.
4503 ext2, ext3, ext4
4505 Labels are limited to 16 bytes.
4506 NTFS
4508 Labels are limited to 128 unicode characters.
4509 XFS The label is limited to 12 bytes. The filesystem must not be
4511 mounted when trying to set the label.
4512 btrfs
4514 The label is limited to 255 bytes and some characters are not
4515 allowed. Setting the label on a btrfs subvolume will set the
4516 label on its parent filesystem. The filesystem must not be
4517 mounted when trying to set the label.
4518 To read the label on a filesystem, call "$g->vfs_label".
4520 $g->set_libvirt_requested_credential ($index, $cred);
4522 After requesting the "index"'th credential from the user, call this
4523 function to pass the answer back to libvirt.
4524 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4526 example code.
4527 $g->set_libvirt_supported_credentials (\@creds);
4529 Call this function before setting an event handler for
4530 "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential
4531 types that the program knows how to process.
4532 The "creds" list must be a non-empty list of strings. Possible
4534 strings are:
4535 "username"
4537 "authname"
4538 "language"
4539 "cnonce"
4540 "passphrase"
4541 "echoprompt"
4542 "noechoprompt"
4543 "realm"
4544 "external"
4545 See libvirt documentation for the meaning of these credential
4547 types.
4548 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4550 example code.
4551 $g->set_memsize ($memsize);
4553 This sets the memory size in megabytes allocated to the qemu
4554 subprocess. This only has any effect if called before
4555 "$g->launch".
4556 You can also change this by setting the environment variable
4558 "LIBGUESTFS_MEMSIZE" before the handle is created.
4559 For more information on the architecture of libguestfs, see
4561 guestfs(3).
4562 $g->set_network ($network);
4564 If "network" is true, then the network is enabled in the libguestfs
4565 appliance. The default is false.
4566 This affects whether commands are able to access the network (see
4568 "RUNNING COMMANDS" in guestfs(3)).
4569 You must call this before calling "$g->launch", otherwise it has no
4571 effect.
4572 $g->set_path ($searchpath);
4574 Set the path that libguestfs searches for kernel and initrd.img.
4575 The default is "$libdir/guestfs" unless overridden by setting
4577 "LIBGUESTFS_PATH" environment variable.
4578 Setting "path" to "NULL" restores the default path.
4580 $g->set_pgroup ($pgroup);
4582 If "pgroup" is true, child processes are placed into their own
4583 process group.
4584 The practical upshot of this is that signals like "SIGINT" (from
4586 users pressing "^C") won't be received by the child process.
4587 The default for this flag is false, because usually you want "^C"
4589 to kill the subprocess. Guestfish sets this flag to true when used
4590 interactively, so that "^C" can cancel long-running commands
4591 gracefully (see "$g->user_cancel").
4592 $g->set_qemu ($qemu);
4594 Set the qemu binary that we will use.
4595 The default is chosen when the library was compiled by the
4597 configure script.
4598 You can also override this by setting the "LIBGUESTFS_QEMU"
4600 environment variable.
4601 Setting "qemu" to "NULL" restores the default qemu binary.
4603 Note that you should call this function as early as possible after
4605 creating the handle. This is because some pre-launch operations
4606 depend on testing qemu features (by running "qemu -help"). If the
4607 qemu binary changes, we don't retest features, and so you might see
4608 inconsistent results. Using the environment variable
4609 "LIBGUESTFS_QEMU" is safest of all since that picks the qemu binary
4610 at the same time as the handle is created.
4611 $g->set_recovery_proc ($recoveryproc);
4613 If this is called with the parameter "false" then "$g->launch" does
4614 not create a recovery process. The purpose of the recovery process
4615 is to stop runaway qemu processes in the case where the main
4616 program aborts abruptly.
4617 This only has any effect if called before "$g->launch", and the
4619 default is true.
4620 About the only time when you would want to disable this is if the
4622 main process will fork itself into the background ("daemonize"
4623 itself). In this case the recovery process thinks that the main
4624 program has disappeared and so kills qemu, which is not very
4625 helpful.
4626 $g->set_selinux ($selinux);
4628 This sets the selinux flag that is passed to the appliance at boot
4629 time. The default is "selinux=0" (disabled).
4630 Note that if SELinux is enabled, it is always in Permissive mode
4632 ("enforcing=0").
4633 For more information on the architecture of libguestfs, see
4635 guestfs(3).
4636 $g->set_smp ($smp);
4638 Change the number of virtual CPUs assigned to the appliance. The
4639 default is 1. Increasing this may improve performance, though
4640 often it has no effect.
4641 This function must be called before "$g->launch".
4643 $g->set_tmpdir ($tmpdir);
4645 Set the directory used by the handle to store temporary files.
4646 The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control
4648 the default value: If "LIBGUESTFS_TMPDIR" is set, then that is the
4649 default. Else if "TMPDIR" is set, then that is the default. Else
4650 "/tmp" is the default.
4651 $g->set_trace ($trace);
4653 If the command trace flag is set to 1, then libguestfs calls,
4654 parameters and return values are traced.
4655 If you want to trace C API calls into libguestfs (and other
4657 libraries) then possibly a better way is to use the external
4658 ltrace(1) command.
4659 Command traces are disabled unless the environment variable
4661 "LIBGUESTFS_TRACE" is defined and set to 1.
4662 Trace messages are normally sent to "stderr", unless you register a
4664 callback to send them somewhere else (see
4665 "$g->set_event_callback").
4666 $g->set_verbose ($verbose);
4668 If "verbose" is true, this turns on verbose messages.
4669 Verbose messages are disabled unless the environment variable
4671 "LIBGUESTFS_DEBUG" is defined and set to 1.
4672 Verbose messages are normally sent to "stderr", unless you register
4674 a callback to send them somewhere else (see
4675 "$g->set_event_callback").
4676 $g->setcon ($context);
4678 This sets the SELinux security context of the daemon to the string
4679 "context".
4680 See the documentation about SELINUX in guestfs(3).
4682 $g->setxattr ($xattr, $val, $vallen, $path);
4684 This call sets the extended attribute named "xattr" of the file
4685 "path" to the value "val" (of length "vallen"). The value is
4686 arbitrary 8 bit data.
4687 See also: "$g->lsetxattr", attr(5).
4689 $g->sfdisk ($device, $cyls, $heads, $sectors, \@lines);
4691 This is a direct interface to the sfdisk(8) program for creating
4692 partitions on block devices.
4693 "device" should be a block device, for example "/dev/sda".
4695 "cyls", "heads" and "sectors" are the number of cylinders, heads
4697 and sectors on the device, which are passed directly to sfdisk as
4698 the -C, -H and -S parameters. If you pass 0 for any of these, then
4699 the corresponding parameter is omitted. Usually for 'large' disks,
4700 you can just pass 0 for these, but for small (floppy-sized) disks,
4701 sfdisk (or rather, the kernel) cannot work out the right geometry
4702 and you will need to tell it.
4703 "lines" is a list of lines that we feed to "sfdisk". For more
4705 information refer to the sfdisk(8) manpage.
4706 To create a single partition occupying the whole disk, you would
4708 pass "lines" as a single element list, when the single element
4709 being the string "," (comma).
4710 See also: "$g->sfdisk_l", "$g->sfdisk_N", "$g->part_init"
4712 This function is deprecated. In new code, use the "part_add" call
4714 instead.
4715 Deprecated functions will not be removed from the API, but the fact
4717 that they are deprecated indicates that there are problems with
4718 correct use of these functions.
4719 $g->sfdiskM ($device, \@lines);
4721 This is a simplified interface to the "$g->sfdisk" command, where
4722 partition sizes are specified in megabytes only (rounded to the
4723 nearest cylinder) and you don't need to specify the cyls, heads and
4724 sectors parameters which were rarely if ever used anyway.
4725 See also: "$g->sfdisk", the sfdisk(8) manpage and "$g->part_disk"
4727 This function is deprecated. In new code, use the "part_add" call
4729 instead.
4730 Deprecated functions will not be removed from the API, but the fact
4732 that they are deprecated indicates that there are problems with
4733 correct use of these functions.
4734 $g->sfdisk_N ($device, $partnum, $cyls, $heads, $sectors, $line);
4736 This runs sfdisk(8) option to modify just the single partition "n"
4737 (note: "n" counts from 1).
4738 For other parameters, see "$g->sfdisk". You should usually pass 0
4740 for the cyls/heads/sectors parameters.
4741 See also: "$g->part_add"
4743 This function is deprecated. In new code, use the "part_add" call
4745 instead.
4746 Deprecated functions will not be removed from the API, but the fact
4748 that they are deprecated indicates that there are problems with
4749 correct use of these functions.
4750 $partitions = $g->sfdisk_disk_geometry ($device);
4752 This displays the disk geometry of "device" read from the partition
4753 table. Especially in the case where the underlying block device
4754 has been resized, this can be different from the kernel's idea of
4755 the geometry (see "$g->sfdisk_kernel_geometry").
4756 The result is in human-readable format, and not designed to be
4758 parsed.
4759 $partitions = $g->sfdisk_kernel_geometry ($device);
4761 This displays the kernel's idea of the geometry of "device".
4762 The result is in human-readable format, and not designed to be
4764 parsed.
4765 $partitions = $g->sfdisk_l ($device);
4767 This displays the partition table on "device", in the human-
4768 readable output of the sfdisk(8) command. It is not intended to be
4769 parsed.
4770 See also: "$g->part_list"
4772 This function is deprecated. In new code, use the "part_list" call
4774 instead.
4775 Deprecated functions will not be removed from the API, but the fact
4777 that they are deprecated indicates that there are problems with
4778 correct use of these functions.
4779 $output = $g->sh ($command);
4781 This call runs a command from the guest filesystem via the guest's
4782 "/bin/sh".
4783 This is like "$g->command", but passes the command to:
4785 /bin/sh -c "command"
4787 Depending on the guest's shell, this usually results in wildcards
4789 being expanded, shell expressions being interpolated and so on.
4790 All the provisos about "$g->command" apply to this call.
4792 @lines = $g->sh_lines ($command);
4794 This is the same as "$g->sh", but splits the result into a list of
4795 lines.
4796 See also: "$g->command_lines"
4798 $g->shutdown ();
4800 This is the opposite of "$g->launch". It performs an orderly
4801 shutdown of the backend process(es). If the autosync flag is set
4802 (which is the default) then the disk image is synchronized.
4803 If the subprocess exits with an error then this function will
4805 return an error, which should not be ignored (it may indicate that
4806 the disk image could not be written out properly).
4807 It is safe to call this multiple times. Extra calls are ignored.
4809 This call does not close or free up the handle. You still need to
4811 call "$g->close" afterwards.
4812 "$g->close" will call this if you don't do it explicitly, but note
4814 that any errors are ignored in that case.
4815 $g->sleep ($secs);
4817 Sleep for "secs" seconds.
4818 %statbuf = $g->stat ($path);
4820 Returns file information for the given "path".
4821 This is the same as the stat(2) system call.
4823 %statbuf = $g->statvfs ($path);
4825 Returns file system statistics for any mounted file system. "path"
4826 should be a file or directory in the mounted file system (typically
4827 it is the mount point itself, but it doesn't need to be).
4828 This is the same as the statvfs(2) system call.
4830 @stringsout = $g->strings ($path);
4832 This runs the strings(1) command on a file and returns the list of
4833 printable strings found.
4834 Because of the message protocol, there is a transfer limit of
4836 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
4837 guestfs(3).
4838 @stringsout = $g->strings_e ($encoding, $path);
4840 This is like the "$g->strings" command, but allows you to specify
4841 the encoding of strings that are looked for in the source file
4842 "path".
4843 Allowed encodings are:
4845 s Single 7-bit-byte characters like ASCII and the ASCII-
4847 compatible parts of ISO-8859-X (this is what "$g->strings"
4848 uses).
4849 S Single 8-bit-byte characters.
4851 b 16-bit big endian strings such as those encoded in UTF-16BE or
4853 UCS-2BE.
4854 l (lower case letter L)
4856 16-bit little endian such as UTF-16LE and UCS-2LE. This is
4857 useful for examining binaries in Windows guests.
4858 B 32-bit big endian such as UCS-4BE.
4860 L 32-bit little endian such as UCS-4LE.
4862 The returned strings are transcoded to UTF-8.
4864 Because of the message protocol, there is a transfer limit of
4866 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
4867 guestfs(3).
4868 $g->swapoff_device ($device);
4870 This command disables the libguestfs appliance swap device or
4871 partition named "device". See "$g->swapon_device".
4872 $g->swapoff_file ($file);
4874 This command disables the libguestfs appliance swap on file.
4875 $g->swapoff_label ($label);
4877 This command disables the libguestfs appliance swap on labeled swap
4878 partition.
4879 $g->swapoff_uuid ($uuid);
4881 This command disables the libguestfs appliance swap partition with
4882 the given UUID.
4883 $g->swapon_device ($device);
4885 This command enables the libguestfs appliance to use the swap
4886 device or partition named "device". The increased memory is made
4887 available for all commands, for example those run using
4888 "$g->command" or "$g->sh".
4889 Note that you should not swap to existing guest swap partitions
4891 unless you know what you are doing. They may contain hibernation
4892 information, or other information that the guest doesn't want you
4893 to trash. You also risk leaking information about the host to the
4894 guest this way. Instead, attach a new host device to the guest and
4895 swap on that.
4896 $g->swapon_file ($file);
4898 This command enables swap to a file. See "$g->swapon_device" for
4899 other notes.
4900 $g->swapon_label ($label);
4902 This command enables swap to a labeled swap partition. See
4903 "$g->swapon_device" for other notes.
4904 $g->swapon_uuid ($uuid);
4906 This command enables swap to a swap partition with the given UUID.
4907 See "$g->swapon_device" for other notes.
4908 $g->sync ();
4910 This syncs the disk, so that any writes are flushed through to the
4911 underlying disk image.
4912 You should always call this if you have modified a disk image,
4914 before closing the handle.
4915 @lines = $g->tail ($path);
4917 This command returns up to the last 10 lines of a file as a list of
4918 strings.
4919 Because of the message protocol, there is a transfer limit of
4921 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
4922 guestfs(3).
4923 @lines = $g->tail_n ($nrlines, $path);
4925 If the parameter "nrlines" is a positive number, this returns the
4926 last "nrlines" lines of the file "path".
4927 If the parameter "nrlines" is a negative number, this returns lines
4929 from the file "path", starting with the "-nrlines"th line.
4930 If the parameter "nrlines" is zero, this returns an empty list.
4932 Because of the message protocol, there is a transfer limit of
4934 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
4935 guestfs(3).
4936 $g->tar_in ($tarfile, $directory [, compress => $compress]);
4938 This command uploads and unpacks local file "tarfile" into
4939 "directory".
4940 The optional "compress" flag controls compression. If not given,
4942 then the input should be an uncompressed tar file. Otherwise one
4943 of the following strings may be given to select the compression
4944 type of the input file: "compress", "gzip", "bzip2", "xz", "lzop".
4945 (Note that not all builds of libguestfs will support all of these
4946 compression types).
4947 $g->tar_in_opts ($tarfile, $directory [, compress => $compress]);
4949 This is an alias of "tar_in".
4950 $g->tar_out ($directory, $tarfile [, compress => $compress] [,
4952 numericowner => $numericowner] [, excludes => $excludes]);
4953 This command packs the contents of "directory" and downloads it to
4954 local file "tarfile".
4955 The optional "compress" flag controls compression. If not given,
4957 then the output will be an uncompressed tar file. Otherwise one of
4958 the following strings may be given to select the compression type
4959 of the output file: "compress", "gzip", "bzip2", "xz", "lzop".
4960 (Note that not all builds of libguestfs will support all of these
4961 compression types).
4962 The other optional arguments are:
4964 "excludes"
4966 A list of wildcards. Files are excluded if they match any of
4967 the wildcards.
4968 "numericowner"
4970 If set to true, the output tar file will contain UID/GID
4971 numbers instead of user/group names.
4972 $g->tar_out_opts ($directory, $tarfile [, compress => $compress] [,
4974 numericowner => $numericowner] [, excludes => $excludes]);
4975 This is an alias of "tar_out".
4976 $g->tgz_in ($tarball, $directory);
4978 This command uploads and unpacks local file "tarball" (a gzip
4979 compressed tar file) into "directory".
4980 This function is deprecated. In new code, use the "tar_in" call
4982 instead.
4983 Deprecated functions will not be removed from the API, but the fact
4985 that they are deprecated indicates that there are problems with
4986 correct use of these functions.
4987 $g->tgz_out ($directory, $tarball);
4989 This command packs the contents of "directory" and downloads it to
4990 local file "tarball".
4991 This function is deprecated. In new code, use the "tar_out" call
4993 instead.
4994 Deprecated functions will not be removed from the API, but the fact
4996 that they are deprecated indicates that there are problems with
4997 correct use of these functions.
4998 $g->touch ($path);
5000 Touch acts like the touch(1) command. It can be used to update the
5001 timestamps on a file, or, if the file does not exist, to create a
5002 new zero-length file.
5003 This command only works on regular files, and will fail on other
5005 file types such as directories, symbolic links, block special etc.
5006 $g->truncate ($path);
5008 This command truncates "path" to a zero-length file. The file must
5009 exist already.
5010 $g->truncate_size ($path, $size);
5012 This command truncates "path" to size "size" bytes. The file must
5013 exist already.
5014 If the current file size is less than "size" then the file is
5016 extended to the required size with zero bytes. This creates a
5017 sparse file (ie. disk blocks are not allocated for the file until
5018 you write to it). To create a non-sparse file of zeroes, use
5019 "$g->fallocate64" instead.
5020 $g->tune2fs ($device [, force => $force] [, maxmountcount =>
5022 $maxmountcount] [, mountcount => $mountcount] [, errorbehavior =>
5023 $errorbehavior] [, group => $group] [, intervalbetweenchecks =>
5024 $intervalbetweenchecks] [, reservedblockspercentage =>
5025 $reservedblockspercentage] [, lastmounteddirectory =>
5026 $lastmounteddirectory] [, reservedblockscount => $reservedblockscount]
5027 [, user => $user]);
5028 This call allows you to adjust various filesystem parameters of an
5029 ext2/ext3/ext4 filesystem called "device".
5030 The optional parameters are:
5032 "force"
5034 Force tune2fs to complete the operation even in the face of
5035 errors. This is the same as the tune2fs "-f" option.
5036 "maxmountcount"
5038 Set the number of mounts after which the filesystem is checked
5039 by e2fsck(8). If this is 0 then the number of mounts is
5040 disregarded. This is the same as the tune2fs "-c" option.
5041 "mountcount"
5043 Set the number of times the filesystem has been mounted. This
5044 is the same as the tune2fs "-C" option.
5045 "errorbehavior"
5047 Change the behavior of the kernel code when errors are
5048 detected. Possible values currently are: "continue",
5049 "remount-ro", "panic". In practice these options don't really
5050 make any difference, particularly for write errors.
5051 This is the same as the tune2fs "-e" option.
5053 "group"
5055 Set the group which can use reserved filesystem blocks. This
5056 is the same as the tune2fs "-g" option except that it can only
5057 be specified as a number.
5058 "intervalbetweenchecks"
5060 Adjust the maximal time between two filesystem checks (in
5061 seconds). If the option is passed as 0 then time-dependent
5062 checking is disabled.
5063 This is the same as the tune2fs "-i" option.
5065 "reservedblockspercentage"
5067 Set the percentage of the filesystem which may only be
5068 allocated by privileged processes. This is the same as the
5069 tune2fs "-m" option.
5070 "lastmounteddirectory"
5072 Set the last mounted directory. This is the same as the
5073 tune2fs "-M" option.
5074 "reservedblockscount" Set the number of reserved filesystem blocks.
5076 This is the same as the tune2fs "-r" option.
5077 "user"
5078 Set the user who can use the reserved filesystem blocks. This
5079 is the same as the tune2fs "-u" option except that it can only
5080 be specified as a number.
5081 To get the current values of filesystem parameters, see
5083 "$g->tune2fs_l". For precise details of how tune2fs works, see the
5084 tune2fs(8) man page.
5085 %superblock = $g->tune2fs_l ($device);
5087 This returns the contents of the ext2, ext3 or ext4 filesystem
5088 superblock on "device".
5089 It is the same as running "tune2fs -l device". See tune2fs(8)
5091 manpage for more details. The list of fields returned isn't
5092 clearly defined, and depends on both the version of "tune2fs" that
5093 libguestfs was built against, and the filesystem itself.
5094 $g->txz_in ($tarball, $directory);
5096 This command uploads and unpacks local file "tarball" (an xz
5097 compressed tar file) into "directory".
5098 This function is deprecated. In new code, use the "tar_in" call
5100 instead.
5101 Deprecated functions will not be removed from the API, but the fact
5103 that they are deprecated indicates that there are problems with
5104 correct use of these functions.
5105 $g->txz_out ($directory, $tarball);
5107 This command packs the contents of "directory" and downloads it to
5108 local file "tarball" (as an xz compressed tar archive).
5109 This function is deprecated. In new code, use the "tar_out" call
5111 instead.
5112 Deprecated functions will not be removed from the API, but the fact
5114 that they are deprecated indicates that there are problems with
5115 correct use of these functions.
5116 $oldmask = $g->umask ($mask);
5118 This function sets the mask used for creating new files and device
5119 nodes to "mask & 0777".
5120 Typical umask values would be 022 which creates new files with
5122 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which
5123 creates new files with permissions like "-rw-rw-r--" or
5124 "-rwxrwxr-x".
5125 The default umask is 022. This is important because it means that
5127 directories and device nodes will be created with 0644 or 0755 mode
5128 even if you specify 0777.
5129 See also "$g->get_umask", umask(2), "$g->mknod", "$g->mkdir".
5131 This call returns the previous umask.
5133 $g->umount ($pathordevice [, force => $force] [, lazyunmount =>
5135 $lazyunmount]);
5136 This unmounts the given filesystem. The filesystem may be
5137 specified either by its mountpoint (path) or the device which
5138 contains the filesystem.
5139 $g->umount_opts ($pathordevice [, force => $force] [, lazyunmount =>
5141 $lazyunmount]);
5142 This is an alias of "umount".
5143 $g->umount_all ();
5145 This unmounts all mounted filesystems.
5146 Some internal mounts are not unmounted by this call.
5148 $g->umount_local ([retry => $retry]);
5150 If libguestfs is exporting the filesystem on a local mountpoint,
5151 then this unmounts it.
5152 See "MOUNT LOCAL" in guestfs(3) for full documentation.
5154 $g->upload ($filename, $remotefilename);
5156 Upload local file "filename" to "remotefilename" on the filesystem.
5157 "filename" can also be a named pipe.
5159 See also "$g->download".
5161 $g->upload_offset ($filename, $remotefilename, $offset);
5163 Upload local file "filename" to "remotefilename" on the filesystem.
5164 "remotefilename" is overwritten starting at the byte "offset"
5166 specified. The intention is to overwrite parts of existing files
5167 or devices, although if a non-existent file is specified then it is
5168 created with a "hole" before "offset". The size of the data
5169 written is implicit in the size of the source "filename".
5170 Note that there is no limit on the amount of data that can be
5172 uploaded with this call, unlike with "$g->pwrite", and this call
5173 always writes the full amount unless an error occurs.
5174 See also "$g->upload", "$g->pwrite".
5176 $g->user_cancel ();
5178 This function cancels the current upload or download operation.
5179 Unlike most other libguestfs calls, this function is signal safe
5181 and thread safe. You can call it from a signal handler or from
5182 another thread, without needing to do any locking.
5183 The transfer that was in progress (if there is one) will stop
5185 shortly afterwards, and will return an error. The errno (see
5186 "guestfs_last_errno") is set to "EINTR", so you can test for this
5187 to find out if the operation was cancelled or failed because of
5188 another error.
5189 No cleanup is performed: for example, if a file was being uploaded
5191 then after cancellation there may be a partially uploaded file. It
5192 is the caller's responsibility to clean up if necessary.
5193 There are two common places that you might call "$g->user_cancel":
5195 In an interactive text-based program, you might call it from a
5197 "SIGINT" signal handler so that pressing "^C" cancels the current
5198 operation. (You also need to call "guestfs_set_pgroup" so that
5199 child processes don't receive the "^C" signal).
5200 In a graphical program, when the main thread is displaying a
5202 progress bar with a cancel button, wire up the cancel button to
5203 call this function.
5204 $g->utimens ($path, $atsecs, $atnsecs, $mtsecs, $mtnsecs);
5206 This command sets the timestamps of a file with nanosecond
5207 precision.
5208 "atsecs, atnsecs" are the last access time (atime) in secs and
5210 nanoseconds from the epoch.
5211 "mtsecs, mtnsecs" are the last modification time (mtime) in secs
5213 and nanoseconds from the epoch.
5214 If the *nsecs field contains the special value "-1" then the
5216 corresponding timestamp is set to the current time. (The *secs
5217 field is ignored in this case).
5218 If the *nsecs field contains the special value "-2" then the
5220 corresponding timestamp is left unchanged. (The *secs field is
5221 ignored in this case).
5222 %uts = $g->utsname ();
5224 This returns the kernel version of the appliance, where this is
5225 available. This information is only useful for debugging. Nothing
5226 in the returned structure is defined by the API.
5227 %version = $g->version ();
5229 Return the libguestfs version number that the program is linked
5230 against.
5231 Note that because of dynamic linking this is not necessarily the
5233 version of libguestfs that you compiled against. You can compile
5234 the program, and then at runtime dynamically link against a
5235 completely different "libguestfs.so" library.
5236 This call was added in version 1.0.58. In previous versions of
5238 libguestfs there was no way to get the version number. From C code
5239 you can use dynamic linker functions to find out if this symbol
5240 exists (if it doesn't, then it's an earlier version).
5241 The call returns a structure with four elements. The first three
5243 ("major", "minor" and "release") are numbers and correspond to the
5244 usual version triplet. The fourth element ("extra") is a string
5245 and is normally empty, but may be used for distro-specific
5246 information.
5247 To construct the original version string:
5249 "$major.$minor.$release$extra"
5250 See also: "LIBGUESTFS VERSION NUMBERS" in guestfs(3).
5252 Note: Don't use this call to test for availability of features. In
5254 enterprise distributions we backport features from later versions
5255 into earlier versions, making this an unreliable way to test for
5256 features. Use "$g->available" instead.
5257 $label = $g->vfs_label ($device);
5259 This returns the filesystem label of the filesystem on "device".
5260 If the filesystem is unlabeled, this returns the empty string.
5262 To find a filesystem from the label, use "$g->findfs_label".
5264 $fstype = $g->vfs_type ($device);
5266 This command gets the filesystem type corresponding to the
5267 filesystem on "device".
5268 For most filesystems, the result is the name of the Linux VFS
5270 module which would be used to mount this filesystem if you mounted
5271 it without specifying the filesystem type. For example a string
5272 such as "ext3" or "ntfs".
5273 $uuid = $g->vfs_uuid ($device);
5275 This returns the filesystem UUID of the filesystem on "device".
5276 If the filesystem does not have a UUID, this returns the empty
5278 string.
5279 To find a filesystem from the UUID, use "$g->findfs_uuid".
5281 $g->vg_activate ($activate, \@volgroups);
5283 This command activates or (if "activate" is false) deactivates all
5284 logical volumes in the listed volume groups "volgroups".
5285 This command is the same as running "vgchange -a y|n volgroups..."
5287 Note that if "volgroups" is an empty list then all volume groups
5289 are activated or deactivated.
5290 $g->vg_activate_all ($activate);
5292 This command activates or (if "activate" is false) deactivates all
5293 logical volumes in all volume groups.
5294 This command is the same as running "vgchange -a y|n"
5296 $g->vgchange_uuid ($vg);
5298 Generate a new random UUID for the volume group "vg".
5299 $g->vgchange_uuid_all ();
5301 Generate new random UUIDs for all volume groups.
5302 $g->vgcreate ($volgroup, \@physvols);
5304 This creates an LVM volume group called "volgroup" from the non-
5305 empty list of physical volumes "physvols".
5306 @uuids = $g->vglvuuids ($vgname);
5308 Given a VG called "vgname", this returns the UUIDs of all the
5309 logical volumes created in this volume group.
5310 You can use this along with "$g->lvs" and "$g->lvuuid" calls to
5312 associate logical volumes and volume groups.
5313 See also "$g->vgpvuuids".
5315 $metadata = $g->vgmeta ($vgname);
5317 "vgname" is an LVM volume group. This command examines the volume
5318 group and returns its metadata.
5319 Note that the metadata is an internal structure used by LVM,
5321 subject to change at any time, and is provided for information
5322 only.
5323 @uuids = $g->vgpvuuids ($vgname);
5325 Given a VG called "vgname", this returns the UUIDs of all the
5326 physical volumes that this volume group resides on.
5327 You can use this along with "$g->pvs" and "$g->pvuuid" calls to
5329 associate physical volumes and volume groups.
5330 See also "$g->vglvuuids".
5332 $g->vgremove ($vgname);
5334 Remove an LVM volume group "vgname", (for example "VG").
5335 This also forcibly removes all logical volumes in the volume group
5337 (if any).
5338 $g->vgrename ($volgroup, $newvolgroup);
5340 Rename a volume group "volgroup" with the new name "newvolgroup".
5341 @volgroups = $g->vgs ();
5343 List all the volumes groups detected. This is the equivalent of
5344 the vgs(8) command.
5345 This returns a list of just the volume group names that were
5347 detected (eg. "VolGroup00").
5348 See also "$g->vgs_full".
5350 @volgroups = $g->vgs_full ();
5352 List all the volumes groups detected. This is the equivalent of
5353 the vgs(8) command. The "full" version includes all fields.
5354 $g->vgscan ();
5356 This rescans all block devices and rebuilds the list of LVM
5357 physical volumes, volume groups and logical volumes.
5358 $uuid = $g->vguuid ($vgname);
5360 This command returns the UUID of the LVM VG named "vgname".
5361 $g->wait_ready ();
5363 This function is a no op.
5364 In versions of the API < 1.0.71 you had to call this function just
5366 after calling "$g->launch" to wait for the launch to complete.
5367 However this is no longer necessary because "$g->launch" now does
5368 the waiting.
5369 If you see any calls to this function in code then you can just
5371 remove them, unless you want to retain compatibility with older
5372 versions of the API.
5373 This function is deprecated. In new code, use the "launch" call
5375 instead.
5376 Deprecated functions will not be removed from the API, but the fact
5378 that they are deprecated indicates that there are problems with
5379 correct use of these functions.
5380 $chars = $g->wc_c ($path);
5382 This command counts the characters in a file, using the "wc -c"
5383 external command.
5384 $lines = $g->wc_l ($path);
5386 This command counts the lines in a file, using the "wc -l" external
5387 command.
5388 $words = $g->wc_w ($path);
5390 This command counts the words in a file, using the "wc -w" external
5391 command.
5392 $g->wipefs ($device);
5394 This command erases filesystem or RAID signatures from the
5395 specified "device" to make the filesystem invisible to libblkid.
5396 This does not erase the filesystem itself nor any other data from
5398 the "device".
5399 Compare with "$g->zero" which zeroes the first few blocks of a
5401 device.
5402 $g->write ($path, $content);
5404 This call creates a file called "path". The content of the file is
5405 the string "content" (which can contain any 8 bit data).
5406 See also "$g->write_append".
5408 $g->write_append ($path, $content);
5410 This call appends "content" to the end of file "path". If "path"
5411 does not exist, then a new file is created.
5412 See also "$g->write".
5414 $g->write_file ($path, $content, $size);
5416 This call creates a file called "path". The contents of the file
5417 is the string "content" (which can contain any 8 bit data), with
5418 length "size".
5419 As a special case, if "size" is 0 then the length is calculated
5421 using "strlen" (so in this case the content cannot contain embedded
5422 ASCII NULs).
5423 NB. Owing to a bug, writing content containing ASCII NUL characters
5425 does not work, even if the length is specified.
5426 Because of the message protocol, there is a transfer limit of
5428 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5429 guestfs(3).
5430 This function is deprecated. In new code, use the "write" call
5432 instead.
5433 Deprecated functions will not be removed from the API, but the fact
5435 that they are deprecated indicates that there are problems with
5436 correct use of these functions.
5437 $g->xfs_admin ($device [, extunwritten => $extunwritten] [, imgfile =>
5439 $imgfile] [, v2log => $v2log] [, projid32bit => $projid32bit] [,
5440 lazycounter => $lazycounter] [, label => $label] [, uuid => $uuid]);
5441 Change the parameters of the XFS filesystem on "device".
5442 Devices that are mounted cannot be modified. Administrators must
5444 unmount filesystems before this call can modify parameters.
5445 Some of the parameters of a mounted filesystem can be examined and
5447 modified using the "$g->xfs_info" and "$g->xfs_growfs" calls.
5448 $g->xfs_growfs ($path [, datasec => $datasec] [, logsec => $logsec] [,
5450 rtsec => $rtsec] [, datasize => $datasize] [, logsize => $logsize] [,
5451 rtsize => $rtsize] [, rtextsize => $rtextsize] [, maxpct => $maxpct]);
5452 Grow the XFS filesystem mounted at "path".
5453 The returned struct contains geometry information. Missing fields
5455 are returned as "-1" (for numeric fields) or empty string.
5456 %info = $g->xfs_info ($pathordevice);
5458 "pathordevice" is a mounted XFS filesystem or a device containing
5459 an XFS filesystem. This command returns the geometry of the
5460 filesystem.
5461 The returned struct contains geometry information. Missing fields
5463 are returned as "-1" (for numeric fields) or empty string.
5464 $status = $g->xfs_repair ($device [, forcelogzero => $forcelogzero] [,
5466 nomodify => $nomodify] [, noprefetch => $noprefetch] [, forcegeometry
5467 => $forcegeometry] [, maxmem => $maxmem] [, ihashsize => $ihashsize] [,
5468 bhashsize => $bhashsize] [, agstride => $agstride] [, logdev =>
5469 $logdev] [, rtdev => $rtdev]);
5470 Repair corrupt or damaged XFS filesystem on "device".
5471 The filesystem is specified using the "device" argument which
5473 should be the device name of the disk partition or volume
5474 containing the filesystem. If given the name of a block device,
5475 "xfs_repair" will attempt to find the raw device associated with
5476 the specified block device and will use the raw device instead.
5477 Regardless, the filesystem to be repaired must be unmounted,
5479 otherwise, the resulting filesystem may be inconsistent or corrupt.
5480 The returned status indicates whether filesystem corruption was
5482 detected (returns 1) or was not detected (returns 0).
5483 @lines = $g->zegrep ($regex, $path);
5485 This calls the external "zegrep" program and returns the matching
5486 lines.
5487 Because of the message protocol, there is a transfer limit of
5489 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5490 guestfs(3).
5491 This function is deprecated. In new code, use the "grep" call
5493 instead.
5494 Deprecated functions will not be removed from the API, but the fact
5496 that they are deprecated indicates that there are problems with
5497 correct use of these functions.
5498 @lines = $g->zegrepi ($regex, $path);
5500 This calls the external "zegrep -i" program and returns the
5501 matching lines.
5502 Because of the message protocol, there is a transfer limit of
5504 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5505 guestfs(3).
5506 This function is deprecated. In new code, use the "grep" call
5508 instead.
5509 Deprecated functions will not be removed from the API, but the fact
5511 that they are deprecated indicates that there are problems with
5512 correct use of these functions.
5513 $g->zero ($device);
5515 This command writes zeroes over the first few blocks of "device".
5516 How many blocks are zeroed isn't specified (but it's not enough to
5518 securely wipe the device). It should be sufficient to remove any
5519 partition tables, filesystem superblocks and so on.
5520 If blocks are already zero, then this command avoids writing
5522 zeroes. This prevents the underlying device from becoming non-
5523 sparse or growing unnecessarily.
5524 See also: "$g->zero_device", "$g->scrub_device",
5526 "$g->is_zero_device"
5527 $g->zero_device ($device);
5529 This command writes zeroes over the entire "device". Compare with
5530 "$g->zero" which just zeroes the first few blocks of a device.
5531 If blocks are already zero, then this command avoids writing
5533 zeroes. This prevents the underlying device from becoming non-
5534 sparse or growing unnecessarily.
5535 $g->zero_free_space ($directory);
5537 Zero the free space in the filesystem mounted on "directory". The
5538 filesystem must be mounted read-write.
5539 The filesystem contents are not affected, but any free space in the
5541 filesystem is freed.
5542 Free space is not "trimmed". You may want to call "$g->fstrim"
5544 either as an alternative to this, or after calling this, depending
5545 on your requirements.
5546 $g->zerofree ($device);
5548 This runs the zerofree program on "device". This program claims to
5549 zero unused inodes and disk blocks on an ext2/3 filesystem, thus
5550 making it possible to compress the filesystem more effectively.
5551 You should not run this program if the filesystem is mounted.
5553 It is possible that using this program can damage the filesystem or
5555 data on the filesystem.
5556 @lines = $g->zfgrep ($pattern, $path);
5558 This calls the external "zfgrep" program and returns the matching
5559 lines.
5560 Because of the message protocol, there is a transfer limit of
5562 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5563 guestfs(3).
5564 This function is deprecated. In new code, use the "grep" call
5566 instead.
5567 Deprecated functions will not be removed from the API, but the fact
5569 that they are deprecated indicates that there are problems with
5570 correct use of these functions.
5571 @lines = $g->zfgrepi ($pattern, $path);
5573 This calls the external "zfgrep -i" program and returns the
5574 matching lines.
5575 Because of the message protocol, there is a transfer limit of
5577 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5578 guestfs(3).
5579 This function is deprecated. In new code, use the "grep" call
5581 instead.
5582 Deprecated functions will not be removed from the API, but the fact
5584 that they are deprecated indicates that there are problems with
5585 correct use of these functions.
5586 $description = $g->zfile ($meth, $path);
5588 This command runs "file" after first decompressing "path" using
5589 "method".
5590 "method" must be one of "gzip", "compress" or "bzip2".
5592 Since 1.0.63, use "$g->file" instead which can now process
5594 compressed files.
5595 This function is deprecated. In new code, use the "file" call
5597 instead.
5598 Deprecated functions will not be removed from the API, but the fact
5600 that they are deprecated indicates that there are problems with
5601 correct use of these functions.
5602 @lines = $g->zgrep ($regex, $path);
5604 This calls the external "zgrep" program and returns the matching
5605 lines.
5606 Because of the message protocol, there is a transfer limit of
5608 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5609 guestfs(3).
5610 This function is deprecated. In new code, use the "grep" call
5612 instead.
5613 Deprecated functions will not be removed from the API, but the fact
5615 that they are deprecated indicates that there are problems with
5616 correct use of these functions.
5617 @lines = $g->zgrepi ($regex, $path);
5619 This calls the external "zgrep -i" program and returns the matching
5620 lines.
5621 Because of the message protocol, there is a transfer limit of
5623 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5624 guestfs(3).
5625 This function is deprecated. In new code, use the "grep" call
5627 instead.
5628 Deprecated functions will not be removed from the API, but the fact
5630 that they are deprecated indicates that there are problems with
5631 correct use of these functions.
5632
5634 From time to time we add new libguestfs APIs. Also some libguestfs
5635 APIs won't be available in all builds of libguestfs (the Fedora build
5636 is full-featured, but other builds may disable features). How do you
5637 test whether the APIs that your Perl program needs are available in the
5638 version of "Sys::Guestfs" that you are using?
5639 To test if a particular function is available in the "Sys::Guestfs"
5641 class, use the ordinary Perl UNIVERSAL method "can(METHOD)" (see
5642 perlobj(1)). For example:
5643 use Sys::Guestfs;
5645 if (defined (Sys::Guestfs->can ("set_verbose"))) {
5646 print "\$g->set_verbose is available\n";
5647 }
5648 Perl does not offer a way to list the arguments of a method, and from
5650 time to time we may add extra arguments to calls that take optional
5651 arguments. For this reason, we provide a global hash variable
5652 %guestfs_introspection which contains the arguments and their types for
5653 each libguestfs method. The keys of this hash are the method names,
5654 and the values are an hashref containing useful introspection
5655 information about the method (further fields may be added to this in
5656 future).
5657 use Sys::Guestfs;
5659 $Sys::Guestfs::guestfs_introspection{mkfs}
5660 => {
5661 ret => 'void', # return type
5662 args => [ # required arguments
5663 [ 'fstype', 'string', 0 ],
5664 [ 'device', 'string(device)', 1 ],
5665 ],
5666 optargs => { # optional arguments
5667 blocksize => [ 'blocksize', 'int', 0 ],
5668 features => [ 'features', 'string', 1 ],
5669 inode => [ 'inode', 'int', 2 ],
5670 sectorsize => [ 'sectorsize', 'int', 3 ],
5671 },
5672 name => "mkfs",
5673 description => "make a filesystem",
5674 }
5675 To test if particular features are supported by the current build, use
5677 the "available" method like the example below. Note that the appliance
5678 must be launched first.
5679 $g->available ( ["augeas"] );
5681 Since the "available" method croaks if the feature is not supported,
5683 you might also want to wrap this in an eval and return a boolean. In
5684 fact this has already been done for you: use "feature_available" in
5685 Sys::Guestfs::Lib(3).
5686 For further discussion on this topic, refer to "AVAILABILITY" in
5688 guestfs(3).
5689
5691 The handle returned from "new" is a hash reference. The hash normally
5692 contains some elements:
5693 {
5695 _g => [private data used by libguestfs],
5696 _flags => [flags provided when creating the handle]
5697 }
5698 Callers can add other elements to this hash to store data for their own
5700 purposes. The data lasts for the lifetime of the handle.
5701 Any fields whose names begin with an underscore are reserved for
5703 private use by libguestfs. We may add more in future.
5704 It is recommended that callers prefix the name of their field(s) with
5706 some unique string, to avoid conflicts with other users.
5707
5709 Copyright (C) 2009-2017 Red Hat Inc.
5710
5712 Please see the file COPYING.LIB for the full license.
5713
5715 guestfs(3), guestfish(1), <http://libguestfs.org>,
5716 Sys::Guestfs::Lib(3).
5717perl v5.10.1 2017-03-23 Sys::Guestfs(3)