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
39 All errors turn into calls to "croak" (see Carp(3)).
40 The error string from libguestfs is directly available from $@. Use
42 the "last_errno" method if you want to get the errno.
43
45 $g = Sys::Guestfs->new ([environment => 0,] [close_on_exit => 0]);
46 Create a new guestfs handle.
47 If the optional argument "environment" is false, then the
49 "GUESTFS_CREATE_NO_ENVIRONMENT" flag is set.
50 If the optional argument "close_on_exit" is false, then the
52 "GUESTFS_CREATE_NO_CLOSE_ON_EXIT" flag is set.
53 $g->close ();
55 Explicitly close the guestfs handle.
56 Note: You should not usually call this function. The handle will
58 be closed implicitly when its reference count goes to zero (eg.
59 when it goes out of scope or the program ends). This call is only
60 required in some exceptional cases, such as where the program may
61 contain cached references to the handle 'somewhere' and you really
62 have to have the close happen right away. After calling "close"
63 the program must not call any method (including "close") on the
64 handle (but the implicit call to "DESTROY" that happens when the
65 final reference is cleaned up is OK).
66 $Sys::Guestfs::EVENT_CLOSE
68 See "GUESTFS_EVENT_CLOSE" in guestfs(3).
69 $Sys::Guestfs::EVENT_SUBPROCESS_QUIT
71 See "GUESTFS_EVENT_SUBPROCESS_QUIT" in guestfs(3).
72 $Sys::Guestfs::EVENT_LAUNCH_DONE
74 See "GUESTFS_EVENT_LAUNCH_DONE" in guestfs(3).
75 $Sys::Guestfs::EVENT_PROGRESS
77 See "GUESTFS_EVENT_PROGRESS" in guestfs(3).
78 $Sys::Guestfs::EVENT_APPLIANCE
80 See "GUESTFS_EVENT_APPLIANCE" in guestfs(3).
81 $Sys::Guestfs::EVENT_LIBRARY
83 See "GUESTFS_EVENT_LIBRARY" in guestfs(3).
84 $Sys::Guestfs::EVENT_TRACE
86 See "GUESTFS_EVENT_TRACE" in guestfs(3).
87 $Sys::Guestfs::EVENT_ENTER
89 See "GUESTFS_EVENT_ENTER" in guestfs(3).
90 $Sys::Guestfs::EVENT_LIBVIRT_AUTH
92 See "GUESTFS_EVENT_LIBVIRT_AUTH" in guestfs(3).
93 $Sys::Guestfs::EVENT_WARNING
95 See "GUESTFS_EVENT_WARNING" 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 $str = Sys::Guestfs::event_to_string ($events);
135 $events is either a single event or a bitmask of events. This
136 returns a printable string, useful for debugging.
137 Note that this is a class function, not a method.
139 $errnum = $g->last_errno ();
141 This returns the last error number (errno) that happened on the
142 handle $g.
143 If successful, an errno integer not equal to zero is returned.
145 If no error number is available, this returns 0. See
147 "guestfs_last_errno" in guestfs(3) for more details of why this can
148 happen.
149 You can use the standard Perl module Errno(3) to compare the
151 numeric error returned from this call with symbolic errnos:
152 $g->mkdir ("/foo");
154 if ($g->last_errno() == Errno::EEXIST()) {
155 # mkdir failed because the directory exists already.
156 }
157 $g->acl_delete_def_file ($dir);
159 This function deletes the default POSIX Access Control List (ACL)
160 attached to directory "dir".
161 This function depends on the feature "acl". See also
163 "$g->feature-available".
164 $acl = $g->acl_get_file ($path, $acltype);
166 This function returns the POSIX Access Control List (ACL) attached
167 to "path". The ACL is returned in "long text form" (see acl(5)).
168 The "acltype" parameter may be:
170 "access"
172 Return the ordinary (access) ACL for any file, directory or
173 other filesystem object.
174 "default"
176 Return the default ACL. Normally this only makes sense if
177 "path" is a directory.
178 This function depends on the feature "acl". See also
180 "$g->feature-available".
181 $g->acl_set_file ($path, $acltype, $acl);
183 This function sets the POSIX Access Control List (ACL) attached to
184 "path".
185 The "acltype" parameter may be:
187 "access"
189 Set the ordinary (access) ACL for any file, directory or other
190 filesystem object.
191 "default"
193 Set the default ACL. Normally this only makes sense if "path"
194 is a directory.
195 The "acl" parameter is the new ACL in either "long text form" or
197 "short text form" (see acl(5)). The new ACL completely replaces
198 any previous ACL on the file. The ACL must contain the full Unix
199 permissions (eg. "u::rwx,g::rx,o::rx").
200 If you are specifying individual users or groups, then the mask
202 field is also required (eg. "m::rwx"), followed by the "u:ID:..."
203 and/or "g:ID:..." field(s). A full ACL string might therefore look
204 like this:
205 u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx
207 \ Unix permissions / \mask/ \ ACL /
208 You should use numeric UIDs and GIDs. To map usernames and
210 groupnames to the correct numeric ID in the context of the guest,
211 use the Augeas functions (see "$g->aug_init").
212 This function depends on the feature "acl". See also
214 "$g->feature-available".
215 $g->add_cdrom ($filename);
217 This function adds a virtual CD-ROM disk image to the guest.
218 The image is added as read-only drive, so this function is
220 equivalent of "$g->add_drive_ro".
221 This function is deprecated. In new code, use the "add_drive_ro"
223 call instead.
224 Deprecated functions will not be removed from the API, but the fact
226 that they are deprecated indicates that there are problems with
227 correct use of these functions.
228 $nrdisks = $g->add_domain ($dom [, libvirturi => $libvirturi] [,
230 readonly => $readonly] [, iface => $iface] [, live => $live] [,
231 allowuuid => $allowuuid] [, readonlydisk => $readonlydisk] [, cachemode
232 => $cachemode] [, discard => $discard] [, copyonread => $copyonread]);
233 This function adds the disk(s) attached to the named libvirt domain
234 "dom". It works by connecting to libvirt, requesting the domain
235 and domain XML from libvirt, parsing it for disks, and calling
236 "$g->add_drive_opts" on each one.
237 The number of disks added is returned. This operation is atomic:
239 if an error is returned, then no disks are added.
240 This function does some minimal checks to make sure the libvirt
242 domain is not running (unless "readonly" is true). In a future
243 version we will try to acquire the libvirt lock on each disk.
244 Disks must be accessible locally. This often means that adding
246 disks from a remote libvirt connection (see
247 <http://libvirt.org/remote.html>) will fail unless those disks are
248 accessible via the same device path locally too.
249 The optional "libvirturi" parameter sets the libvirt URI (see
251 <http://libvirt.org/uri.html>). If this is not set then we connect
252 to the default libvirt URI (or one set through an environment
253 variable, see the libvirt documentation for full details).
254 The optional "live" flag controls whether this call will try to
256 connect to a running virtual machine "guestfsd" process if it sees
257 a suitable <channel> element in the libvirt XML definition. The
258 default (if the flag is omitted) is never to try. See "ATTACHING
259 TO RUNNING DAEMONS" in guestfs(3) for more information.
260 If the "allowuuid" flag is true (default is false) then a UUID may
262 be passed instead of the domain name. The "dom" string is treated
263 as a UUID first and looked up, and if that lookup fails then we
264 treat "dom" as a name as usual.
265 The optional "readonlydisk" parameter controls what we do for disks
267 which are marked <readonly/> in the libvirt XML. Possible values
268 are:
269 readonlydisk = "error"
271 If "readonly" is false:
272 The whole call is aborted with an error if any disk with the
274 <readonly/> flag is found.
275 If "readonly" is true:
277 Disks with the <readonly/> flag are added read-only.
279 readonlydisk = "read"
281 If "readonly" is false:
282 Disks with the <readonly/> flag are added read-only. Other
284 disks are added read/write.
285 If "readonly" is true:
287 Disks with the <readonly/> flag are added read-only.
289 readonlydisk = "write" (default)
291 If "readonly" is false:
292 Disks with the <readonly/> flag are added read/write.
294 If "readonly" is true:
296 Disks with the <readonly/> flag are added read-only.
298 readonlydisk = "ignore"
300 If "readonly" is true or false:
301 Disks with the <readonly/> flag are skipped.
303 The other optional parameters are passed directly through to
305 "$g->add_drive_opts".
306 $g->add_drive ($filename [, readonly => $readonly] [, format =>
308 $format] [, iface => $iface] [, name => $name] [, label => $label] [,
309 protocol => $protocol] [, server => $server] [, username => $username]
310 [, secret => $secret] [, cachemode => $cachemode] [, discard =>
311 $discard] [, copyonread => $copyonread]);
312 This function adds a disk image called filename to the handle.
313 filename may be a regular host file or a host device.
314 When this function is called before "$g->launch" (the usual case)
316 then the first time you call this function, the disk appears in the
317 API as /dev/sda, the second time as /dev/sdb, and so on.
318 In libguestfs X 1.20 you can also call this function after launch
320 (with some restrictions). This is called "hotplugging". When
321 hotplugging, you must specify a "label" so that the new disk gets a
322 predictable name. For more information see "HOTPLUGGING" in
323 guestfs(3).
324 You don't necessarily need to be root when using libguestfs.
326 However you obviously do need sufficient permissions to access the
327 filename for whatever operations you want to perform (ie. read
328 access if you just want to read the image or write access if you
329 want to modify the image).
330 This call checks that filename exists.
332 filename may be the special string "/dev/null". See "NULL DISKS"
334 in guestfs(3).
335 The optional arguments are:
337 "readonly"
339 If true then the image is treated as read-only. Writes are
340 still allowed, but they are stored in a temporary snapshot
341 overlay which is discarded at the end. The disk that you add
342 is not modified.
343 "format"
345 This forces the image format. If you omit this (or use
346 "$g->add_drive" or "$g->add_drive_ro") then the format is
347 automatically detected. Possible formats include "raw" and
348 "qcow2".
349 Automatic detection of the format opens you up to a potential
351 security hole when dealing with untrusted raw-format images.
352 See CVE-2010-3851 and RHBZ#642934. Specifying the format
353 closes this security hole.
354 "iface"
356 This rarely-used option lets you emulate the behaviour of the
357 deprecated "$g->add_drive_with_if" call (q.v.)
358 "name"
360 The name the drive had in the original guest, e.g. /dev/sdb.
361 This is used as a hint to the guest inspection process if it is
362 available.
363 "label"
365 Give the disk a label. The label should be a unique, short
366 string using only ASCII characters "[a-zA-Z]". As well as its
367 usual name in the API (such as /dev/sda), the drive will also
368 be named /dev/disk/guestfs/label.
369 See "DISK LABELS" in guestfs(3).
371 "protocol"
373 The optional protocol argument can be used to select an
374 alternate source protocol.
375 See also: "REMOTE STORAGE" in guestfs(3).
377 "protocol = "file""
379 filename is interpreted as a local file or device. This is
380 the default if the optional protocol parameter is omitted.
381 "protocol = "ftp"|"ftps"|"http"|"https"|"tftp""
383 Connect to a remote FTP, HTTP or TFTP server. The "server"
384 parameter must also be supplied - see below.
385 See also: "FTP, HTTP AND TFTP" in guestfs(3)
387 "protocol = "gluster""
389 Connect to the GlusterFS server. The "server" parameter
390 must also be supplied - see below.
391 See also: "GLUSTER" in guestfs(3)
393 "protocol = "iscsi""
395 Connect to the iSCSI server. The "server" parameter must
396 also be supplied - see below. The "username" parameter may
397 be supplied. See below. The "secret" parameter may be
398 supplied. See below.
399 See also: "ISCSI" in guestfs(3).
401 "protocol = "nbd""
403 Connect to the Network Block Device server. The "server"
404 parameter must also be supplied - see below.
405 See also: "NETWORK BLOCK DEVICE" in guestfs(3).
407 "protocol = "rbd""
409 Connect to the Ceph (librbd/RBD) server. The "server"
410 parameter must also be supplied - see below. The
411 "username" parameter may be supplied. See below. The
412 "secret" parameter may be supplied. See below.
413 See also: "CEPH" in guestfs(3).
415 "protocol = "sheepdog""
417 Connect to the Sheepdog server. The "server" parameter may
418 also be supplied - see below.
419 See also: "SHEEPDOG" in guestfs(3).
421 "protocol = "ssh""
423 Connect to the Secure Shell (ssh) server.
424 The "server" parameter must be supplied. The "username"
426 parameter may be supplied. See below.
427 See also: "SSH" in guestfs(3).
429 "server"
431 For protocols which require access to a remote server, this is
432 a list of server(s).
433 Protocol Number of servers required
435 -------- --------------------------
436 file List must be empty or param not used at all
437 ftp|ftps|http|https|tftp Exactly one
438 gluster Exactly one
439 iscsi Exactly one
440 nbd Exactly one
441 rbd Zero or more
442 sheepdog Zero or more
443 ssh Exactly one
444 Each list element is a string specifying a server. The string
446 must be in one of the following formats:
447 hostname
449 hostname:port
450 tcp:hostname
451 tcp:hostname:port
452 unix:/path/to/socket
453 If the port number is omitted, then the standard port number
455 for the protocol is used (see /etc/services).
456 "username"
458 For the "ftp", "ftps", "http", "https", "iscsi", "rbd", "ssh"
459 and "tftp" protocols, this specifies the remote username.
460 If not given, then the local username is used for "ssh", and no
462 authentication is attempted for ceph. But note this sometimes
463 may give unexpected results, for example if using the libvirt
464 backend and if the libvirt backend is configured to start the
465 qemu appliance as a special user such as "qemu.qemu". If in
466 doubt, specify the remote username you want.
467 "secret"
469 For the "rbd" protocol only, this specifies the XsecretX to use
470 when connecting to the remote device. It must be base64
471 encoded.
472 If not given, then a secret matching the given username will be
474 looked up in the default keychain locations, or if no username
475 is given, then no authentication will be used.
476 "cachemode"
478 Choose whether or not libguestfs will obey sync operations
479 (safe but slow) or not (unsafe but fast). The possible values
480 for this string are:
481 "cachemode = "writeback""
483 This is the default.
484 Write operations in the API do not return until a write(2)
486 call has completed in the host [but note this does not
487 imply that anything gets written to disk].
488 Sync operations in the API, including implicit syncs caused
490 by filesystem journalling, will not return until an
491 fdatasync(2) call has completed in the host, indicating
492 that data has been committed to disk.
493 "cachemode = "unsafe""
495 In this mode, there are no guarantees. Libguestfs may
496 cache anything and ignore sync requests. This is suitable
497 only for scratch or temporary disks.
498 "discard"
500 Enable or disable discard (a.k.a. trim or unmap) support on
501 this drive. If enabled, operations such as "$g->fstrim" will
502 be able to discard / make thin / punch holes in the underlying
503 host file or device.
504 Possible discard settings are:
506 "discard = "disable""
508 Disable discard support. This is the default.
509 "discard = "enable""
511 Enable discard support. Fail if discard is not possible.
512 "discard = "besteffort""
514 Enable discard support if possible, but don't fail if it is
515 not supported.
516 Since not all backends and not all underlying systems
518 support discard, this is a good choice if you want to use
519 discard if possible, but don't mind if it doesn't work.
520 "copyonread"
522 The boolean parameter "copyonread" enables copy-on-read
523 support. This only affects disk formats which have backing
524 files, and causes reads to be stored in the overlay layer,
525 speeding up multiple reads of the same area of disk.
526 The default is false.
528 $g->add_drive_opts ($filename [, readonly => $readonly] [, format =>
530 $format] [, iface => $iface] [, name => $name] [, label => $label] [,
531 protocol => $protocol] [, server => $server] [, username => $username]
532 [, secret => $secret] [, cachemode => $cachemode] [, discard =>
533 $discard] [, copyonread => $copyonread]);
534 This is an alias of "add_drive".
535 $g->add_drive_ro ($filename);
537 This function is the equivalent of calling "$g->add_drive_opts"
538 with the optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set
539 to 1, so the disk is added read-only, with the format being
540 detected automatically.
541 $g->add_drive_ro_with_if ($filename, $iface);
543 This is the same as "$g->add_drive_ro" but it allows you to specify
544 the QEMU interface emulation to use at run time.
545 This function is deprecated. In new code, use the "add_drive" call
547 instead.
548 Deprecated functions will not be removed from the API, but the fact
550 that they are deprecated indicates that there are problems with
551 correct use of these functions.
552 $g->add_drive_scratch ($size [, name => $name] [, label => $label]);
554 This command adds a temporary scratch drive to the handle. The
555 "size" parameter is the virtual size (in bytes). The scratch drive
556 is blank initially (all reads return zeroes until you start writing
557 to it). The drive is deleted when the handle is closed.
558 The optional arguments "name" and "label" are passed through to
560 "$g->add_drive".
561 $g->add_drive_with_if ($filename, $iface);
563 This is the same as "$g->add_drive" but it allows you to specify
564 the QEMU interface emulation to use at run time.
565 This function is deprecated. In new code, use the "add_drive" call
567 instead.
568 Deprecated functions will not be removed from the API, but the fact
570 that they are deprecated indicates that there are problems with
571 correct use of these functions.
572 $nrdisks = $g->add_libvirt_dom ($dom [, readonly => $readonly] [, iface
574 => $iface] [, live => $live] [, readonlydisk => $readonlydisk] [,
575 cachemode => $cachemode] [, discard => $discard] [, copyonread =>
576 $copyonread]);
577 This function adds the disk(s) attached to the libvirt domain
578 "dom". It works by requesting the domain XML from libvirt, parsing
579 it for disks, and calling "$g->add_drive_opts" on each one.
580 In the C API we declare "void *dom", but really it has type
582 "virDomainPtr dom". This is so we don't need <libvirt.h>.
583 The number of disks added is returned. This operation is atomic:
585 if an error is returned, then no disks are added.
586 This function does some minimal checks to make sure the libvirt
588 domain is not running (unless "readonly" is true). In a future
589 version we will try to acquire the libvirt lock on each disk.
590 Disks must be accessible locally. This often means that adding
592 disks from a remote libvirt connection (see
593 <http://libvirt.org/remote.html>) will fail unless those disks are
594 accessible via the same device path locally too.
595 The optional "live" flag controls whether this call will try to
597 connect to a running virtual machine "guestfsd" process if it sees
598 a suitable <channel> element in the libvirt XML definition. The
599 default (if the flag is omitted) is never to try. See "ATTACHING
600 TO RUNNING DAEMONS" in guestfs(3) for more information.
601 The optional "readonlydisk" parameter controls what we do for disks
603 which are marked <readonly/> in the libvirt XML. See
604 "$g->add_domain" for possible values.
605 The other optional parameters are passed directly through to
607 "$g->add_drive_opts".
608 $g->aug_clear ($augpath);
610 Set the value associated with "path" to "NULL". This is the same
611 as the augtool(1) "clear" command.
612 $g->aug_close ();
614 Close the current Augeas handle and free up any resources used by
615 it. After calling this, you have to call "$g->aug_init" again
616 before you can use any other Augeas functions.
617 %nrnodescreated = $g->aug_defnode ($name, $expr, $val);
619 Defines a variable "name" whose value is the result of evaluating
620 "expr".
621 If "expr" evaluates to an empty nodeset, a node is created,
623 equivalent to calling "$g->aug_set" "expr", "value". "name" will
624 be the nodeset containing that single node.
625 On success this returns a pair containing the number of nodes in
627 the nodeset, and a boolean flag if a node was created.
628 $nrnodes = $g->aug_defvar ($name, $expr);
630 Defines an Augeas variable "name" whose value is the result of
631 evaluating "expr". If "expr" is NULL, then "name" is undefined.
632 On success this returns the number of nodes in "expr", or 0 if
634 "expr" evaluates to something which is not a nodeset.
635 $val = $g->aug_get ($augpath);
637 Look up the value associated with "path". If "path" matches
638 exactly one node, the "value" is returned.
639 $g->aug_init ($root, $flags);
641 Create a new Augeas handle for editing configuration files. If
642 there was any previous Augeas handle associated with this guestfs
643 session, then it is closed.
644 You must call this before using any other "$g->aug_*" commands.
646 "root" is the filesystem root. "root" must not be NULL, use /
648 instead.
649 The flags are the same as the flags defined in <augeas.h>, the
651 logical or of the following integers:
652 "AUG_SAVE_BACKUP" = 1
654 Keep the original file with a ".augsave" extension.
655 "AUG_SAVE_NEWFILE" = 2
657 Save changes into a file with extension ".augnew", and do not
658 overwrite original. Overrides "AUG_SAVE_BACKUP".
659 "AUG_TYPE_CHECK" = 4
661 Typecheck lenses.
662 This option is only useful when debugging Augeas lenses. Use
664 of this option may require additional memory for the libguestfs
665 appliance. You may need to set the "LIBGUESTFS_MEMSIZE"
666 environment variable or call "$g->set_memsize".
667 "AUG_NO_STDINC" = 8
669 Do not use standard load path for modules.
670 "AUG_SAVE_NOOP" = 16
672 Make save a no-op, just record what would have been changed.
673 "AUG_NO_LOAD" = 32
675 Do not load the tree in "$g->aug_init".
676 To close the handle, you can call "$g->aug_close".
678 To find out more about Augeas, see <http://augeas.net/>.
680 $g->aug_insert ($augpath, $label, $before);
682 Create a new sibling "label" for "path", inserting it into the tree
683 before or after "path" (depending on the boolean flag "before").
684 "path" must match exactly one existing node in the tree, and
686 "label" must be a label, ie. not contain /, "*" or end with a
687 bracketed index "[N]".
688 $label = $g->aug_label ($augpath);
690 The label (name of the last element) of the Augeas path expression
691 "augpath" is returned. "augpath" must match exactly one node, else
692 this function returns an error.
693 $g->aug_load ();
695 Load files into the tree.
696 See "aug_load" in the Augeas documentation for the full gory
698 details.
699 @matches = $g->aug_ls ($augpath);
701 This is just a shortcut for listing "$g->aug_match" "path/*" and
702 sorting the resulting nodes into alphabetical order.
703 @matches = $g->aug_match ($augpath);
705 Returns a list of paths which match the path expression "path".
706 The returned paths are sufficiently qualified so that they match
707 exactly one node in the current tree.
708 $g->aug_mv ($src, $dest);
710 Move the node "src" to "dest". "src" must match exactly one node.
711 "dest" is overwritten if it exists.
712 $nrnodes = $g->aug_rm ($augpath);
714 Remove "path" and all of its children.
715 On success this returns the number of entries which were removed.
717 $g->aug_save ();
719 This writes all pending changes to disk.
720 The flags which were passed to "$g->aug_init" affect exactly how
722 files are saved.
723 $g->aug_set ($augpath, $val);
725 Set the value associated with "path" to "val".
726 In the Augeas API, it is possible to clear a node by setting the
728 value to NULL. Due to an oversight in the libguestfs API you
729 cannot do that with this call. Instead you must use the
730 "$g->aug_clear" call.
731 $nodes = $g->aug_setm ($base, $sub, $val);
733 Change multiple Augeas nodes in a single operation. "base" is an
734 expression matching multiple nodes. "sub" is a path expression
735 relative to "base". All nodes matching "base" are found, and then
736 for each node, "sub" is changed to "val". "sub" may also be "NULL"
737 in which case the "base" nodes are modified.
738 This returns the number of nodes modified.
740 $g->aug_transform ($lens, $file [, remove => $remove]);
742 Add an Augeas transformation for the specified "lens" so it can
743 handle "file".
744 If "remove" is true ("false" by default), then the transformation
746 is removed.
747 $g->available (\@groups);
749 This command is used to check the availability of some groups of
750 functionality in the appliance, which not all builds of the
751 libguestfs appliance will be able to provide.
752 The libguestfs groups, and the functions that those groups
754 correspond to, are listed in "AVAILABILITY" in guestfs(3). You can
755 also fetch this list at runtime by calling
756 "$g->available_all_groups".
757 The argument "groups" is a list of group names, eg: "["inotify",
759 "augeas"]" would check for the availability of the Linux inotify
760 functions and Augeas (configuration file editing) functions.
761 The command returns no error if all requested groups are available.
763 It fails with an error if one or more of the requested groups is
765 unavailable in the appliance.
766 If an unknown group name is included in the list of groups then an
768 error is always returned.
769 Notes:
771 · "$g->feature_available" is the same as this call, but with a
773 slightly simpler to use API: that call returns a boolean
774 true/false instead of throwing an error.
775 · You must call "$g->launch" before calling this function.
777 The reason is because we don't know what groups are supported
779 by the appliance/daemon until it is running and can be queried.
780 · If a group of functions is available, this does not necessarily
782 mean that they will work. You still have to check for errors
783 when calling individual API functions even if they are
784 available.
785 · It is usually the job of distro packagers to build complete
787 functionality into the libguestfs appliance. Upstream
788 libguestfs, if built from source with all requirements
789 satisfied, will support everything.
790 · This call was added in version 1.0.80. In previous versions of
792 libguestfs all you could do would be to speculatively execute a
793 command to find out if the daemon implemented it. See also
794 "$g->version".
795 See also "$g->filesystem_available".
797 @groups = $g->available_all_groups ();
799 This command returns a list of all optional groups that this daemon
800 knows about. Note this returns both supported and unsupported
801 groups. To find out which ones the daemon can actually support you
802 have to call "$g->available" / "$g->feature_available" on each
803 member of the returned list.
804 See also "$g->available", "$g->feature_available" and
806 "AVAILABILITY" in guestfs(3).
807 $g->base64_in ($base64file, $filename);
809 This command uploads base64-encoded data from "base64file" to
810 filename.
811 $g->base64_out ($filename, $base64file);
813 This command downloads the contents of filename, writing it out to
814 local file "base64file" encoded as base64.
815 $g->blkdiscard ($device);
817 This discards all blocks on the block device "device", giving the
818 free space back to the host.
819 This operation requires support in libguestfs, the host filesystem,
821 qemu and the host kernel. If this support isn't present it may
822 give an error or even appear to run but do nothing. You must also
823 set the "discard" attribute on the underlying drive (see
824 "$g->add_drive_opts").
825 This function depends on the feature "blkdiscard". See also
827 "$g->feature-available".
828 $zeroes = $g->blkdiscardzeroes ($device);
830 This call returns true if blocks on "device" that have been
831 discarded by a call to "$g->blkdiscard" are returned as blocks of
832 zero bytes when read the next time.
833 If it returns false, then it may be that discarded blocks are read
835 as stale or random data.
836 This function depends on the feature "blkdiscardzeroes". See also
838 "$g->feature-available".
839 %info = $g->blkid ($device);
841 This command returns block device attributes for "device". The
842 following fields are usually present in the returned hash. Other
843 fields may also be present.
844 "UUID"
846 The uuid of this device.
847 "LABEL"
849 The label of this device.
850 "VERSION"
852 The version of blkid command.
853 "TYPE"
855 The filesystem type or RAID of this device.
856 "USAGE"
858 The usage of this device, for example "filesystem" or "raid".
859 $g->blockdev_flushbufs ($device);
861 This tells the kernel to flush internal buffers associated with
862 "device".
863 This uses the blockdev(8) command.
865 $blocksize = $g->blockdev_getbsz ($device);
867 This returns the block size of a device.
868 Note: this is different from both size in blocks and filesystem
870 block size. Also this setting is not really used by anything. You
871 should probably not use it for anything. Filesystems have their
872 own idea about what block size to choose.
873 This uses the blockdev(8) command.
875 $ro = $g->blockdev_getro ($device);
877 Returns a boolean indicating if the block device is read-only (true
878 if read-only, false if not).
879 This uses the blockdev(8) command.
881 $sizeinbytes = $g->blockdev_getsize64 ($device);
883 This returns the size of the device in bytes.
884 See also "$g->blockdev_getsz".
886 This uses the blockdev(8) command.
888 $sectorsize = $g->blockdev_getss ($device);
890 This returns the size of sectors on a block device. Usually 512,
891 but can be larger for modern devices.
892 (Note, this is not the size in sectors, use "$g->blockdev_getsz"
894 for that).
895 This uses the blockdev(8) command.
897 $sizeinsectors = $g->blockdev_getsz ($device);
899 This returns the size of the device in units of 512-byte sectors
900 (even if the sectorsize isn't 512 bytes ... weird).
901 See also "$g->blockdev_getss" for the real sector size of the
903 device, and "$g->blockdev_getsize64" for the more useful size in
904 bytes.
905 This uses the blockdev(8) command.
907 $g->blockdev_rereadpt ($device);
909 Reread the partition table on "device".
910 This uses the blockdev(8) command.
912 $g->blockdev_setbsz ($device, $blocksize);
914 This call does nothing and has never done anything because of a bug
915 in blockdev. Do not use it.
916 If you need to set the filesystem block size, use the "blocksize"
918 option of "$g->mkfs".
919 This function is deprecated. There is no replacement. Consult the
921 API documentation in guestfs(3) for further information.
922 Deprecated functions will not be removed from the API, but the fact
924 that they are deprecated indicates that there are problems with
925 correct use of these functions.
926 $g->blockdev_setra ($device, $sectors);
928 Set readahead (in 512-byte sectors) for the device.
929 This uses the blockdev(8) command.
931 $g->blockdev_setro ($device);
933 Sets the block device named "device" to read-only.
934 This uses the blockdev(8) command.
936 $g->blockdev_setrw ($device);
938 Sets the block device named "device" to read-write.
939 This uses the blockdev(8) command.
941 $g->btrfs_balance_cancel ($path);
943 Cancel a running balance on a btrfs filesystem.
944 This function depends on the feature "btrfs". See also
946 "$g->feature-available".
947 $g->btrfs_balance_pause ($path);
949 Pause a running balance on a btrfs filesystem.
950 This function depends on the feature "btrfs". See also
952 "$g->feature-available".
953 $g->btrfs_balance_resume ($path);
955 Resume a paused balance on a btrfs filesystem.
956 This function depends on the feature "btrfs". See also
958 "$g->feature-available".
959 %status = $g->btrfs_balance_status ($path);
961 Show the status of a running or paused balance on a btrfs
962 filesystem.
963 This function depends on the feature "btrfs". See also
965 "$g->feature-available".
966 $g->btrfs_device_add (\@devices, $fs);
968 Add the list of device(s) in "devices" to the btrfs filesystem
969 mounted at "fs". If "devices" is an empty list, this does nothing.
970 This function depends on the feature "btrfs". See also
972 "$g->feature-available".
973 $g->btrfs_device_delete (\@devices, $fs);
975 Remove the "devices" from the btrfs filesystem mounted at "fs". If
976 "devices" is an empty list, this does nothing.
977 This function depends on the feature "btrfs". See also
979 "$g->feature-available".
980 $g->btrfs_filesystem_balance ($fs);
982 Balance the chunks in the btrfs filesystem mounted at "fs" across
983 the underlying devices.
984 This function depends on the feature "btrfs". See also
986 "$g->feature-available".
987 $g->btrfs_filesystem_defragment ($path [, flush => $flush] [, compress
989 => $compress]);
990 Defragment a file or directory on a btrfs filesystem. compress is
991 one of zlib or lzo.
992 This function depends on the feature "btrfs". See also
994 "$g->feature-available".
995 $g->btrfs_filesystem_resize ($mountpoint [, size => $size]);
997 This command resizes a btrfs filesystem.
998 Note that unlike other resize calls, the filesystem has to be
1000 mounted and the parameter is the mountpoint not the device (this is
1001 a requirement of btrfs itself).
1002 The optional parameters are:
1004 "size"
1006 The new size (in bytes) of the filesystem. If omitted, the
1007 filesystem is resized to the maximum size.
1008 See also btrfs(8).
1010 This function depends on the feature "btrfs". See also
1012 "$g->feature-available".
1013 @devices = $g->btrfs_filesystem_show ($device);
1015 Show all the devices where the filesystems in "device" is spanned
1016 over.
1017 If not all the devices for the filesystems are present, then this
1019 function fails and the "errno" is set to "ENODEV".
1020 This function depends on the feature "btrfs". See also
1022 "$g->feature-available".
1023 $g->btrfs_filesystem_sync ($fs);
1025 Force sync on the btrfs filesystem mounted at "fs".
1026 This function depends on the feature "btrfs". See also
1028 "$g->feature-available".
1029 $g->btrfs_fsck ($device [, superblock => $superblock] [, repair =>
1031 $repair]);
1032 Used to check a btrfs filesystem, "device" is the device file where
1033 the filesystem is stored.
1034 This function depends on the feature "btrfs". See also
1036 "$g->feature-available".
1037 $g->btrfs_image (\@source, $image [, compresslevel => $compresslevel]);
1039 This is used to create an image of a btrfs filesystem. All data
1040 will be zeroed, but metadata and the like is preserved.
1041 This function depends on the feature "btrfs". See also
1043 "$g->feature-available".
1044 $g->btrfs_qgroup_assign ($src, $dst, $path);
1046 Add qgroup "src" to parent qgroup "dst". This command can group
1047 several qgroups into a parent qgroup to share common limit.
1048 This function depends on the feature "btrfs". See also
1050 "$g->feature-available".
1051 $g->btrfs_qgroup_create ($qgroupid, $subvolume);
1053 Create a quota group (qgroup) for subvolume at "subvolume".
1054 This function depends on the feature "btrfs". See also
1056 "$g->feature-available".
1057 $g->btrfs_qgroup_destroy ($qgroupid, $subvolume);
1059 Destroy a quota group.
1060 This function depends on the feature "btrfs". See also
1062 "$g->feature-available".
1063 $g->btrfs_qgroup_limit ($subvolume, $size);
1065 Limit the size of the subvolume with path "subvolume".
1066 This function depends on the feature "btrfs". See also
1068 "$g->feature-available".
1069 $g->btrfs_qgroup_remove ($src, $dst, $path);
1071 Remove qgroup "src" from the parent qgroup "dst".
1072 This function depends on the feature "btrfs". See also
1074 "$g->feature-available".
1075 @qgroups = $g->btrfs_qgroup_show ($path);
1077 Show all subvolume quota groups in a btrfs filesystem, including
1078 their usages.
1079 This function depends on the feature "btrfs". See also
1081 "$g->feature-available".
1082 $g->btrfs_quota_enable ($fs, $enable);
1084 Enable or disable subvolume quota support for filesystem which
1085 contains "path".
1086 This function depends on the feature "btrfs". See also
1088 "$g->feature-available".
1089 $g->btrfs_quota_rescan ($fs);
1091 Trash all qgroup numbers and scan the metadata again with the
1092 current config.
1093 This function depends on the feature "btrfs". See also
1095 "$g->feature-available".
1096 $g->btrfs_replace ($srcdev, $targetdev, $mntpoint);
1098 Replace device of a btrfs filesystem. On a live filesystem,
1099 duplicate the data to the target device which is currently stored
1100 on the source device. After completion of the operation, the
1101 source device is wiped out and removed from the filesystem.
1102 The "targetdev" needs to be same size or larger than the "srcdev".
1104 Devices which are currently mounted are never allowed to be used as
1105 the "targetdev".
1106 This function depends on the feature "btrfs". See also
1108 "$g->feature-available".
1109 $g->btrfs_rescue_chunk_recover ($device);
1111 Recover the chunk tree of btrfs filesystem by scanning the devices
1112 one by one.
1113 This function depends on the feature "btrfs". See also
1115 "$g->feature-available".
1116 $g->btrfs_rescue_super_recover ($device);
1118 Recover bad superblocks from good copies.
1119 This function depends on the feature "btrfs". See also
1121 "$g->feature-available".
1122 $g->btrfs_scrub_cancel ($path);
1124 Cancel a running scrub on a btrfs filesystem.
1125 This function depends on the feature "btrfs". See also
1127 "$g->feature-available".
1128 $g->btrfs_scrub_resume ($path);
1130 Resume a previously canceled or interrupted scrub on a btrfs
1131 filesystem.
1132 This function depends on the feature "btrfs". See also
1134 "$g->feature-available".
1135 $g->btrfs_scrub_start ($path);
1137 Reads all the data and metadata on the filesystem, and uses
1138 checksums and the duplicate copies from RAID storage to identify
1139 and repair any corrupt data.
1140 This function depends on the feature "btrfs". See also
1142 "$g->feature-available".
1143 %status = $g->btrfs_scrub_status ($path);
1145 Show status of running or finished scrub on a btrfs filesystem.
1146 This function depends on the feature "btrfs". See also
1148 "$g->feature-available".
1149 $g->btrfs_set_seeding ($device, $seeding);
1151 Enable or disable the seeding feature of a device that contains a
1152 btrfs filesystem.
1153 This function depends on the feature "btrfs". See also
1155 "$g->feature-available".
1156 $g->btrfs_subvolume_create ($dest [, qgroupid => $qgroupid]);
1158 Create a btrfs subvolume. The "dest" argument is the destination
1159 directory and the name of the subvolume, in the form
1160 /path/to/dest/name. The optional parameter "qgroupid" represents
1161 the qgroup which the newly created subvolume will be added to.
1162 This function depends on the feature "btrfs". See also
1164 "$g->feature-available".
1165 $g->btrfs_subvolume_create_opts ($dest [, qgroupid => $qgroupid]);
1167 This is an alias of "btrfs_subvolume_create".
1168 $g->btrfs_subvolume_delete ($subvolume);
1170 Delete the named btrfs subvolume or snapshot.
1171 This function depends on the feature "btrfs". See also
1173 "$g->feature-available".
1174 $id = $g->btrfs_subvolume_get_default ($fs);
1176 Get the default subvolume or snapshot of a filesystem mounted at
1177 "mountpoint".
1178 This function depends on the feature "btrfs". See also
1180 "$g->feature-available".
1181 @subvolumes = $g->btrfs_subvolume_list ($fs);
1183 List the btrfs snapshots and subvolumes of the btrfs filesystem
1184 which is mounted at "fs".
1185 This function depends on the feature "btrfs". See also
1187 "$g->feature-available".
1188 $g->btrfs_subvolume_set_default ($id, $fs);
1190 Set the subvolume of the btrfs filesystem "fs" which will be
1191 mounted by default. See "$g->btrfs_subvolume_list" to get a list
1192 of subvolumes.
1193 This function depends on the feature "btrfs". See also
1195 "$g->feature-available".
1196 %btrfssubvolumeinfo = $g->btrfs_subvolume_show ($subvolume);
1198 Return detailed information of the subvolume.
1199 This function depends on the feature "btrfs". See also
1201 "$g->feature-available".
1202 $g->btrfs_subvolume_snapshot ($source, $dest [, ro => $ro] [, qgroupid
1204 => $qgroupid]);
1205 Create a snapshot of the btrfs subvolume "source". The "dest"
1206 argument is the destination directory and the name of the snapshot,
1207 in the form /path/to/dest/name. By default the newly created
1208 snapshot is writable, if the value of optional parameter "ro" is
1209 true, then a readonly snapshot is created. The optional parameter
1210 "qgroupid" represents the qgroup which the newly created snapshot
1211 will be added to.
1212 This function depends on the feature "btrfs". See also
1214 "$g->feature-available".
1215 $g->btrfs_subvolume_snapshot_opts ($source, $dest [, ro => $ro] [,
1217 qgroupid => $qgroupid]);
1218 This is an alias of "btrfs_subvolume_snapshot".
1219 $g->btrfstune_enable_extended_inode_refs ($device);
1221 This will Enable extended inode refs.
1222 This function depends on the feature "btrfs". See also
1224 "$g->feature-available".
1225 $g->btrfstune_enable_skinny_metadata_extent_refs ($device);
1227 This enable skinny metadata extent refs.
1228 This function depends on the feature "btrfs". See also
1230 "$g->feature-available".
1231 $g->btrfstune_seeding ($device, $seeding);
1233 Enable seeding of a btrfs device, this will force a fs readonly so
1234 that you can use it to build other filesystems.
1235 This function depends on the feature "btrfs". See also
1237 "$g->feature-available".
1238 $ptr = $g->c_pointer ();
1240 In non-C language bindings, this allows you to retrieve the
1241 underlying C pointer to the handle (ie. "$g->h *"). The purpose of
1242 this is to allow other libraries to interwork with libguestfs.
1243 $canonical = $g->canonical_device_name ($device);
1245 This utility function is useful when displaying device names to the
1246 user. It takes a number of irregular device names and returns them
1247 in a consistent format:
1248 /dev/hdX
1250 /dev/vdX
1251 These are returned as /dev/sdX. Note this works for device
1252 names and partition names. This is approximately the reverse
1253 of the algorithm described in "BLOCK DEVICE NAMING" in
1254 guestfs(3).
1255 /dev/mapper/VG-LV
1257 /dev/dm-N
1258 Converted to /dev/VG/LV form using "$g->lvm_canonical_lv_name".
1259 Other strings are returned unmodified.
1261 $cap = $g->cap_get_file ($path);
1263 This function returns the Linux capabilities attached to "path".
1264 The capabilities set is returned in text form (see cap_to_text(3)).
1265 If no capabilities are attached to a file, an empty string is
1267 returned.
1268 This function depends on the feature "linuxcaps". See also
1270 "$g->feature-available".
1271 $g->cap_set_file ($path, $cap);
1273 This function sets the Linux capabilities attached to "path". The
1274 capabilities set "cap" should be passed in text form (see
1275 cap_from_text(3)).
1276 This function depends on the feature "linuxcaps". See also
1278 "$g->feature-available".
1279 $rpath = $g->case_sensitive_path ($path);
1281 This can be used to resolve case insensitive paths on a filesystem
1282 which is case sensitive. The use case is to resolve paths which
1283 you have read from Windows configuration files or the Windows
1284 Registry, to the true path.
1285 The command handles a peculiarity of the Linux ntfs-3g filesystem
1287 driver (and probably others), which is that although the underlying
1288 filesystem is case-insensitive, the driver exports the filesystem
1289 to Linux as case-sensitive.
1290 One consequence of this is that special directories such as
1292 C:\windows may appear as /WINDOWS or /windows (or other things)
1293 depending on the precise details of how they were created. In
1294 Windows itself this would not be a problem.
1295 Bug or feature? You decide:
1297 <http://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1>
1298 "$g->case_sensitive_path" attempts to resolve the true case of each
1300 element in the path. It will return a resolved path if either the
1301 full path or its parent directory exists. If the parent directory
1302 exists but the full path does not, the case of the parent directory
1303 will be correctly resolved, and the remainder appended unmodified.
1304 For example, if the file "/Windows/System32/netkvm.sys" exists:
1305 "$g->case_sensitive_path" ("/windows/system32/netkvm.sys")
1307 "Windows/System32/netkvm.sys"
1308 "$g->case_sensitive_path" ("/windows/system32/NoSuchFile")
1310 "Windows/System32/NoSuchFile"
1311 "$g->case_sensitive_path" ("/windows/system33/netkvm.sys")
1313 ERROR
1314 Note: Because of the above behaviour, "$g->case_sensitive_path"
1316 cannot be used to check for the existence of a file.
1317 Note: This function does not handle drive names, backslashes etc.
1319 See also "$g->realpath".
1321 $content = $g->cat ($path);
1323 Return the contents of the file named "path".
1324 Because, in C, this function returns a "char *", there is no way to
1326 differentiate between a "\0" character in a file and end of string.
1327 To handle binary files, use the "$g->read_file" or "$g->download"
1328 functions.
1329 $checksum = $g->checksum ($csumtype, $path);
1331 This call computes the MD5, SHAx or CRC checksum of the file named
1332 "path".
1333 The type of checksum to compute is given by the "csumtype"
1335 parameter which must have one of the following values:
1336 "crc"
1338 Compute the cyclic redundancy check (CRC) specified by POSIX
1339 for the "cksum" command.
1340 "md5"
1342 Compute the MD5 hash (using the "md5sum" program).
1343 "sha1"
1345 Compute the SHA1 hash (using the "sha1sum" program).
1346 "sha224"
1348 Compute the SHA224 hash (using the "sha224sum" program).
1349 "sha256"
1351 Compute the SHA256 hash (using the "sha256sum" program).
1352 "sha384"
1354 Compute the SHA384 hash (using the "sha384sum" program).
1355 "sha512"
1357 Compute the SHA512 hash (using the "sha512sum" program).
1358 The checksum is returned as a printable string.
1360 To get the checksum for a device, use "$g->checksum_device".
1362 To get the checksums for many files, use "$g->checksums_out".
1364 $checksum = $g->checksum_device ($csumtype, $device);
1366 This call computes the MD5, SHAx or CRC checksum of the contents of
1367 the device named "device". For the types of checksums supported
1368 see the "$g->checksum" command.
1369 $g->checksums_out ($csumtype, $directory, $sumsfile);
1371 This command computes the checksums of all regular files in
1372 directory and then emits a list of those checksums to the local
1373 output file "sumsfile".
1374 This can be used for verifying the integrity of a virtual machine.
1376 However to be properly secure you should pay attention to the
1377 output of the checksum command (it uses the ones from GNU
1378 coreutils). In particular when the filename is not printable,
1379 coreutils uses a special backslash syntax. For more information,
1380 see the GNU coreutils info file.
1381 $g->chmod ($mode, $path);
1383 Change the mode (permissions) of "path" to "mode". Only numeric
1384 modes are supported.
1385 Note: When using this command from guestfish, "mode" by default
1387 would be decimal, unless you prefix it with 0 to get octal, ie. use
1388 0700 not 700.
1389 The mode actually set is affected by the umask.
1391 $g->chown ($owner, $group, $path);
1393 Change the file owner to "owner" and group to "group".
1394 Only numeric uid and gid are supported. If you want to use names,
1396 you will need to locate and parse the password file yourself
1397 (Augeas support makes this relatively easy).
1398 $count = $g->clear_backend_setting ($name);
1400 If there is a backend setting string matching "name" or beginning
1401 with "name=", then that string is removed from the backend
1402 settings.
1403 This call returns the number of strings which were removed (which
1405 may be 0, 1 or greater than 1).
1406 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
1408 $output = $g->command (\@arguments);
1410 This call runs a command from the guest filesystem. The filesystem
1411 must be mounted, and must contain a compatible operating system
1412 (ie. something Linux, with the same or compatible processor
1413 architecture).
1414 The single parameter is an argv-style list of arguments. The first
1416 element is the name of the program to run. Subsequent elements are
1417 parameters. The list must be non-empty (ie. must contain a program
1418 name). Note that the command runs directly, and is not invoked via
1419 the shell (see "$g->sh").
1420 The return value is anything printed to stdout by the command.
1422 If the command returns a non-zero exit status, then this function
1424 returns an error message. The error message string is the content
1425 of stderr from the command.
1426 The $PATH environment variable will contain at least /usr/bin and
1428 /bin. If you require a program from another location, you should
1429 provide the full path in the first parameter.
1430 Shared libraries and data files required by the program must be
1432 available on filesystems which are mounted in the correct places.
1433 It is the callerXs responsibility to ensure all filesystems that
1434 are needed are mounted at the right locations.
1435 Because of the message protocol, there is a transfer limit of
1437 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1438 guestfs(3).
1439 @lines = $g->command_lines (\@arguments);
1441 This is the same as "$g->command", but splits the result into a
1442 list of lines.
1443 See also: "$g->sh_lines"
1445 Because of the message protocol, there is a transfer limit of
1447 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1448 guestfs(3).
1449 $g->compress_device_out ($ctype, $device, $zdevice [, level =>
1451 $level]);
1452 This command compresses "device" and writes it out to the local
1453 file "zdevice".
1454 The "ctype" and optional "level" parameters have the same meaning
1456 as in "$g->compress_out".
1457 $g->compress_out ($ctype, $file, $zfile [, level => $level]);
1459 This command compresses file and writes it out to the local file
1460 zfile.
1461 The compression program used is controlled by the "ctype"
1463 parameter. Currently this includes: "compress", "gzip", "bzip2",
1464 "xz" or "lzop". Some compression types may not be supported by
1465 particular builds of libguestfs, in which case you will get an
1466 error containing the substring "not supported".
1467 The optional "level" parameter controls compression level. The
1469 meaning and default for this parameter depends on the compression
1470 program being used.
1471 $g->config ($hvparam, $hvvalue);
1473 This can be used to add arbitrary hypervisor parameters of the form
1474 -param value. Actually itXs not quite arbitrary - we prevent you
1475 from setting some parameters which would interfere with parameters
1476 that we use.
1477 The first character of "hvparam" string must be a "-" (dash).
1479 "hvvalue" can be NULL.
1481 $g->copy_attributes ($src, $dest [, all => $all] [, mode => $mode] [,
1483 xattributes => $xattributes] [, ownership => $ownership]);
1484 Copy the attributes of a path (which can be a file or a directory)
1485 to another path.
1486 By default "no" attribute is copied, so make sure to specify any
1488 (or "all" to copy everything).
1489 The optional arguments specify which attributes can be copied:
1491 "mode"
1493 Copy part of the file mode from "source" to "destination". Only
1494 the UNIX permissions and the sticky/setuid/setgid bits can be
1495 copied.
1496 "xattributes"
1498 Copy the Linux extended attributes (xattrs) from "source" to
1499 "destination". This flag does nothing if the linuxxattrs
1500 feature is not available (see "$g->feature_available").
1501 "ownership"
1503 Copy the owner uid and the group gid of "source" to
1504 "destination".
1505 "all"
1507 Copy all the attributes from "source" to "destination".
1508 Enabling it enables all the other flags, if they are not
1509 specified already.
1510 $g->copy_device_to_device ($src, $dest [, srcoffset => $srcoffset] [,
1512 destoffset => $destoffset] [, size => $size] [, sparse => $sparse] [,
1513 append => $append]);
1514 The four calls "$g->copy_device_to_device",
1515 "$g->copy_device_to_file", "$g->copy_file_to_device", and
1516 "$g->copy_file_to_file" let you copy from a source (device|file) to
1517 a destination (device|file).
1518 Partial copies can be made since you can specify optionally the
1520 source offset, destination offset and size to copy. These values
1521 are all specified in bytes. If not given, the offsets both default
1522 to zero, and the size defaults to copying as much as possible until
1523 we hit the end of the source.
1524 The source and destination may be the same object. However
1526 overlapping regions may not be copied correctly.
1527 If the destination is a file, it is created if required. If the
1529 destination file is not large enough, it is extended.
1530 If the destination is a file and the "append" flag is not set, then
1532 the destination file is truncated. If the "append" flag is set,
1533 then the copy appends to the destination file. The "append" flag
1534 currently cannot be set for devices.
1535 If the "sparse" flag is true then the call avoids writing blocks
1537 that contain only zeroes, which can help in some situations where
1538 the backing disk is thin-provisioned. Note that unless the target
1539 is already zeroed, using this option will result in incorrect
1540 copying.
1541 $g->copy_device_to_file ($src, $dest [, srcoffset => $srcoffset] [,
1543 destoffset => $destoffset] [, size => $size] [, sparse => $sparse] [,
1544 append => $append]);
1545 See "$g->copy_device_to_device" for a general overview of this
1546 call.
1547 $g->copy_file_to_device ($src, $dest [, srcoffset => $srcoffset] [,
1549 destoffset => $destoffset] [, size => $size] [, sparse => $sparse] [,
1550 append => $append]);
1551 See "$g->copy_device_to_device" for a general overview of this
1552 call.
1553 $g->copy_file_to_file ($src, $dest [, srcoffset => $srcoffset] [,
1555 destoffset => $destoffset] [, size => $size] [, sparse => $sparse] [,
1556 append => $append]);
1557 See "$g->copy_device_to_device" for a general overview of this
1558 call.
1559 This is not the function you want for copying files. This is for
1561 copying blocks within existing files. See "$g->cp", "$g->cp_a" and
1562 "$g->mv" for general file copying and moving functions.
1563 $g->copy_in ($localpath, $remotedir);
1565 "$g->copy_in" copies local files or directories recursively into
1566 the disk image, placing them in the directory called "remotedir"
1567 (which must exist).
1568 Wildcards cannot be used.
1570 $g->copy_out ($remotepath, $localdir);
1572 "$g->copy_out" copies remote files or directories recursively out
1573 of the disk image, placing them on the host disk in a local
1574 directory called "localdir" (which must exist).
1575 To download to the current directory, use "." as in:
1577 C<$g-E<gt>copy_out> /home .
1579 Wildcards cannot be used.
1581 $g->copy_size ($src, $dest, $size);
1583 This command copies exactly "size" bytes from one source device or
1584 file "src" to another destination device or file "dest".
1585 Note this will fail if the source is too short or if the
1587 destination is not large enough.
1588 This function is deprecated. In new code, use the
1590 "copy_device_to_device" call instead.
1591 Deprecated functions will not be removed from the API, but the fact
1593 that they are deprecated indicates that there are problems with
1594 correct use of these functions.
1595 $g->cp ($src, $dest);
1597 This copies a file from "src" to "dest" where "dest" is either a
1598 destination filename or destination directory.
1599 $g->cp_a ($src, $dest);
1601 This copies a file or directory from "src" to "dest" recursively
1602 using the "cp -a" command.
1603 $g->cp_r ($src, $dest);
1605 This copies a file or directory from "src" to "dest" recursively
1606 using the "cp -rP" command.
1607 Most users should use "$g->cp_a" instead. This command is useful
1609 when you don't want to preserve permissions, because the target
1610 filesystem does not support it (primarily when writing to DOS FAT
1611 filesystems).
1612 $g->cpio_out ($directory, $cpiofile [, format => $format]);
1614 This command packs the contents of directory and downloads it to
1615 local file "cpiofile".
1616 The optional "format" parameter can be used to select the format.
1618 Only the following formats are currently permitted:
1619 "newc"
1621 New (SVR4) portable format. This format happens to be
1622 compatible with the cpio-like format used by the Linux kernel
1623 for initramfs.
1624 This is the default format.
1626 "crc"
1628 New (SVR4) portable format with a checksum.
1629 $g->dd ($src, $dest);
1631 This command copies from one source device or file "src" to another
1632 destination device or file "dest". Normally you would use this to
1633 copy to or from a device or partition, for example to duplicate a
1634 filesystem.
1635 If the destination is a device, it must be as large or larger than
1637 the source file or device, otherwise the copy will fail. This
1638 command cannot do partial copies (see "$g->copy_device_to_device").
1639 This function is deprecated. In new code, use the
1641 "copy_device_to_device" call instead.
1642 Deprecated functions will not be removed from the API, but the fact
1644 that they are deprecated indicates that there are problems with
1645 correct use of these functions.
1646 $index = $g->device_index ($device);
1648 This function takes a device name (eg. "/dev/sdb") and returns the
1649 index of the device in the list of devices.
1650 Index numbers start from 0. The named device must exist, for
1652 example as a string returned from "$g->list_devices".
1653 See also "$g->list_devices", "$g->part_to_dev".
1655 $output = $g->df ();
1657 This command runs the "df" command to report disk space used.
1658 This command is mostly useful for interactive sessions. It is not
1660 intended that you try to parse the output string. Use
1661 "$g->statvfs" from programs.
1662 $output = $g->df_h ();
1664 This command runs the "df -h" command to report disk space used in
1665 human-readable format.
1666 This command is mostly useful for interactive sessions. It is not
1668 intended that you try to parse the output string. Use
1669 "$g->statvfs" from programs.
1670 $g->disk_create ($filename, $format, $size [, backingfile =>
1672 $backingfile] [, backingformat => $backingformat] [, preallocation =>
1673 $preallocation] [, compat => $compat] [, clustersize => $clustersize]);
1674 Create a blank disk image called filename (a host file) with format
1675 "format" (usually "raw" or "qcow2"). The size is "size" bytes.
1676 If used with the optional "backingfile" parameter, then a snapshot
1678 is created on top of the backing file. In this case, "size" must
1679 be passed as "-1". The size of the snapshot is the same as the
1680 size of the backing file, which is discovered automatically. You
1681 are encouraged to also pass "backingformat" to describe the format
1682 of "backingfile".
1683 If filename refers to a block device, then the device is formatted.
1685 The "size" is ignored since block devices have an intrinsic size.
1686 The other optional parameters are:
1688 "preallocation"
1690 If format is "raw", then this can be either "off" (or "sparse")
1691 or "full" to create a sparse or fully allocated file
1692 respectively. The default is "off".
1693 If format is "qcow2", then this can be "off" (or "sparse"),
1695 "metadata" or "full". Preallocating metadata can be faster
1696 when doing lots of writes, but uses more space. The default is
1697 "off".
1698 "compat"
1700 "qcow2" only: Pass the string 1.1 to use the advanced qcow2
1701 format supported by qemu X 1.1.
1702 "clustersize"
1704 "qcow2" only: Change the qcow2 cluster size. The default is
1705 65536 (bytes) and this setting may be any power of two between
1706 512 and 2097152.
1707 Note that this call does not add the new disk to the handle. You
1709 may need to call "$g->add_drive_opts" separately.
1710 $format = $g->disk_format ($filename);
1712 Detect and return the format of the disk image called filename.
1713 filename can also be a host device, etc. If the format of the
1714 image could not be detected, then "unknown" is returned.
1715 Note that detecting the disk format can be insecure under some
1717 circumstances. See "CVE-2010-3851" in guestfs(3).
1718 See also: "DISK IMAGE FORMATS" in guestfs(3)
1720 $backingfile = $g->disk_has_backing_file ($filename);
1722 Detect and return whether the disk image filename has a backing
1723 file.
1724 Note that detecting disk features can be insecure under some
1726 circumstances. See "CVE-2010-3851" in guestfs(3).
1727 $size = $g->disk_virtual_size ($filename);
1729 Detect and return the virtual size in bytes of the disk image
1730 called filename.
1731 Note that detecting disk features can be insecure under some
1733 circumstances. See "CVE-2010-3851" in guestfs(3).
1734 $kmsgs = $g->dmesg ();
1736 This returns the kernel messages ("dmesg" output) from the guest
1737 kernel. This is sometimes useful for extended debugging of
1738 problems.
1739 Another way to get the same information is to enable verbose
1741 messages with "$g->set_verbose" or by setting the environment
1742 variable "LIBGUESTFS_DEBUG=1" before running the program.
1743 $g->download ($remotefilename, $filename);
1745 Download file remotefilename and save it as filename on the local
1746 machine.
1747 filename can also be a named pipe.
1749 See also "$g->upload", "$g->cat".
1751 $g->download_blocks ($device, $start, $stop, $filename [, unallocated
1753 => $unallocated]);
1754 Download the data units from start address to stop from the disk
1755 partition (eg. /dev/sda1) and save them as filename on the local
1756 machine.
1757 The use of this API on sparse disk image formats such as QCOW, may
1759 result in large zero-filled files downloaded on the host.
1760 The size of a data unit varies across filesystem implementations.
1762 On NTFS filesystems data units are referred as clusters while on
1763 ExtX ones they are referred as fragments.
1764 If the optional "unallocated" flag is true (default is false), only
1766 the unallocated blocks will be extracted. This is useful to detect
1767 hidden data or to retrieve deleted files which data units have not
1768 been overwritten yet.
1769 This function depends on the feature "sleuthkit". See also
1771 "$g->feature-available".
1772 $g->download_inode ($device, $inode, $filename);
1774 Download a file given its inode from the disk partition (eg.
1775 /dev/sda1) and save it as filename on the local machine.
1776 It is not required to mount the disk to run this command.
1778 The command is capable of downloading deleted or inaccessible
1780 files.
1781 This function depends on the feature "sleuthkit". See also
1783 "$g->feature-available".
1784 $g->download_offset ($remotefilename, $filename, $offset, $size);
1786 Download file remotefilename and save it as filename on the local
1787 machine.
1788 remotefilename is read for "size" bytes starting at "offset" (this
1790 region must be within the file or device).
1791 Note that there is no limit on the amount of data that can be
1793 downloaded with this call, unlike with "$g->pread", and this call
1794 always reads the full amount unless an error occurs.
1795 See also "$g->download", "$g->pread".
1797 $g->drop_caches ($whattodrop);
1799 This instructs the guest kernel to drop its page cache, and/or
1800 dentries and inode caches. The parameter "whattodrop" tells the
1801 kernel what precisely to drop, see
1802 <http://linux-mm.org/Drop_Caches>
1803 Setting "whattodrop" to 3 should drop everything.
1805 This automatically calls sync(2) before the operation, so that the
1807 maximum guest memory is freed.
1808 $sizekb = $g->du ($path);
1810 This command runs the "du -s" command to estimate file space usage
1811 for "path".
1812 "path" can be a file or a directory. If "path" is a directory then
1814 the estimate includes the contents of the directory and all
1815 subdirectories (recursively).
1816 The result is the estimated size in kilobytes (ie. units of 1024
1818 bytes).
1819 $g->e2fsck ($device [, correct => $correct] [, forceall => $forceall]);
1821 This runs the ext2/ext3 filesystem checker on "device". It can
1822 take the following optional arguments:
1823 "correct"
1825 Automatically repair the file system. This option will cause
1826 e2fsck to automatically fix any filesystem problems that can be
1827 safely fixed without human intervention.
1828 This option may not be specified at the same time as the
1830 "forceall" option.
1831 "forceall"
1833 Assume an answer of XyesX to all questions; allows e2fsck to be
1834 used non-interactively.
1835 This option may not be specified at the same time as the
1837 "correct" option.
1838 $g->e2fsck_f ($device);
1840 This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
1841 checker on "device", noninteractively (-p), even if the filesystem
1842 appears to be clean (-f).
1843 This function is deprecated. In new code, use the "e2fsck" call
1845 instead.
1846 Deprecated functions will not be removed from the API, but the fact
1848 that they are deprecated indicates that there are problems with
1849 correct use of these functions.
1850 $output = $g->echo_daemon (\@words);
1852 This command concatenates the list of "words" passed with single
1853 spaces between them and returns the resulting string.
1854 You can use this command to test the connection through to the
1856 daemon.
1857 See also "$g->ping_daemon".
1859 @lines = $g->egrep ($regex, $path);
1861 This calls the external "egrep" program and returns the matching
1862 lines.
1863 Because of the message protocol, there is a transfer limit of
1865 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1866 guestfs(3).
1867 This function is deprecated. In new code, use the "grep" call
1869 instead.
1870 Deprecated functions will not be removed from the API, but the fact
1872 that they are deprecated indicates that there are problems with
1873 correct use of these functions.
1874 @lines = $g->egrepi ($regex, $path);
1876 This calls the external "egrep -i" program and returns the matching
1877 lines.
1878 Because of the message protocol, there is a transfer limit of
1880 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1881 guestfs(3).
1882 This function is deprecated. In new code, use the "grep" call
1884 instead.
1885 Deprecated functions will not be removed from the API, but the fact
1887 that they are deprecated indicates that there are problems with
1888 correct use of these functions.
1889 $equality = $g->equal ($file1, $file2);
1891 This compares the two files file1 and file2 and returns true if
1892 their content is exactly equal, or false otherwise.
1893 The external cmp(1) program is used for the comparison.
1895 $existsflag = $g->exists ($path);
1897 This returns "true" if and only if there is a file, directory (or
1898 anything) with the given "path" name.
1899 See also "$g->is_file", "$g->is_dir", "$g->stat".
1901 $g->extlinux ($directory);
1903 Install the SYSLINUX bootloader on the device mounted at directory.
1904 Unlike "$g->syslinux" which requires a FAT filesystem, this can be
1905 used on an ext2/3/4 or btrfs filesystem.
1906 The directory parameter can be either a mountpoint, or a directory
1908 within the mountpoint.
1909 You also have to mark the partition as "active"
1911 ("$g->part_set_bootable") and a Master Boot Record must be
1912 installed (eg. using "$g->pwrite_device") on the first sector of
1913 the whole disk. The SYSLINUX package comes with some suitable
1914 Master Boot Records. See the extlinux(1) man page for further
1915 information.
1916 Additional configuration can be supplied to SYSLINUX by placing a
1918 file called extlinux.conf on the filesystem under directory. For
1919 further information about the contents of this file, see
1920 extlinux(1).
1921 See also "$g->syslinux".
1923 This function depends on the feature "extlinux". See also
1925 "$g->feature-available".
1926 $g->f2fs_expand ($device);
1928 This expands a f2fs filesystem to match the size of the underlying
1929 device.
1930 This function depends on the feature "f2fs". See also
1932 "$g->feature-available".
1933 $g->fallocate ($path, $len);
1935 This command preallocates a file (containing zero bytes) named
1936 "path" of size "len" bytes. If the file exists already, it is
1937 overwritten.
1938 Do not confuse this with the guestfish-specific "alloc" command
1940 which allocates a file in the host and attaches it as a device.
1941 This function is deprecated. In new code, use the "fallocate64"
1943 call instead.
1944 Deprecated functions will not be removed from the API, but the fact
1946 that they are deprecated indicates that there are problems with
1947 correct use of these functions.
1948 $g->fallocate64 ($path, $len);
1950 This command preallocates a file (containing zero bytes) named
1951 "path" of size "len" bytes. If the file exists already, it is
1952 overwritten.
1953 Note that this call allocates disk blocks for the file. To create
1955 a sparse file use "$g->truncate_size" instead.
1956 The deprecated call "$g->fallocate" does the same, but owing to an
1958 oversight it only allowed 30 bit lengths to be specified,
1959 effectively limiting the maximum size of files created through that
1960 call to 1GB.
1961 Do not confuse this with the guestfish-specific "alloc" and
1963 "sparse" commands which create a file in the host and attach it as
1964 a device.
1965 $isavailable = $g->feature_available (\@groups);
1967 This is the same as "$g->available", but unlike that call it
1968 returns a simple true/false boolean result, instead of throwing an
1969 exception if a feature is not found. For other documentation see
1970 "$g->available".
1971 @lines = $g->fgrep ($pattern, $path);
1973 This calls the external "fgrep" program and returns the matching
1974 lines.
1975 Because of the message protocol, there is a transfer limit of
1977 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1978 guestfs(3).
1979 This function is deprecated. In new code, use the "grep" call
1981 instead.
1982 Deprecated functions will not be removed from the API, but the fact
1984 that they are deprecated indicates that there are problems with
1985 correct use of these functions.
1986 @lines = $g->fgrepi ($pattern, $path);
1988 This calls the external "fgrep -i" program and returns the matching
1989 lines.
1990 Because of the message protocol, there is a transfer limit of
1992 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1993 guestfs(3).
1994 This function is deprecated. In new code, use the "grep" call
1996 instead.
1997 Deprecated functions will not be removed from the API, but the fact
1999 that they are deprecated indicates that there are problems with
2000 correct use of these functions.
2001 $description = $g->file ($path);
2003 This call uses the standard file(1) command to determine the type
2004 or contents of the file.
2005 This call will also transparently look inside various types of
2007 compressed file.
2008 The exact command which runs is "file -zb path". Note in
2010 particular that the filename is not prepended to the output (the -b
2011 option).
2012 The output depends on the output of the underlying file(1) command
2014 and it can change in future in ways beyond our control. In other
2015 words, the output is not guaranteed by the ABI.
2016 See also: file(1), "$g->vfs_type", "$g->lstat", "$g->is_file",
2018 "$g->is_blockdev" (etc), "$g->is_zero".
2019 $arch = $g->file_architecture ($filename);
2021 This detects the architecture of the binary filename, and returns
2022 it if known.
2023 Currently defined architectures are:
2025 "aarch64"
2027 64 bit ARM.
2028 "arm"
2030 32 bit ARM.
2031 "i386"
2033 This string is returned for all 32 bit i386, i486, i586, i686
2034 binaries irrespective of the precise processor requirements of
2035 the binary.
2036 "ia64"
2038 Intel Itanium.
2039 "ppc"
2041 32 bit Power PC.
2042 "ppc64"
2044 64 bit Power PC (big endian).
2045 "ppc64le"
2047 64 bit Power PC (little endian).
2048 "riscv32"
2050 "riscv64"
2051 "riscv128"
2052 RISC-V 32-, 64- or 128-bit variants.
2053 "s390"
2055 31 bit IBM S/390.
2056 "s390x"
2058 64 bit IBM S/390.
2059 "sparc"
2061 32 bit SPARC.
2062 "sparc64"
2064 64 bit SPARC V9 and above.
2065 "x86_64"
2067 64 bit x86-64.
2068 Libguestfs may return other architecture strings in future.
2070 The function works on at least the following types of files:
2072 · many types of Un*x and Linux binary
2074 · many types of Un*x and Linux shared library
2076 · Windows Win32 and Win64 binaries
2078 · Windows Win32 and Win64 DLLs
2080 Win32 binaries and DLLs return "i386".
2082 Win64 binaries and DLLs return "x86_64".
2084 · Linux kernel modules
2086 · Linux new-style initrd images
2088 · some non-x86 Linux vmlinuz kernels
2090 What it can't do currently:
2092 · static libraries (libfoo.a)
2094 · Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
2096 · x86 Linux vmlinuz kernels
2098 x86 vmlinuz images (bzImage format) consist of a mix of 16-,
2100 32- and compressed code, and are horribly hard to unpack. If
2101 you want to find the architecture of a kernel, use the
2102 architecture of the associated initrd or kernel module(s)
2103 instead.
2104 $size = $g->filesize ($file);
2106 This command returns the size of file in bytes.
2107 To get other stats about a file, use "$g->stat", "$g->lstat",
2109 "$g->is_dir", "$g->is_file" etc. To get the size of block devices,
2110 use "$g->blockdev_getsize64".
2111 $fsavail = $g->filesystem_available ($filesystem);
2113 Check whether libguestfs supports the named filesystem. The
2114 argument "filesystem" is a filesystem name, such as "ext3".
2115 You must call "$g->launch" before using this command.
2117 This is mainly useful as a negative test. If this returns true, it
2119 doesn't mean that a particular filesystem can be created or
2120 mounted, since filesystems can fail for other reasons such as it
2121 being a later version of the filesystem, or having incompatible
2122 features, or lacking the right mkfs.<fs> tool.
2123 See also "$g->available", "$g->feature_available", "AVAILABILITY"
2125 in guestfs(3).
2126 @dirents = $g->filesystem_walk ($device);
2128 Walk through the internal structures of a disk partition (eg.
2129 /dev/sda1) in order to return a list of all the files and
2130 directories stored within.
2131 It is not necessary to mount the disk partition to run this
2133 command.
2134 All entries in the filesystem are returned. This function can list
2136 deleted or unaccessible files. The entries are not sorted.
2137 The "tsk_dirent" structure contains the following fields.
2139 "tsk_inode"
2141 Filesystem reference number of the node. It might be 0 if the
2142 node has been deleted.
2143 "tsk_type"
2145 Basic file type information. See below for a detailed list of
2146 values.
2147 "tsk_size"
2149 File size in bytes. It might be "-1" if the node has been
2150 deleted.
2151 "tsk_name"
2153 The file path relative to its directory.
2154 "tsk_flags"
2156 Bitfield containing extra information regarding the entry. It
2157 contains the logical OR of the following values:
2158 0x0001
2160 If set to 1, the file is allocated and visible within the
2161 filesystem. Otherwise, the file has been deleted. Under
2162 certain circumstances, the function "download_inode" can be
2163 used to recover deleted files.
2164 0x0002
2166 Filesystem such as NTFS and Ext2 or greater, separate the
2167 file name from the metadata structure. The bit is set to 1
2168 when the file name is in an unallocated state and the
2169 metadata structure is in an allocated one. This generally
2170 implies the metadata has been reallocated to a new file.
2171 Therefore, information such as file type, file size,
2172 timestamps, number of links and symlink target might not
2173 correspond with the ones of the original deleted entry.
2174 0x0004
2176 The bit is set to 1 when the file is compressed using
2177 filesystem native compression support (NTFS). The API is
2178 not able to detect application level compression.
2179 "tsk_atime_sec"
2181 "tsk_atime_nsec"
2182 "tsk_mtime_sec"
2183 "tsk_mtime_nsec"
2184 "tsk_ctime_sec"
2185 "tsk_ctime_nsec"
2186 "tsk_crtime_sec"
2187 "tsk_crtime_nsec"
2188 Respectively, access, modification, last status change and
2189 creation time in Unix format in seconds and nanoseconds.
2190 "tsk_nlink"
2192 Number of file names pointing to this entry.
2193 "tsk_link"
2195 If the entry is a symbolic link, this field will contain the
2196 path to the target file.
2197 The "tsk_type" field will contain one of the following characters:
2199 'b' Block special
2201 'c' Char special
2203 'd' Directory
2205 'f' FIFO (named pipe)
2207 'l' Symbolic link
2209 'r' Regular file
2211 's' Socket
2213 'h' Shadow inode (Solaris)
2215 'w' Whiteout inode (BSD)
2217 'u' Unknown file type
2219 This function depends on the feature "libtsk". See also
2221 "$g->feature-available".
2222 $g->fill ($c, $len, $path);
2224 This command creates a new file called "path". The initial content
2225 of the file is "len" octets of "c", where "c" must be a number in
2226 the range "[0..255]".
2227 To fill a file with zero bytes (sparsely), it is much more
2229 efficient to use "$g->truncate_size". To create a file with a
2230 pattern of repeating bytes use "$g->fill_pattern".
2231 $g->fill_dir ($dir, $nr);
2233 This function, useful for testing filesystems, creates "nr" empty
2234 files in the directory "dir" with names 00000000 through "nr-1"
2235 (ie. each file name is 8 digits long padded with zeroes).
2236 $g->fill_pattern ($pattern, $len, $path);
2238 This function is like "$g->fill" except that it creates a new file
2239 of length "len" containing the repeating pattern of bytes in
2240 "pattern". The pattern is truncated if necessary to ensure the
2241 length of the file is exactly "len" bytes.
2242 @names = $g->find ($directory);
2244 This command lists out all files and directories, recursively,
2245 starting at directory. It is essentially equivalent to running the
2246 shell command "find directory -print" but some post-processing
2247 happens on the output, described below.
2248 This returns a list of strings without any prefix. Thus if the
2250 directory structure was:
2251 /tmp/a
2253 /tmp/b
2254 /tmp/c/d
2255 then the returned list from "$g->find" /tmp would be 4 elements:
2257 a
2259 b
2260 c
2261 c/d
2262 If directory is not a directory, then this command returns an
2264 error.
2265 The returned list is sorted.
2267 $g->find0 ($directory, $files);
2269 This command lists out all files and directories, recursively,
2270 starting at directory, placing the resulting list in the external
2271 file called files.
2272 This command works the same way as "$g->find" with the following
2274 exceptions:
2275 · The resulting list is written to an external file.
2277 · Items (filenames) in the result are separated by "\0"
2279 characters. See find(1) option -print0.
2280 · The result list is not sorted.
2282 @dirents = $g->find_inode ($device, $inode);
2284 Searches all the entries associated with the given inode.
2285 For each entry, a "tsk_dirent" structure is returned. See
2287 "filesystem_walk" for more information about "tsk_dirent"
2288 structures.
2289 This function depends on the feature "libtsk". See also
2291 "$g->feature-available".
2292 $device = $g->findfs_label ($label);
2294 This command searches the filesystems and returns the one which has
2295 the given label. An error is returned if no such filesystem can be
2296 found.
2297 To find the label of a filesystem, use "$g->vfs_label".
2299 $device = $g->findfs_uuid ($uuid);
2301 This command searches the filesystems and returns the one which has
2302 the given UUID. An error is returned if no such filesystem can be
2303 found.
2304 To find the UUID of a filesystem, use "$g->vfs_uuid".
2306 $status = $g->fsck ($fstype, $device);
2308 This runs the filesystem checker (fsck) on "device" which should
2309 have filesystem type "fstype".
2310 The returned integer is the status. See fsck(8) for the list of
2312 status codes from "fsck".
2313 Notes:
2315 · Multiple status codes can be summed together.
2317 · A non-zero return code can mean "success", for example if
2319 errors have been corrected on the filesystem.
2320 · Checking or repairing NTFS volumes is not supported (by linux-
2322 ntfs).
2323 This command is entirely equivalent to running "fsck -a -t fstype
2325 device".
2326 $g->fstrim ($mountpoint [, offset => $offset] [, length => $length] [,
2328 minimumfreeextent => $minimumfreeextent]);
2329 Trim the free space in the filesystem mounted on "mountpoint". The
2330 filesystem must be mounted read-write.
2331 The filesystem contents are not affected, but any free space in the
2333 filesystem is "trimmed", that is, given back to the host device,
2334 thus making disk images more sparse, allowing unused space in qcow2
2335 files to be reused, etc.
2336 This operation requires support in libguestfs, the mounted
2338 filesystem, the host filesystem, qemu and the host kernel. If this
2339 support isn't present it may give an error or even appear to run
2340 but do nothing.
2341 In the case where the kernel vfs driver does not support trimming,
2343 this call will fail with errno set to "ENOTSUP". Currently this
2344 happens when trying to trim FAT filesystems.
2345 See also "$g->zero_free_space". That is a slightly different
2347 operation that turns free space in the filesystem into zeroes. It
2348 is valid to call "$g->fstrim" either instead of, or after calling
2349 "$g->zero_free_space".
2350 This function depends on the feature "fstrim". See also
2352 "$g->feature-available".
2353 $append = $g->get_append ();
2355 Return the additional kernel options which are added to the
2356 libguestfs appliance kernel command line.
2357 If "NULL" then no options are added.
2359 $backend = $g->get_attach_method ();
2361 Return the current backend.
2362 See "$g->set_backend" and "BACKEND" in guestfs(3).
2364 This function is deprecated. In new code, use the "get_backend"
2366 call instead.
2367 Deprecated functions will not be removed from the API, but the fact
2369 that they are deprecated indicates that there are problems with
2370 correct use of these functions.
2371 $autosync = $g->get_autosync ();
2373 Get the autosync flag.
2374 $backend = $g->get_backend ();
2376 Return the current backend.
2377 This handle property was previously called the "attach method".
2379 See "$g->set_backend" and "BACKEND" in guestfs(3).
2381 $val = $g->get_backend_setting ($name);
2383 Find a backend setting string which is either "name" or begins with
2384 "name=". If "name", this returns the string "1". If "name=", this
2385 returns the part after the equals sign (which may be an empty
2386 string).
2387 If no such setting is found, this function throws an error. The
2389 errno (see "$g->last_errno") will be "ESRCH" in this case.
2390 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
2392 @settings = $g->get_backend_settings ();
2394 Return the current backend settings.
2395 This call returns all backend settings strings. If you want to
2397 find a single backend setting, see "$g->get_backend_setting".
2398 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
2400 $cachedir = $g->get_cachedir ();
2402 Get the directory used by the handle to store the appliance cache.
2403 $direct = $g->get_direct ();
2405 Return the direct appliance mode flag.
2406 This function is deprecated. In new code, use the
2408 "internal_get_console_socket" call instead.
2409 Deprecated functions will not be removed from the API, but the fact
2411 that they are deprecated indicates that there are problems with
2412 correct use of these functions.
2413 $attrs = $g->get_e2attrs ($file);
2415 This returns the file attributes associated with file.
2416 The attributes are a set of bits associated with each inode which
2418 affect the behaviour of the file. The attributes are returned as a
2419 string of letters (described below). The string may be empty,
2420 indicating that no file attributes are set for this file.
2421 These attributes are only present when the file is located on an
2423 ext2/3/4 filesystem. Using this call on other filesystem types
2424 will result in an error.
2425 The characters (file attributes) in the returned string are
2427 currently:
2428 'A' When the file is accessed, its atime is not modified.
2430 'a' The file is append-only.
2432 'c' The file is compressed on-disk.
2434 'D' (Directories only.) Changes to this directory are written
2436 synchronously to disk.
2437 'd' The file is not a candidate for backup (see dump(8)).
2439 'E' The file has compression errors.
2441 'e' The file is using extents.
2443 'h' The file is storing its blocks in units of the filesystem
2445 blocksize instead of sectors.
2446 'I' (Directories only.) The directory is using hashed trees.
2448 'i' The file is immutable. It cannot be modified, deleted or
2450 renamed. No link can be created to this file.
2451 'j' The file is data-journaled.
2453 's' When the file is deleted, all its blocks will be zeroed.
2455 'S' Changes to this file are written synchronously to disk.
2457 'T' (Directories only.) This is a hint to the block allocator that
2459 subdirectories contained in this directory should be spread
2460 across blocks. If not present, the block allocator will try to
2461 group subdirectories together.
2462 't' For a file, this disables tail-merging. (Not used by upstream
2464 implementations of ext2.)
2465 'u' When the file is deleted, its blocks will be saved, allowing
2467 the file to be undeleted.
2468 'X' The raw contents of the compressed file may be accessed.
2470 'Z' The compressed file is dirty.
2472 More file attributes may be added to this list later. Not all file
2474 attributes may be set for all kinds of files. For detailed
2475 information, consult the chattr(1) man page.
2476 See also "$g->set_e2attrs".
2478 Don't confuse these attributes with extended attributes (see
2480 "$g->getxattr").
2481 $generation = $g->get_e2generation ($file);
2483 This returns the ext2 file generation of a file. The generation
2484 (which used to be called the "version") is a number associated with
2485 an inode. This is most commonly used by NFS servers.
2486 The generation is only present when the file is located on an
2488 ext2/3/4 filesystem. Using this call on other filesystem types
2489 will result in an error.
2490 See "$g->set_e2generation".
2492 $label = $g->get_e2label ($device);
2494 This returns the ext2/3/4 filesystem label of the filesystem on
2495 "device".
2496 This function is deprecated. In new code, use the "vfs_label" call
2498 instead.
2499 Deprecated functions will not be removed from the API, but the fact
2501 that they are deprecated indicates that there are problems with
2502 correct use of these functions.
2503 $uuid = $g->get_e2uuid ($device);
2505 This returns the ext2/3/4 filesystem UUID of the filesystem on
2506 "device".
2507 This function is deprecated. In new code, use the "vfs_uuid" call
2509 instead.
2510 Deprecated functions will not be removed from the API, but the fact
2512 that they are deprecated indicates that there are problems with
2513 correct use of these functions.
2514 $hv = $g->get_hv ();
2516 Return the current hypervisor binary.
2517 This is always non-NULL. If it wasn't set already, then this will
2519 return the default qemu binary name.
2520 $identifier = $g->get_identifier ();
2522 Get the handle identifier. See "$g->set_identifier".
2523 $challenge = $g->get_libvirt_requested_credential_challenge ($index);
2525 Get the challenge (provided by libvirt) for the "index"'th
2526 requested credential. If libvirt did not provide a challenge, this
2527 returns the empty string "".
2528 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2530 example code.
2531 $defresult = $g->get_libvirt_requested_credential_defresult ($index);
2533 Get the default result (provided by libvirt) for the "index"'th
2534 requested credential. If libvirt did not provide a default result,
2535 this returns the empty string "".
2536 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2538 example code.
2539 $prompt = $g->get_libvirt_requested_credential_prompt ($index);
2541 Get the prompt (provided by libvirt) for the "index"'th requested
2542 credential. If libvirt did not provide a prompt, this returns the
2543 empty string "".
2544 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2546 example code.
2547 @creds = $g->get_libvirt_requested_credentials ();
2549 This should only be called during the event callback for events of
2550 type "GUESTFS_EVENT_LIBVIRT_AUTH".
2551 Return the list of credentials requested by libvirt. Possible
2553 values are a subset of the strings provided when you called
2554 "$g->set_libvirt_supported_credentials".
2555 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2557 example code.
2558 $memsize = $g->get_memsize ();
2560 This gets the memory size in megabytes allocated to the hypervisor.
2561 If "$g->set_memsize" was not called on this handle, and if
2563 "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
2564 default value for memsize.
2565 For more information on the architecture of libguestfs, see
2567 guestfs(3).
2568 $network = $g->get_network ();
2570 This returns the enable network flag.
2571 $path = $g->get_path ();
2573 Return the current search path.
2574 This is always non-NULL. If it wasn't set already, then this will
2576 return the default path.
2577 $pgroup = $g->get_pgroup ();
2579 This returns the process group flag.
2580 $pid = $g->get_pid ();
2582 Return the process ID of the hypervisor. If there is no hypervisor
2583 running, then this will return an error.
2584 This is an internal call used for debugging and testing.
2586 $program = $g->get_program ();
2588 Get the program name. See "$g->set_program".
2589 $hv = $g->get_qemu ();
2591 Return the current hypervisor binary (usually qemu).
2592 This is always non-NULL. If it wasn't set already, then this will
2594 return the default qemu binary name.
2595 This function is deprecated. In new code, use the "get_hv" call
2597 instead.
2598 Deprecated functions will not be removed from the API, but the fact
2600 that they are deprecated indicates that there are problems with
2601 correct use of these functions.
2602 $recoveryproc = $g->get_recovery_proc ();
2604 Return the recovery process enabled flag.
2605 $selinux = $g->get_selinux ();
2607 This returns the current setting of the selinux flag which is
2608 passed to the appliance at boot time. See "$g->set_selinux".
2609 For more information on the architecture of libguestfs, see
2611 guestfs(3).
2612 This function is deprecated. In new code, use the
2614 "selinux_relabel" call instead.
2615 Deprecated functions will not be removed from the API, but the fact
2617 that they are deprecated indicates that there are problems with
2618 correct use of these functions.
2619 $smp = $g->get_smp ();
2621 This returns the number of virtual CPUs assigned to the appliance.
2622 $sockdir = $g->get_sockdir ();
2624 Get the directory used by the handle to store temporary socket
2625 files.
2626 This is different from "$g->tmpdir", as we need shorter paths for
2628 sockets (due to the limited buffers of filenames for UNIX sockets),
2629 and "$g->tmpdir" may be too long for them.
2630 The environment variable "XDG_RUNTIME_DIR" controls the default
2632 value: If "XDG_RUNTIME_DIR" is set, then that is the default. Else
2633 /tmp is the default.
2634 $state = $g->get_state ();
2636 This returns the current state as an opaque integer. This is only
2637 useful for printing debug and internal error messages.
2638 For more information on states, see guestfs(3).
2640 $tmpdir = $g->get_tmpdir ();
2642 Get the directory used by the handle to store temporary files.
2643 $trace = $g->get_trace ();
2645 Return the command trace flag.
2646 $mask = $g->get_umask ();
2648 Return the current umask. By default the umask is 022 unless it
2649 has been set by calling "$g->umask".
2650 $verbose = $g->get_verbose ();
2652 This returns the verbose messages flag.
2653 $context = $g->getcon ();
2655 This gets the SELinux security context of the daemon.
2656 See the documentation about SELINUX in guestfs(3), and "$g->setcon"
2658 This function depends on the feature "selinux". See also
2660 "$g->feature-available".
2661 This function is deprecated. In new code, use the
2663 "selinux_relabel" call instead.
2664 Deprecated functions will not be removed from the API, but the fact
2666 that they are deprecated indicates that there are problems with
2667 correct use of these functions.
2668 $xattr = $g->getxattr ($path, $name);
2670 Get a single extended attribute from file "path" named "name".
2671 This call follows symlinks. If you want to lookup an extended
2672 attribute for the symlink itself, use "$g->lgetxattr".
2673 Normally it is better to get all extended attributes from a file in
2675 one go by calling "$g->getxattrs". However some Linux filesystem
2676 implementations are buggy and do not provide a way to list out
2677 attributes. For these filesystems (notably ntfs-3g) you have to
2678 know the names of the extended attributes you want in advance and
2679 call this function.
2680 Extended attribute values are blobs of binary data. If there is no
2682 extended attribute named "name", this returns an error.
2683 See also: "$g->getxattrs", "$g->lgetxattr", attr(5).
2685 This function depends on the feature "linuxxattrs". See also
2687 "$g->feature-available".
2688 @xattrs = $g->getxattrs ($path);
2690 This call lists the extended attributes of the file or directory
2691 "path".
2692 At the system call level, this is a combination of the listxattr(2)
2694 and getxattr(2) calls.
2695 See also: "$g->lgetxattrs", attr(5).
2697 This function depends on the feature "linuxxattrs". See also
2699 "$g->feature-available".
2700 @paths = $g->glob_expand ($pattern [, directoryslash =>
2702 $directoryslash]);
2703 This command searches for all the pathnames matching "pattern"
2704 according to the wildcard expansion rules used by the shell.
2705 If no paths match, then this returns an empty list (note: not an
2707 error).
2708 It is just a wrapper around the C glob(3) function with flags
2710 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
2711 "directoryslash" controls whether use the "GLOB_MARK" flag for
2713 glob(3), and it defaults to true. It can be explicitly set as off
2714 to return no trailing slashes in filenames of directories.
2715 Notice that there is no equivalent command for expanding a device
2717 name (eg. /dev/sd*). Use "$g->list_devices", "$g->list_partitions"
2718 etc functions instead.
2719 @paths = $g->glob_expand_opts ($pattern [, directoryslash =>
2721 $directoryslash]);
2722 This is an alias of "glob_expand".
2723 @lines = $g->grep ($regex, $path [, extended => $extended] [, fixed =>
2725 $fixed] [, insensitive => $insensitive] [, compressed => $compressed]);
2726 This calls the external "grep" program and returns the matching
2727 lines.
2728 The optional flags are:
2730 "extended"
2732 Use extended regular expressions. This is the same as using
2733 the -E flag.
2734 "fixed"
2736 Match fixed (don't use regular expressions). This is the same
2737 as using the -F flag.
2738 "insensitive"
2740 Match case-insensitive. This is the same as using the -i flag.
2741 "compressed"
2743 Use "zgrep" instead of "grep". This allows the input to be
2744 compress- or gzip-compressed.
2745 Because of the message protocol, there is a transfer limit of
2747 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2748 guestfs(3).
2749 @lines = $g->grep_opts ($regex, $path [, extended => $extended] [,
2751 fixed => $fixed] [, insensitive => $insensitive] [, compressed =>
2752 $compressed]);
2753 This is an alias of "grep".
2754 @lines = $g->grepi ($regex, $path);
2756 This calls the external "grep -i" program and returns the matching
2757 lines.
2758 Because of the message protocol, there is a transfer limit of
2760 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2761 guestfs(3).
2762 This function is deprecated. In new code, use the "grep" call
2764 instead.
2765 Deprecated functions will not be removed from the API, but the fact
2767 that they are deprecated indicates that there are problems with
2768 correct use of these functions.
2769 $g->grub_install ($root, $device);
2771 This command installs GRUB 1 (the Grand Unified Bootloader) on
2772 "device", with the root directory being "root".
2773 Notes:
2775 · There is currently no way in the API to install grub2, which is
2777 used by most modern Linux guests. It is possible to run the
2778 grub2 command from the guest, although see the caveats in
2779 "RUNNING COMMANDS" in guestfs(3).
2780 · This uses "grub-install" from the host. Unfortunately grub is
2782 not always compatible with itself, so this only works in rather
2783 narrow circumstances. Careful testing with each guest version
2784 is advisable.
2785 · If grub-install reports the error "No suitable drive was found
2787 in the generated device map." it may be that you need to
2788 create a /boot/grub/device.map file first that contains the
2789 mapping between grub device names and Linux device names. It
2790 is usually sufficient to create a file containing:
2791 (hd0) /dev/vda
2793 replacing /dev/vda with the name of the installation device.
2795 This function depends on the feature "grub". See also
2797 "$g->feature-available".
2798 @lines = $g->head ($path);
2800 This command returns up to the first 10 lines of a file as a list
2801 of strings.
2802 Because of the message protocol, there is a transfer limit of
2804 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2805 guestfs(3).
2806 @lines = $g->head_n ($nrlines, $path);
2808 If the parameter "nrlines" is a positive number, this returns the
2809 first "nrlines" lines of the file "path".
2810 If the parameter "nrlines" is a negative number, this returns lines
2812 from the file "path", excluding the last "nrlines" lines.
2813 If the parameter "nrlines" is zero, this returns an empty list.
2815 Because of the message protocol, there is a transfer limit of
2817 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2818 guestfs(3).
2819 $dump = $g->hexdump ($path);
2821 This runs "hexdump -C" on the given "path". The result is the
2822 human-readable, canonical hex dump of the file.
2823 Because of the message protocol, there is a transfer limit of
2825 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2826 guestfs(3).
2827 $g->hivex_close ();
2829 Close the current hivex handle.
2830 This is a wrapper around the hivex(3) call of the same name.
2832 This function depends on the feature "hivex". See also
2834 "$g->feature-available".
2835 $g->hivex_commit ($filename);
2837 Commit (write) changes to the hive.
2838 If the optional filename parameter is null, then the changes are
2840 written back to the same hive that was opened. If this is not null
2841 then they are written to the alternate filename given and the
2842 original hive is left untouched.
2843 This is a wrapper around the hivex(3) call of the same name.
2845 This function depends on the feature "hivex". See also
2847 "$g->feature-available".
2848 $nodeh = $g->hivex_node_add_child ($parent, $name);
2850 Add a child node to "parent" named "name".
2851 This is a wrapper around the hivex(3) call of the same name.
2853 This function depends on the feature "hivex". See also
2855 "$g->feature-available".
2856 @nodehs = $g->hivex_node_children ($nodeh);
2858 Return the list of nodes which are subkeys of "nodeh".
2859 This is a wrapper around the hivex(3) call of the same name.
2861 This function depends on the feature "hivex". See also
2863 "$g->feature-available".
2864 $g->hivex_node_delete_child ($nodeh);
2866 Delete "nodeh", recursively if necessary.
2867 This is a wrapper around the hivex(3) call of the same name.
2869 This function depends on the feature "hivex". See also
2871 "$g->feature-available".
2872 $child = $g->hivex_node_get_child ($nodeh, $name);
2874 Return the child of "nodeh" with the name "name", if it exists.
2875 This can return 0 meaning the name was not found.
2876 This is a wrapper around the hivex(3) call of the same name.
2878 This function depends on the feature "hivex". See also
2880 "$g->feature-available".
2881 $valueh = $g->hivex_node_get_value ($nodeh, $key);
2883 Return the value attached to "nodeh" which has the name "key", if
2884 it exists. This can return 0 meaning the key was not found.
2885 This is a wrapper around the hivex(3) call of the same name.
2887 This function depends on the feature "hivex". See also
2889 "$g->feature-available".
2890 $name = $g->hivex_node_name ($nodeh);
2892 Return the name of "nodeh".
2893 This is a wrapper around the hivex(3) call of the same name.
2895 This function depends on the feature "hivex". See also
2897 "$g->feature-available".
2898 $parent = $g->hivex_node_parent ($nodeh);
2900 Return the parent node of "nodeh".
2901 This is a wrapper around the hivex(3) call of the same name.
2903 This function depends on the feature "hivex". See also
2905 "$g->feature-available".
2906 $g->hivex_node_set_value ($nodeh, $key, $t, $val);
2908 Set or replace a single value under the node "nodeh". The "key" is
2909 the name, "t" is the type, and "val" is the data.
2910 This is a wrapper around the hivex(3) call of the same name.
2912 This function depends on the feature "hivex". See also
2914 "$g->feature-available".
2915 @valuehs = $g->hivex_node_values ($nodeh);
2917 Return the array of (key, datatype, data) tuples attached to
2918 "nodeh".
2919 This is a wrapper around the hivex(3) call of the same name.
2921 This function depends on the feature "hivex". See also
2923 "$g->feature-available".
2924 $g->hivex_open ($filename [, verbose => $verbose] [, debug => $debug]
2926 [, write => $write] [, unsafe => $unsafe]);
2927 Open the Windows Registry hive file named filename. If there was
2928 any previous hivex handle associated with this guestfs session,
2929 then it is closed.
2930 This is a wrapper around the hivex(3) call of the same name.
2932 This function depends on the feature "hivex". See also
2934 "$g->feature-available".
2935 $nodeh = $g->hivex_root ();
2937 Return the root node of the hive.
2938 This is a wrapper around the hivex(3) call of the same name.
2940 This function depends on the feature "hivex". See also
2942 "$g->feature-available".
2943 $key = $g->hivex_value_key ($valueh);
2945 Return the key (name) field of a (key, datatype, data) tuple.
2946 This is a wrapper around the hivex(3) call of the same name.
2948 This function depends on the feature "hivex". See also
2950 "$g->feature-available".
2951 $databuf = $g->hivex_value_string ($valueh);
2953 This calls "$g->hivex_value_value" (which returns the data field
2954 from a hivex value tuple). It then assumes that the field is a
2955 UTF-16LE string and converts the result to UTF-8 (or if this is not
2956 possible, it returns an error).
2957 This is useful for reading strings out of the Windows registry.
2959 However it is not foolproof because the registry is not strongly-
2960 typed and fields can contain arbitrary or unexpected data.
2961 This function depends on the feature "hivex". See also
2963 "$g->feature-available".
2964 $datatype = $g->hivex_value_type ($valueh);
2966 Return the data type field from a (key, datatype, data) tuple.
2967 This is a wrapper around the hivex(3) call of the same name.
2969 This function depends on the feature "hivex". See also
2971 "$g->feature-available".
2972 $databuf = $g->hivex_value_utf8 ($valueh);
2974 This calls "$g->hivex_value_value" (which returns the data field
2975 from a hivex value tuple). It then assumes that the field is a
2976 UTF-16LE string and converts the result to UTF-8 (or if this is not
2977 possible, it returns an error).
2978 This is useful for reading strings out of the Windows registry.
2980 However it is not foolproof because the registry is not strongly-
2981 typed and fields can contain arbitrary or unexpected data.
2982 This function depends on the feature "hivex". See also
2984 "$g->feature-available".
2985 This function is deprecated. In new code, use the
2987 "hivex_value_string" call instead.
2988 Deprecated functions will not be removed from the API, but the fact
2990 that they are deprecated indicates that there are problems with
2991 correct use of these functions.
2992 $databuf = $g->hivex_value_value ($valueh);
2994 Return the data field of a (key, datatype, data) tuple.
2995 This is a wrapper around the hivex(3) call of the same name.
2997 See also: "$g->hivex_value_utf8".
2999 This function depends on the feature "hivex". See also
3001 "$g->feature-available".
3002 $content = $g->initrd_cat ($initrdpath, $filename);
3004 This command unpacks the file filename from the initrd file called
3005 initrdpath. The filename must be given without the initial /
3006 character.
3007 For example, in guestfish you could use the following command to
3009 examine the boot script (usually called /init) contained in a Linux
3010 initrd or initramfs image:
3011 initrd-cat /boot/initrd-<version>.img init
3013 See also "$g->initrd_list".
3015 Because of the message protocol, there is a transfer limit of
3017 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
3018 guestfs(3).
3019 @filenames = $g->initrd_list ($path);
3021 This command lists out files contained in an initrd.
3022 The files are listed without any initial / character. The files
3024 are listed in the order they appear (not necessarily alphabetical).
3025 Directory names are listed as separate items.
3026 Old Linux kernels (2.4 and earlier) used a compressed ext2
3028 filesystem as initrd. We only support the newer initramfs format
3029 (compressed cpio files).
3030 $wd = $g->inotify_add_watch ($path, $mask);
3032 Watch "path" for the events listed in "mask".
3033 Note that if "path" is a directory then events within that
3035 directory are watched, but this does not happen recursively (in
3036 subdirectories).
3037 Note for non-C or non-Linux callers: the inotify events are defined
3039 by the Linux kernel ABI and are listed in
3040 /usr/include/sys/inotify.h.
3041 This function depends on the feature "inotify". See also
3043 "$g->feature-available".
3044 $g->inotify_close ();
3046 This closes the inotify handle which was previously opened by
3047 inotify_init. It removes all watches, throws away any pending
3048 events, and deallocates all resources.
3049 This function depends on the feature "inotify". See also
3051 "$g->feature-available".
3052 @paths = $g->inotify_files ();
3054 This function is a helpful wrapper around "$g->inotify_read" which
3055 just returns a list of pathnames of objects that were touched. The
3056 returned pathnames are sorted and deduplicated.
3057 This function depends on the feature "inotify". See also
3059 "$g->feature-available".
3060 $g->inotify_init ($maxevents);
3062 This command creates a new inotify handle. The inotify subsystem
3063 can be used to notify events which happen to objects in the guest
3064 filesystem.
3065 "maxevents" is the maximum number of events which will be queued up
3067 between calls to "$g->inotify_read" or "$g->inotify_files". If
3068 this is passed as 0, then the kernel (or previously set) default is
3069 used. For Linux 2.6.29 the default was 16384 events. Beyond this
3070 limit, the kernel throws away events, but records the fact that it
3071 threw them away by setting a flag "IN_Q_OVERFLOW" in the returned
3072 structure list (see "$g->inotify_read").
3073 Before any events are generated, you have to add some watches to
3075 the internal watch list. See: "$g->inotify_add_watch" and
3076 "$g->inotify_rm_watch".
3077 Queued up events should be read periodically by calling
3079 "$g->inotify_read" (or "$g->inotify_files" which is just a helpful
3080 wrapper around "$g->inotify_read"). If you don't read the events
3081 out often enough then you risk the internal queue overflowing.
3082 The handle should be closed after use by calling
3084 "$g->inotify_close". This also removes any watches automatically.
3085 See also inotify(7) for an overview of the inotify interface as
3087 exposed by the Linux kernel, which is roughly what we expose via
3088 libguestfs. Note that there is one global inotify handle per
3089 libguestfs instance.
3090 This function depends on the feature "inotify". See also
3092 "$g->feature-available".
3093 @events = $g->inotify_read ();
3095 Return the complete queue of events that have happened since the
3096 previous read call.
3097 If no events have happened, this returns an empty list.
3099 Note: In order to make sure that all events have been read, you
3101 must call this function repeatedly until it returns an empty list.
3102 The reason is that the call will read events up to the maximum
3103 appliance-to-host message size and leave remaining events in the
3104 queue.
3105 This function depends on the feature "inotify". See also
3107 "$g->feature-available".
3108 $g->inotify_rm_watch ($wd);
3110 Remove a previously defined inotify watch. See
3111 "$g->inotify_add_watch".
3112 This function depends on the feature "inotify". See also
3114 "$g->feature-available".
3115 $arch = $g->inspect_get_arch ($root);
3117 This returns the architecture of the inspected operating system.
3118 The possible return values are listed under
3119 "$g->file_architecture".
3120 If the architecture could not be determined, then the string
3122 "unknown" is returned.
3123 Please read "INSPECTION" in guestfs(3) for more details.
3125 $distro = $g->inspect_get_distro ($root);
3127 This returns the distro (distribution) of the inspected operating
3128 system.
3129 Currently defined distros are:
3131 "alpinelinux"
3133 Alpine Linux.
3134 "altlinux"
3136 ALT Linux.
3137 "archlinux"
3139 Arch Linux.
3140 "buildroot"
3142 Buildroot-derived distro, but not one we specifically
3143 recognize.
3144 "centos"
3146 CentOS.
3147 "cirros"
3149 Cirros.
3150 "coreos"
3152 CoreOS.
3153 "debian"
3155 Debian.
3156 "fedora"
3158 Fedora.
3159 "freebsd"
3161 FreeBSD.
3162 "freedos"
3164 FreeDOS.
3165 "frugalware"
3167 Frugalware.
3168 "gentoo"
3170 Gentoo.
3171 "kalilinux"
3173 Kali Linux.
3174 "linuxmint"
3176 Linux Mint.
3177 "mageia"
3179 Mageia.
3180 "mandriva"
3182 Mandriva.
3183 "meego"
3185 MeeGo.
3186 "msdos"
3188 Microsoft DOS.
3189 "neokylin"
3191 NeoKylin.
3192 "netbsd"
3194 NetBSD.
3195 "openbsd"
3197 OpenBSD.
3198 "opensuse"
3200 OpenSUSE.
3201 "oraclelinux"
3203 Oracle Linux.
3204 "pardus"
3206 Pardus.
3207 "pldlinux"
3209 PLD Linux.
3210 "redhat-based"
3212 Some Red Hat-derived distro.
3213 "rhel"
3215 Red Hat Enterprise Linux.
3216 "scientificlinux"
3218 Scientific Linux.
3219 "slackware"
3221 Slackware.
3222 "sles"
3224 SuSE Linux Enterprise Server or Desktop.
3225 "suse-based"
3227 Some openSuSE-derived distro.
3228 "ttylinux"
3230 ttylinux.
3231 "ubuntu"
3233 Ubuntu.
3234 "unknown"
3236 The distro could not be determined.
3237 "voidlinux"
3239 Void Linux.
3240 "windows"
3242 Windows does not have distributions. This string is returned
3243 if the OS type is Windows.
3244 Future versions of libguestfs may return other strings here. The
3246 caller should be prepared to handle any string.
3247 Please read "INSPECTION" in guestfs(3) for more details.
3249 %drives = $g->inspect_get_drive_mappings ($root);
3251 This call is useful for Windows which uses a primitive system of
3252 assigning drive letters (like C:\) to partitions. This inspection
3253 API examines the Windows Registry to find out how disks/partitions
3254 are mapped to drive letters, and returns a hash table as in the
3255 example below:
3256 C => /dev/vda2
3258 E => /dev/vdb1
3259 F => /dev/vdc1
3260 Note that keys are drive letters. For Windows, the key is case
3262 insensitive and just contains the drive letter, without the
3263 customary colon separator character.
3264 In future we may support other operating systems that also used
3266 drive letters, but the keys for those might not be case insensitive
3267 and might be longer than 1 character. For example in OS-9, hard
3268 drives were named "h0", "h1" etc.
3269 For Windows guests, currently only hard drive mappings are
3271 returned. Removable disks (eg. DVD-ROMs) are ignored.
3272 For guests that do not use drive mappings, or if the drive mappings
3274 could not be determined, this returns an empty hash table.
3275 Please read "INSPECTION" in guestfs(3) for more details. See also
3277 "$g->inspect_get_mountpoints", "$g->inspect_get_filesystems".
3278 @filesystems = $g->inspect_get_filesystems ($root);
3280 This returns a list of all the filesystems that we think are
3281 associated with this operating system. This includes the root
3282 filesystem, other ordinary filesystems, and non-mounted devices
3283 like swap partitions.
3284 In the case of a multi-boot virtual machine, it is possible for a
3286 filesystem to be shared between operating systems.
3287 Please read "INSPECTION" in guestfs(3) for more details. See also
3289 "$g->inspect_get_mountpoints".
3290 $format = $g->inspect_get_format ($root);
3292 Before libguestfs 1.38, there was some unreliable support for
3293 detecting installer CDs. This API would return:
3294 "installed"
3296 This is an installed operating system.
3297 "installer"
3299 The disk image being inspected is not an installed operating
3300 system, but a bootable install disk, live CD, or similar.
3301 "unknown"
3303 The format of this disk image is not known.
3304 In libguestfs X 1.38, this only returns "installed". Use libosinfo
3306 directly to detect installer CDs.
3307 Please read "INSPECTION" in guestfs(3) for more details.
3309 This function is deprecated. There is no replacement. Consult the
3311 API documentation in guestfs(3) for further information.
3312 Deprecated functions will not be removed from the API, but the fact
3314 that they are deprecated indicates that there are problems with
3315 correct use of these functions.
3316 $hostname = $g->inspect_get_hostname ($root);
3318 This function returns the hostname of the operating system as found
3319 by inspection of the guestXs configuration files.
3320 If the hostname could not be determined, then the string "unknown"
3322 is returned.
3323 Please read "INSPECTION" in guestfs(3) for more details.
3325 $icon = $g->inspect_get_icon ($root [, favicon => $favicon] [,
3327 highquality => $highquality]);
3328 This function returns an icon corresponding to the inspected
3329 operating system. The icon is returned as a buffer containing a
3330 PNG image (re-encoded to PNG if necessary).
3331 If it was not possible to get an icon this function returns a zero-
3333 length (non-NULL) buffer. Callers must check for this case.
3334 Libguestfs will start by looking for a file called /etc/favicon.png
3336 or C:\etc\favicon.png and if it has the correct format, the
3337 contents of this file will be returned. You can disable favicons
3338 by passing the optional "favicon" boolean as false (default is
3339 true).
3340 If finding the favicon fails, then we look in other places in the
3342 guest for a suitable icon.
3343 If the optional "highquality" boolean is true then only high
3345 quality icons are returned, which means only icons of high
3346 resolution with an alpha channel. The default (false) is to return
3347 any icon we can, even if it is of substandard quality.
3348 Notes:
3350 · Unlike most other inspection API calls, the guestXs disks must
3352 be mounted up before you call this, since it needs to read
3353 information from the guest filesystem during the call.
3354 · Security: The icon data comes from the untrusted guest, and
3356 should be treated with caution. PNG files have been known to
3357 contain exploits. Ensure that libpng (or other relevant
3358 libraries) are fully up to date before trying to process or
3359 display the icon.
3360 · The PNG image returned can be any size. It might not be
3362 square. Libguestfs tries to return the largest, highest
3363 quality icon available. The application must scale the icon to
3364 the required size.
3365 · Extracting icons from Windows guests requires the external
3367 "wrestool" program from the "icoutils" package, and several
3368 programs ("bmptopnm", "pnmtopng", "pamcut") from the "netpbm"
3369 package. These must be installed separately.
3370 · Operating system icons are usually trademarks. Seek legal
3372 advice before using trademarks in applications.
3373 $major = $g->inspect_get_major_version ($root);
3375 This returns the major version number of the inspected operating
3376 system.
3377 Windows uses a consistent versioning scheme which is not reflected
3379 in the popular public names used by the operating system. Notably
3380 the operating system known as "Windows 7" is really version 6.1
3381 (ie. major = 6, minor = 1). You can find out the real versions
3382 corresponding to releases of Windows by consulting Wikipedia or
3383 MSDN.
3384 If the version could not be determined, then 0 is returned.
3386 Please read "INSPECTION" in guestfs(3) for more details.
3388 $minor = $g->inspect_get_minor_version ($root);
3390 This returns the minor version number of the inspected operating
3391 system.
3392 If the version could not be determined, then 0 is returned.
3394 Please read "INSPECTION" in guestfs(3) for more details. See also
3396 "$g->inspect_get_major_version".
3397 %mountpoints = $g->inspect_get_mountpoints ($root);
3399 This returns a hash of where we think the filesystems associated
3400 with this operating system should be mounted. Callers should note
3401 that this is at best an educated guess made by reading
3402 configuration files such as /etc/fstab. In particular note that
3403 this may return filesystems which are non-existent or not mountable
3404 and callers should be prepared to handle or ignore failures if they
3405 try to mount them.
3406 Each element in the returned hashtable has a key which is the path
3408 of the mountpoint (eg. /boot) and a value which is the filesystem
3409 that would be mounted there (eg. /dev/sda1).
3410 Non-mounted devices such as swap devices are not returned in this
3412 list.
3413 For operating systems like Windows which still use drive letters,
3415 this call will only return an entry for the first drive "mounted
3416 on" /. For information about the mapping of drive letters to
3417 partitions, see "$g->inspect_get_drive_mappings".
3418 Please read "INSPECTION" in guestfs(3) for more details. See also
3420 "$g->inspect_get_filesystems".
3421 $id = $g->inspect_get_osinfo ($root);
3423 This function returns a possible short ID for libosinfo
3424 corresponding to the guest.
3425 Note: The returned ID is only a guess by libguestfs, and nothing
3427 ensures that it actually exists in osinfo-db.
3428 If no ID could not be determined, then the string "unknown" is
3430 returned.
3431 $packageformat = $g->inspect_get_package_format ($root);
3433 This function and "$g->inspect_get_package_management" return the
3434 package format and package management tool used by the inspected
3435 operating system. For example for Fedora these functions would
3436 return "rpm" (package format), and "yum" or "dnf" (package
3437 management).
3438 This returns the string "unknown" if we could not determine the
3440 package format or if the operating system does not have a real
3441 packaging system (eg. Windows).
3442 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
3444 "pkgsrc", "apk", "xbps". Future versions of libguestfs may return
3445 other strings.
3446 Please read "INSPECTION" in guestfs(3) for more details.
3448 $packagemanagement = $g->inspect_get_package_management ($root);
3450 "$g->inspect_get_package_format" and this function return the
3451 package format and package management tool used by the inspected
3452 operating system. For example for Fedora these functions would
3453 return "rpm" (package format), and "yum" or "dnf" (package
3454 management).
3455 This returns the string "unknown" if we could not determine the
3457 package management tool or if the operating system does not have a
3458 real packaging system (eg. Windows).
3459 Possible strings include: "yum", "dnf", "up2date", "apt" (for all
3461 Debian derivatives), "portage", "pisi", "pacman", "urpmi",
3462 "zypper", "apk", "xbps". Future versions of libguestfs may return
3463 other strings.
3464 Please read "INSPECTION" in guestfs(3) for more details.
3466 $product = $g->inspect_get_product_name ($root);
3468 This returns the product name of the inspected operating system.
3469 The product name is generally some freeform string which can be
3470 displayed to the user, but should not be parsed by programs.
3471 If the product name could not be determined, then the string
3473 "unknown" is returned.
3474 Please read "INSPECTION" in guestfs(3) for more details.
3476 $variant = $g->inspect_get_product_variant ($root);
3478 This returns the product variant of the inspected operating system.
3479 For Windows guests, this returns the contents of the Registry key
3481 "HKLM\Software\Microsoft\Windows NT\CurrentVersion"
3482 "InstallationType" which is usually a string such as "Client" or
3483 "Server" (other values are possible). This can be used to
3484 distinguish consumer and enterprise versions of Windows that have
3485 the same version number (for example, Windows 7 and Windows 2008
3486 Server are both version 6.1, but the former is "Client" and the
3487 latter is "Server").
3488 For enterprise Linux guests, in future we intend this to return the
3490 product variant such as "Desktop", "Server" and so on. But this is
3491 not implemented at present.
3492 If the product variant could not be determined, then the string
3494 "unknown" is returned.
3495 Please read "INSPECTION" in guestfs(3) for more details. See also
3497 "$g->inspect_get_product_name", "$g->inspect_get_major_version".
3498 @roots = $g->inspect_get_roots ();
3500 This function is a convenient way to get the list of root devices,
3501 as returned from a previous call to "$g->inspect_os", but without
3502 redoing the whole inspection process.
3503 This returns an empty list if either no root devices were found or
3505 the caller has not called "$g->inspect_os".
3506 Please read "INSPECTION" in guestfs(3) for more details.
3508 $name = $g->inspect_get_type ($root);
3510 This returns the type of the inspected operating system. Currently
3511 defined types are:
3512 "linux"
3514 Any Linux-based operating system.
3515 "windows"
3517 Any Microsoft Windows operating system.
3518 "freebsd"
3520 FreeBSD.
3521 "netbsd"
3523 NetBSD.
3524 "openbsd"
3526 OpenBSD.
3527 "hurd"
3529 GNU/Hurd.
3530 "dos"
3532 MS-DOS, FreeDOS and others.
3533 "minix"
3535 MINIX.
3536 "unknown"
3538 The operating system type could not be determined.
3539 Future versions of libguestfs may return other strings here. The
3541 caller should be prepared to handle any string.
3542 Please read "INSPECTION" in guestfs(3) for more details.
3544 $controlset = $g->inspect_get_windows_current_control_set ($root);
3546 This returns the Windows CurrentControlSet of the inspected guest.
3547 The CurrentControlSet is a registry key name such as
3548 "ControlSet001".
3549 This call assumes that the guest is Windows and that the Registry
3551 could be examined by inspection. If this is not the case then an
3552 error is returned.
3553 Please read "INSPECTION" in guestfs(3) for more details.
3555 $path = $g->inspect_get_windows_software_hive ($root);
3557 This returns the path to the hive (binary Windows Registry file)
3558 corresponding to HKLM\SOFTWARE.
3559 This call assumes that the guest is Windows and that the guest has
3561 a software hive file with the right name. If this is not the case
3562 then an error is returned. This call does not check that the hive
3563 is a valid Windows Registry hive.
3564 You can use "$g->hivex_open" to read or write to the hive.
3566 Please read "INSPECTION" in guestfs(3) for more details.
3568 $path = $g->inspect_get_windows_system_hive ($root);
3570 This returns the path to the hive (binary Windows Registry file)
3571 corresponding to HKLM\SYSTEM.
3572 This call assumes that the guest is Windows and that the guest has
3574 a system hive file with the right name. If this is not the case
3575 then an error is returned. This call does not check that the hive
3576 is a valid Windows Registry hive.
3577 You can use "$g->hivex_open" to read or write to the hive.
3579 Please read "INSPECTION" in guestfs(3) for more details.
3581 $systemroot = $g->inspect_get_windows_systemroot ($root);
3583 This returns the Windows systemroot of the inspected guest. The
3584 systemroot is a directory path such as /WINDOWS.
3585 This call assumes that the guest is Windows and that the systemroot
3587 could be determined by inspection. If this is not the case then an
3588 error is returned.
3589 Please read "INSPECTION" in guestfs(3) for more details.
3591 $live = $g->inspect_is_live ($root);
3593 This is deprecated and always returns "false".
3594 Please read "INSPECTION" in guestfs(3) for more details.
3596 This function is deprecated. There is no replacement. Consult the
3598 API documentation in guestfs(3) for further information.
3599 Deprecated functions will not be removed from the API, but the fact
3601 that they are deprecated indicates that there are problems with
3602 correct use of these functions.
3603 $multipart = $g->inspect_is_multipart ($root);
3605 This is deprecated and always returns "false".
3606 Please read "INSPECTION" in guestfs(3) for more details.
3608 This function is deprecated. There is no replacement. Consult the
3610 API documentation in guestfs(3) for further information.
3611 Deprecated functions will not be removed from the API, but the fact
3613 that they are deprecated indicates that there are problems with
3614 correct use of these functions.
3615 $netinst = $g->inspect_is_netinst ($root);
3617 This is deprecated and always returns "false".
3618 Please read "INSPECTION" in guestfs(3) for more details.
3620 This function is deprecated. There is no replacement. Consult the
3622 API documentation in guestfs(3) for further information.
3623 Deprecated functions will not be removed from the API, but the fact
3625 that they are deprecated indicates that there are problems with
3626 correct use of these functions.
3627 @applications = $g->inspect_list_applications ($root);
3629 Return the list of applications installed in the operating system.
3630 Note: This call works differently from other parts of the
3632 inspection API. You have to call "$g->inspect_os", then
3633 "$g->inspect_get_mountpoints", then mount up the disks, before
3634 calling this. Listing applications is a significantly more
3635 difficult operation which requires access to the full filesystem.
3636 Also note that unlike the other "$g->inspect_get_*" calls which are
3637 just returning data cached in the libguestfs handle, this call
3638 actually reads parts of the mounted filesystems during the call.
3639 This returns an empty list if the inspection code was not able to
3641 determine the list of applications.
3642 The application structure contains the following fields:
3644 "app_name"
3646 The name of the application. For Red Hat-derived and Debian-
3647 derived Linux guests, this is the package name.
3648 "app_display_name"
3650 The display name of the application, sometimes localized to the
3651 install language of the guest operating system.
3652 If unavailable this is returned as an empty string "". Callers
3654 needing to display something can use "app_name" instead.
3655 "app_epoch"
3657 For package managers which use epochs, this contains the epoch
3658 of the package (an integer). If unavailable, this is returned
3659 as 0.
3660 "app_version"
3662 The version string of the application or package. If
3663 unavailable this is returned as an empty string "".
3664 "app_release"
3666 The release string of the application or package, for package
3667 managers that use this. If unavailable this is returned as an
3668 empty string "".
3669 "app_install_path"
3671 The installation path of the application (on operating systems
3672 such as Windows which use installation paths). This path is in
3673 the format used by the guest operating system, it is not a
3674 libguestfs path.
3675 If unavailable this is returned as an empty string "".
3677 "app_trans_path"
3679 The install path translated into a libguestfs path. If
3680 unavailable this is returned as an empty string "".
3681 "app_publisher"
3683 The name of the publisher of the application, for package
3684 managers that use this. If unavailable this is returned as an
3685 empty string "".
3686 "app_url"
3688 The URL (eg. upstream URL) of the application. If unavailable
3689 this is returned as an empty string "".
3690 "app_source_package"
3692 For packaging systems which support this, the name of the
3693 source package. If unavailable this is returned as an empty
3694 string "".
3695 "app_summary"
3697 A short (usually one line) description of the application or
3698 package. If unavailable this is returned as an empty string
3699 "".
3700 "app_description"
3702 A longer description of the application or package. If
3703 unavailable this is returned as an empty string "".
3704 Please read "INSPECTION" in guestfs(3) for more details.
3706 This function is deprecated. In new code, use the
3708 "inspect_list_applications2" call instead.
3709 Deprecated functions will not be removed from the API, but the fact
3711 that they are deprecated indicates that there are problems with
3712 correct use of these functions.
3713 @applications2 = $g->inspect_list_applications2 ($root);
3715 Return the list of applications installed in the operating system.
3716 Note: This call works differently from other parts of the
3718 inspection API. You have to call "$g->inspect_os", then
3719 "$g->inspect_get_mountpoints", then mount up the disks, before
3720 calling this. Listing applications is a significantly more
3721 difficult operation which requires access to the full filesystem.
3722 Also note that unlike the other "$g->inspect_get_*" calls which are
3723 just returning data cached in the libguestfs handle, this call
3724 actually reads parts of the mounted filesystems during the call.
3725 This returns an empty list if the inspection code was not able to
3727 determine the list of applications.
3728 The application structure contains the following fields:
3730 "app2_name"
3732 The name of the application. For Red Hat-derived and Debian-
3733 derived Linux guests, this is the package name.
3734 "app2_display_name"
3736 The display name of the application, sometimes localized to the
3737 install language of the guest operating system.
3738 If unavailable this is returned as an empty string "". Callers
3740 needing to display something can use "app2_name" instead.
3741 "app2_epoch"
3743 For package managers which use epochs, this contains the epoch
3744 of the package (an integer). If unavailable, this is returned
3745 as 0.
3746 "app2_version"
3748 The version string of the application or package. If
3749 unavailable this is returned as an empty string "".
3750 "app2_release"
3752 The release string of the application or package, for package
3753 managers that use this. If unavailable this is returned as an
3754 empty string "".
3755 "app2_arch"
3757 The architecture string of the application or package, for
3758 package managers that use this. If unavailable this is
3759 returned as an empty string "".
3760 "app2_install_path"
3762 The installation path of the application (on operating systems
3763 such as Windows which use installation paths). This path is in
3764 the format used by the guest operating system, it is not a
3765 libguestfs path.
3766 If unavailable this is returned as an empty string "".
3768 "app2_trans_path"
3770 The install path translated into a libguestfs path. If
3771 unavailable this is returned as an empty string "".
3772 "app2_publisher"
3774 The name of the publisher of the application, for package
3775 managers that use this. If unavailable this is returned as an
3776 empty string "".
3777 "app2_url"
3779 The URL (eg. upstream URL) of the application. If unavailable
3780 this is returned as an empty string "".
3781 "app2_source_package"
3783 For packaging systems which support this, the name of the
3784 source package. If unavailable this is returned as an empty
3785 string "".
3786 "app2_summary"
3788 A short (usually one line) description of the application or
3789 package. If unavailable this is returned as an empty string
3790 "".
3791 "app2_description"
3793 A longer description of the application or package. If
3794 unavailable this is returned as an empty string "".
3795 Please read "INSPECTION" in guestfs(3) for more details.
3797 @roots = $g->inspect_os ();
3799 This function uses other libguestfs functions and certain
3800 heuristics to inspect the disk(s) (usually disks belonging to a
3801 virtual machine), looking for operating systems.
3802 The list returned is empty if no operating systems were found.
3804 If one operating system was found, then this returns a list with a
3806 single element, which is the name of the root filesystem of this
3807 operating system. It is also possible for this function to return
3808 a list containing more than one element, indicating a dual-boot or
3809 multi-boot virtual machine, with each element being the root
3810 filesystem of one of the operating systems.
3811 You can pass the root string(s) returned to other
3813 "$g->inspect_get_*" functions in order to query further information
3814 about each operating system, such as the name and version.
3815 This function uses other libguestfs features such as "$g->mount_ro"
3817 and "$g->umount_all" in order to mount and unmount filesystems and
3818 look at the contents. This should be called with no disks
3819 currently mounted. The function may also use Augeas, so any
3820 existing Augeas handle will be closed.
3821 This function cannot decrypt encrypted disks. The caller must do
3823 that first (supplying the necessary keys) if the disk is encrypted.
3824 Please read "INSPECTION" in guestfs(3) for more details.
3826 See also "$g->list_filesystems".
3828 $flag = $g->is_blockdev ($path [, followsymlinks => $followsymlinks]);
3830 This returns "true" if and only if there is a block device with the
3831 given "path" name.
3832 If the optional flag "followsymlinks" is true, then a symlink (or
3834 chain of symlinks) that ends with a block device also causes the
3835 function to return true.
3836 This call only looks at files within the guest filesystem.
3838 Libguestfs partitions and block devices (eg. /dev/sda) cannot be
3839 used as the "path" parameter of this call.
3840 See also "$g->stat".
3842 $flag = $g->is_blockdev_opts ($path [, followsymlinks =>
3844 $followsymlinks]);
3845 This is an alias of "is_blockdev".
3846 $busy = $g->is_busy ();
3848 This always returns false. This function is deprecated with no
3849 replacement. Do not use this function.
3850 For more information on states, see guestfs(3).
3852 $flag = $g->is_chardev ($path [, followsymlinks => $followsymlinks]);
3854 This returns "true" if and only if there is a character device with
3855 the given "path" name.
3856 If the optional flag "followsymlinks" is true, then a symlink (or
3858 chain of symlinks) that ends with a chardev also causes the
3859 function to return true.
3860 See also "$g->stat".
3862 $flag = $g->is_chardev_opts ($path [, followsymlinks =>
3864 $followsymlinks]);
3865 This is an alias of "is_chardev".
3866 $config = $g->is_config ();
3868 This returns true iff this handle is being configured (in the
3869 "CONFIG" state).
3870 For more information on states, see guestfs(3).
3872 $dirflag = $g->is_dir ($path [, followsymlinks => $followsymlinks]);
3874 This returns "true" if and only if there is a directory with the
3875 given "path" name. Note that it returns false for other objects
3876 like files.
3877 If the optional flag "followsymlinks" is true, then a symlink (or
3879 chain of symlinks) that ends with a directory also causes the
3880 function to return true.
3881 See also "$g->stat".
3883 $dirflag = $g->is_dir_opts ($path [, followsymlinks =>
3885 $followsymlinks]);
3886 This is an alias of "is_dir".
3887 $flag = $g->is_fifo ($path [, followsymlinks => $followsymlinks]);
3889 This returns "true" if and only if there is a FIFO (named pipe)
3890 with the given "path" name.
3891 If the optional flag "followsymlinks" is true, then a symlink (or
3893 chain of symlinks) that ends with a FIFO also causes the function
3894 to return true.
3895 See also "$g->stat".
3897 $flag = $g->is_fifo_opts ($path [, followsymlinks => $followsymlinks]);
3899 This is an alias of "is_fifo".
3900 $fileflag = $g->is_file ($path [, followsymlinks => $followsymlinks]);
3902 This returns "true" if and only if there is a regular file with the
3903 given "path" name. Note that it returns false for other objects
3904 like directories.
3905 If the optional flag "followsymlinks" is true, then a symlink (or
3907 chain of symlinks) that ends with a file also causes the function
3908 to return true.
3909 See also "$g->stat".
3911 $fileflag = $g->is_file_opts ($path [, followsymlinks =>
3913 $followsymlinks]);
3914 This is an alias of "is_file".
3915 $launching = $g->is_launching ();
3917 This returns true iff this handle is launching the subprocess (in
3918 the "LAUNCHING" state).
3919 For more information on states, see guestfs(3).
3921 $lvflag = $g->is_lv ($mountable);
3923 This command tests whether "mountable" is a logical volume, and
3924 returns true iff this is the case.
3925 $ready = $g->is_ready ();
3927 This returns true iff this handle is ready to accept commands (in
3928 the "READY" state).
3929 For more information on states, see guestfs(3).
3931 $flag = $g->is_socket ($path [, followsymlinks => $followsymlinks]);
3933 This returns "true" if and only if there is a Unix domain socket
3934 with the given "path" name.
3935 If the optional flag "followsymlinks" is true, then a symlink (or
3937 chain of symlinks) that ends with a socket also causes the function
3938 to return true.
3939 See also "$g->stat".
3941 $flag = $g->is_socket_opts ($path [, followsymlinks =>
3943 $followsymlinks]);
3944 This is an alias of "is_socket".
3945 $flag = $g->is_symlink ($path);
3947 This returns "true" if and only if there is a symbolic link with
3948 the given "path" name.
3949 See also "$g->stat".
3951 $flag = $g->is_whole_device ($device);
3953 This returns "true" if and only if "device" refers to a whole block
3954 device. That is, not a partition or a logical device.
3955 $zeroflag = $g->is_zero ($path);
3957 This returns true iff the file exists and the file is empty or it
3958 contains all zero bytes.
3959 $zeroflag = $g->is_zero_device ($device);
3961 This returns true iff the device exists and contains all zero
3962 bytes.
3963 Note that for large devices this can take a long time to run.
3965 %isodata = $g->isoinfo ($isofile);
3967 This is the same as "$g->isoinfo_device" except that it works for
3968 an ISO file located inside some other mounted filesystem. Note
3969 that in the common case where you have added an ISO file as a
3970 libguestfs device, you would not call this. Instead you would call
3971 "$g->isoinfo_device".
3972 %isodata = $g->isoinfo_device ($device);
3974 "device" is an ISO device. This returns a struct of information
3975 read from the primary volume descriptor (the ISO equivalent of the
3976 superblock) of the device.
3977 Usually it is more efficient to use the isoinfo(1) command with the
3979 -d option on the host to analyze ISO files, instead of going
3980 through libguestfs.
3981 For information on the primary volume descriptor fields, see
3983 <http://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor>
3984 $g->journal_close ();
3986 Close the journal handle.
3987 This function depends on the feature "journal". See also
3989 "$g->feature-available".
3990 @fields = $g->journal_get ();
3992 Read the current journal entry. This returns all the fields in the
3993 journal as a set of "(attrname, attrval)" pairs. The "attrname" is
3994 the field name (a string).
3995 The "attrval" is the field value (a binary blob, often but not
3997 always a string). Please note that "attrval" is a byte array, not
3998 a \0-terminated C string.
3999 The length of data may be truncated to the data threshold (see:
4001 "$g->journal_set_data_threshold",
4002 "$g->journal_get_data_threshold").
4003 If you set the data threshold to unlimited (0) then this call can
4005 read a journal entry of any size, ie. it is not limited by the
4006 libguestfs protocol.
4007 This function depends on the feature "journal". See also
4009 "$g->feature-available".
4010 $threshold = $g->journal_get_data_threshold ();
4012 Get the current data threshold for reading journal entries. This
4013 is a hint to the journal that it may truncate data fields to this
4014 size when reading them (note also that it may not truncate them).
4015 If this returns 0, then the threshold is unlimited.
4016 See also "$g->journal_set_data_threshold".
4018 This function depends on the feature "journal". See also
4020 "$g->feature-available".
4021 $usec = $g->journal_get_realtime_usec ();
4023 Get the realtime (wallclock) timestamp of the current journal
4024 entry.
4025 This function depends on the feature "journal". See also
4027 "$g->feature-available".
4028 $more = $g->journal_next ();
4030 Move to the next journal entry. You have to call this at least
4031 once after opening the handle before you are able to read data.
4032 The returned boolean tells you if there are any more journal
4034 records to read. "true" means you can read the next record (eg.
4035 using "$g->journal_get"), and "false" means you have reached the
4036 end of the journal.
4037 This function depends on the feature "journal". See also
4039 "$g->feature-available".
4040 $g->journal_open ($directory);
4042 Open the systemd journal located in directory. Any previously
4043 opened journal handle is closed.
4044 The contents of the journal can be read using "$g->journal_next"
4046 and "$g->journal_get".
4047 After you have finished using the journal, you should close the
4049 handle by calling "$g->journal_close".
4050 This function depends on the feature "journal". See also
4052 "$g->feature-available".
4053 $g->journal_set_data_threshold ($threshold);
4055 Set the data threshold for reading journal entries. This is a hint
4056 to the journal that it may truncate data fields to this size when
4057 reading them (note also that it may not truncate them). If you set
4058 this to 0, then the threshold is unlimited.
4059 See also "$g->journal_get_data_threshold".
4061 This function depends on the feature "journal". See also
4063 "$g->feature-available".
4064 $rskip = $g->journal_skip ($skip);
4066 Skip forwards ("skip X 0") or backwards ("skip < 0") in the
4067 journal.
4068 The number of entries actually skipped is returned (note
4070 "rskip X 0"). If this is not the same as the absolute value of the
4071 skip parameter ("|skip|") you passed in then it means you have
4072 reached the end or the start of the journal.
4073 This function depends on the feature "journal". See also
4075 "$g->feature-available".
4076 $g->kill_subprocess ();
4078 This kills the hypervisor.
4079 Do not call this. See: "$g->shutdown" instead.
4081 This function is deprecated. In new code, use the "shutdown" call
4083 instead.
4084 Deprecated functions will not be removed from the API, but the fact
4086 that they are deprecated indicates that there are problems with
4087 correct use of these functions.
4088 $g->launch ();
4090 You should call this after configuring the handle (eg. adding
4091 drives) but before performing any actions.
4092 Do not call "$g->launch" twice on the same handle. Although it
4094 will not give an error (for historical reasons), the precise
4095 behaviour when you do this is not well defined. Handles are very
4096 cheap to create, so create a new one for each launch.
4097 $g->lchown ($owner, $group, $path);
4099 Change the file owner to "owner" and group to "group". This is
4100 like "$g->chown" but if "path" is a symlink then the link itself is
4101 changed, not the target.
4102 Only numeric uid and gid are supported. If you want to use names,
4104 you will need to locate and parse the password file yourself
4105 (Augeas support makes this relatively easy).
4106 $g->ldmtool_create_all ();
4108 This function scans all block devices looking for Windows dynamic
4109 disk volumes and partitions, and creates devices for any that were
4110 found.
4111 Call "$g->list_ldm_volumes" and "$g->list_ldm_partitions" to return
4113 all devices.
4114 Note that you don't normally need to call this explicitly, since it
4116 is done automatically at "$g->launch" time. However you might want
4117 to call this function if you have hotplugged disks or have just
4118 created a Windows dynamic disk.
4119 This function depends on the feature "ldm". See also
4121 "$g->feature-available".
4122 @disks = $g->ldmtool_diskgroup_disks ($diskgroup);
4124 Return the disks in a Windows dynamic disk group. The "diskgroup"
4125 parameter should be the GUID of a disk group, one element from the
4126 list returned by "$g->ldmtool_scan".
4127 This function depends on the feature "ldm". See also
4129 "$g->feature-available".
4130 $name = $g->ldmtool_diskgroup_name ($diskgroup);
4132 Return the name of a Windows dynamic disk group. The "diskgroup"
4133 parameter should be the GUID of a disk group, one element from the
4134 list returned by "$g->ldmtool_scan".
4135 This function depends on the feature "ldm". See also
4137 "$g->feature-available".
4138 @volumes = $g->ldmtool_diskgroup_volumes ($diskgroup);
4140 Return the volumes in a Windows dynamic disk group. The
4141 "diskgroup" parameter should be the GUID of a disk group, one
4142 element from the list returned by "$g->ldmtool_scan".
4143 This function depends on the feature "ldm". See also
4145 "$g->feature-available".
4146 $g->ldmtool_remove_all ();
4148 This is essentially the opposite of "$g->ldmtool_create_all". It
4149 removes the device mapper mappings for all Windows dynamic disk
4150 volumes
4151 This function depends on the feature "ldm". See also
4153 "$g->feature-available".
4154 @guids = $g->ldmtool_scan ();
4156 This function scans for Windows dynamic disks. It returns a list
4157 of identifiers (GUIDs) for all disk groups that were found. These
4158 identifiers can be passed to other "$g->ldmtool_*" functions.
4159 This function scans all block devices. To scan a subset of block
4161 devices, call "$g->ldmtool_scan_devices" instead.
4162 This function depends on the feature "ldm". See also
4164 "$g->feature-available".
4165 @guids = $g->ldmtool_scan_devices (\@devices);
4167 This function scans for Windows dynamic disks. It returns a list
4168 of identifiers (GUIDs) for all disk groups that were found. These
4169 identifiers can be passed to other "$g->ldmtool_*" functions.
4170 The parameter "devices" is a list of block devices which are
4172 scanned. If this list is empty, all block devices are scanned.
4173 This function depends on the feature "ldm". See also
4175 "$g->feature-available".
4176 $hint = $g->ldmtool_volume_hint ($diskgroup, $volume);
4178 Return the hint field of the volume named "volume" in the disk
4179 group with GUID "diskgroup". This may not be defined, in which
4180 case the empty string is returned. The hint field is often, though
4181 not always, the name of a Windows drive, eg. "E:".
4182 This function depends on the feature "ldm". See also
4184 "$g->feature-available".
4185 @partitions = $g->ldmtool_volume_partitions ($diskgroup, $volume);
4187 Return the list of partitions in the volume named "volume" in the
4188 disk group with GUID "diskgroup".
4189 This function depends on the feature "ldm". See also
4191 "$g->feature-available".
4192 $voltype = $g->ldmtool_volume_type ($diskgroup, $volume);
4194 Return the type of the volume named "volume" in the disk group with
4195 GUID "diskgroup".
4196 Possible volume types that can be returned here include: "simple",
4198 "spanned", "striped", "mirrored", "raid5". Other types may also be
4199 returned.
4200 This function depends on the feature "ldm". See also
4202 "$g->feature-available".
4203 $xattr = $g->lgetxattr ($path, $name);
4205 Get a single extended attribute from file "path" named "name". If
4206 "path" is a symlink, then this call returns an extended attribute
4207 from the symlink.
4208 Normally it is better to get all extended attributes from a file in
4210 one go by calling "$g->getxattrs". However some Linux filesystem
4211 implementations are buggy and do not provide a way to list out
4212 attributes. For these filesystems (notably ntfs-3g) you have to
4213 know the names of the extended attributes you want in advance and
4214 call this function.
4215 Extended attribute values are blobs of binary data. If there is no
4217 extended attribute named "name", this returns an error.
4218 See also: "$g->lgetxattrs", "$g->getxattr", attr(5).
4220 This function depends on the feature "linuxxattrs". See also
4222 "$g->feature-available".
4223 @xattrs = $g->lgetxattrs ($path);
4225 This is the same as "$g->getxattrs", but if "path" is a symbolic
4226 link, then it returns the extended attributes of the link itself.
4227 This function depends on the feature "linuxxattrs". See also
4229 "$g->feature-available".
4230 @mounttags = $g->list_9p ();
4232 List all 9p filesystems attached to the guest. A list of mount
4233 tags is returned.
4234 @devices = $g->list_devices ();
4236 List all the block devices.
4237 The full block device names are returned, eg. /dev/sda.
4239 See also "$g->list_filesystems".
4241 %labels = $g->list_disk_labels ();
4243 If you add drives using the optional "label" parameter of
4244 "$g->add_drive_opts", you can use this call to map between disk
4245 labels, and raw block device and partition names (like /dev/sda and
4246 /dev/sda1).
4247 This returns a hashtable, where keys are the disk labels (without
4249 the /dev/disk/guestfs prefix), and the values are the full raw
4250 block device and partition names (eg. /dev/sda and /dev/sda1).
4251 @devices = $g->list_dm_devices ();
4253 List all device mapper devices.
4254 The returned list contains /dev/mapper/* devices, eg. ones created
4256 by a previous call to "$g->luks_open".
4257 Device mapper devices which correspond to logical volumes are not
4259 returned in this list. Call "$g->lvs" if you want to list logical
4260 volumes.
4261 %fses = $g->list_filesystems ();
4263 This inspection command looks for filesystems on partitions, block
4264 devices and logical volumes, returning a list of "mountables"
4265 containing filesystems and their type.
4266 The return value is a hash, where the keys are the devices
4268 containing filesystems, and the values are the filesystem types.
4269 For example:
4270 "/dev/sda1" => "ntfs"
4272 "/dev/sda2" => "ext2"
4273 "/dev/vg_guest/lv_root" => "ext4"
4274 "/dev/vg_guest/lv_swap" => "swap"
4275 The key is not necessarily a block device. It may also be an opaque
4277 XmountableX string which can be passed to "$g->mount".
4278 The value can have the special value "unknown", meaning the content
4280 of the device is undetermined or empty. "swap" means a Linux swap
4281 partition.
4282 In libguestfs X 1.36 this command ran other libguestfs commands,
4284 which might have included "$g->mount" and "$g->umount", and
4285 therefore you had to use this soon after launch and only when
4286 nothing else was mounted. This restriction is removed in
4287 libguestfs X 1.38.
4288 Not all of the filesystems returned will be mountable. In
4290 particular, swap partitions are returned in the list. Also this
4291 command does not check that each filesystem found is valid and
4292 mountable, and some filesystems might be mountable but require
4293 special options. Filesystems may not all belong to a single
4294 logical operating system (use "$g->inspect_os" to look for OSes).
4295 @devices = $g->list_ldm_partitions ();
4297 This function returns all Windows dynamic disk partitions that were
4298 found at launch time. It returns a list of device names.
4299 This function depends on the feature "ldm". See also
4301 "$g->feature-available".
4302 @devices = $g->list_ldm_volumes ();
4304 This function returns all Windows dynamic disk volumes that were
4305 found at launch time. It returns a list of device names.
4306 This function depends on the feature "ldm". See also
4308 "$g->feature-available".
4309 @devices = $g->list_md_devices ();
4311 List all Linux md devices.
4312 @partitions = $g->list_partitions ();
4314 List all the partitions detected on all block devices.
4315 The full partition device names are returned, eg. /dev/sda1
4317 This does not return logical volumes. For that you will need to
4319 call "$g->lvs".
4320 See also "$g->list_filesystems".
4322 $listing = $g->ll ($directory);
4324 List the files in directory (relative to the root directory, there
4325 is no cwd) in the format of 'ls -la'.
4326 This command is mostly useful for interactive sessions. It is not
4328 intended that you try to parse the output string.
4329 $listing = $g->llz ($directory);
4331 List the files in directory in the format of 'ls -laZ'.
4332 This command is mostly useful for interactive sessions. It is not
4334 intended that you try to parse the output string.
4335 This function is deprecated. In new code, use the "lgetxattrs"
4337 call instead.
4338 Deprecated functions will not be removed from the API, but the fact
4340 that they are deprecated indicates that there are problems with
4341 correct use of these functions.
4342 $g->ln ($target, $linkname);
4344 This command creates a hard link using the "ln" command.
4345 $g->ln_f ($target, $linkname);
4347 This command creates a hard link using the "ln -f" command. The -f
4348 option removes the link ("linkname") if it exists already.
4349 $g->ln_s ($target, $linkname);
4351 This command creates a symbolic link using the "ln -s" command.
4352 $g->ln_sf ($target, $linkname);
4354 This command creates a symbolic link using the "ln -sf" command,
4355 The -f option removes the link ("linkname") if it exists already.
4356 $g->lremovexattr ($xattr, $path);
4358 This is the same as "$g->removexattr", but if "path" is a symbolic
4359 link, then it removes an extended attribute of the link itself.
4360 This function depends on the feature "linuxxattrs". See also
4362 "$g->feature-available".
4363 @listing = $g->ls ($directory);
4365 List the files in directory (relative to the root directory, there
4366 is no cwd). The '.' and '..' entries are not returned, but hidden
4367 files are shown.
4368 $g->ls0 ($dir, $filenames);
4370 This specialized command is used to get a listing of the filenames
4371 in the directory "dir". The list of filenames is written to the
4372 local file filenames (on the host).
4373 In the output file, the filenames are separated by "\0" characters.
4375 "." and ".." are not returned. The filenames are not sorted.
4377 $g->lsetxattr ($xattr, $val, $vallen, $path);
4379 This is the same as "$g->setxattr", but if "path" is a symbolic
4380 link, then it sets an extended attribute of the link itself.
4381 This function depends on the feature "linuxxattrs". See also
4383 "$g->feature-available".
4384 %statbuf = $g->lstat ($path);
4386 Returns file information for the given "path".
4387 This is the same as "$g->stat" except that if "path" is a symbolic
4389 link, then the link is stat-ed, not the file it refers to.
4390 This is the same as the lstat(2) system call.
4392 This function is deprecated. In new code, use the "lstatns" call
4394 instead.
4395 Deprecated functions will not be removed from the API, but the fact
4397 that they are deprecated indicates that there are problems with
4398 correct use of these functions.
4399 @statbufs = $g->lstatlist ($path, \@names);
4401 This call allows you to perform the "$g->lstat" operation on
4402 multiple files, where all files are in the directory "path".
4403 "names" is the list of files from this directory.
4404 On return you get a list of stat structs, with a one-to-one
4406 correspondence to the "names" list. If any name did not exist or
4407 could not be lstat'd, then the "st_ino" field of that structure is
4408 set to "-1".
4409 This call is intended for programs that want to efficiently list a
4411 directory contents without making many round-trips. See also
4412 "$g->lxattrlist" for a similarly efficient call for getting
4413 extended attributes.
4414 This function is deprecated. In new code, use the "lstatnslist"
4416 call instead.
4417 Deprecated functions will not be removed from the API, but the fact
4419 that they are deprecated indicates that there are problems with
4420 correct use of these functions.
4421 %statbuf = $g->lstatns ($path);
4423 Returns file information for the given "path".
4424 This is the same as "$g->statns" except that if "path" is a
4426 symbolic link, then the link is stat-ed, not the file it refers to.
4427 This is the same as the lstat(2) system call.
4429 @statbufs = $g->lstatnslist ($path, \@names);
4431 This call allows you to perform the "$g->lstatns" operation on
4432 multiple files, where all files are in the directory "path".
4433 "names" is the list of files from this directory.
4434 On return you get a list of stat structs, with a one-to-one
4436 correspondence to the "names" list. If any name did not exist or
4437 could not be lstat'd, then the "st_ino" field of that structure is
4438 set to "-1".
4439 This call is intended for programs that want to efficiently list a
4441 directory contents without making many round-trips. See also
4442 "$g->lxattrlist" for a similarly efficient call for getting
4443 extended attributes.
4444 $g->luks_add_key ($device, $key, $newkey, $keyslot);
4446 This command adds a new key on LUKS device "device". "key" is any
4447 existing key, and is used to access the device. "newkey" is the
4448 new key to add. "keyslot" is the key slot that will be replaced.
4449 Note that if "keyslot" already contains a key, then this command
4451 will fail. You have to use "$g->luks_kill_slot" first to remove
4452 that key.
4453 This function depends on the feature "luks". See also
4455 "$g->feature-available".
4456 $g->luks_close ($device);
4458 This closes a LUKS device that was created earlier by
4459 "$g->luks_open" or "$g->luks_open_ro". The "device" parameter must
4460 be the name of the LUKS mapping device (ie. /dev/mapper/mapname)
4461 and not the name of the underlying block device.
4462 This function depends on the feature "luks". See also
4464 "$g->feature-available".
4465 $g->luks_format ($device, $key, $keyslot);
4467 This command erases existing data on "device" and formats the
4468 device as a LUKS encrypted device. "key" is the initial key, which
4469 is added to key slot "slot". (LUKS supports 8 key slots, numbered
4470 0-7).
4471 This function depends on the feature "luks". See also
4473 "$g->feature-available".
4474 $g->luks_format_cipher ($device, $key, $keyslot, $cipher);
4476 This command is the same as "$g->luks_format" but it also allows
4477 you to set the "cipher" used.
4478 This function depends on the feature "luks". See also
4480 "$g->feature-available".
4481 $g->luks_kill_slot ($device, $key, $keyslot);
4483 This command deletes the key in key slot "keyslot" from the
4484 encrypted LUKS device "device". "key" must be one of the other
4485 keys.
4486 This function depends on the feature "luks". See also
4488 "$g->feature-available".
4489 $g->luks_open ($device, $key, $mapname);
4491 This command opens a block device which has been encrypted
4492 according to the Linux Unified Key Setup (LUKS) standard.
4493 "device" is the encrypted block device or partition.
4495 The caller must supply one of the keys associated with the LUKS
4497 block device, in the "key" parameter.
4498 This creates a new block device called /dev/mapper/mapname. Reads
4500 and writes to this block device are decrypted from and encrypted to
4501 the underlying "device" respectively.
4502 If this block device contains LVM volume groups, then calling
4504 "$g->lvm_scan" with the "activate" parameter "true" will make them
4505 visible.
4506 Use "$g->list_dm_devices" to list all device mapper devices.
4508 This function depends on the feature "luks". See also
4510 "$g->feature-available".
4511 $g->luks_open_ro ($device, $key, $mapname);
4513 This is the same as "$g->luks_open" except that a read-only mapping
4514 is created.
4515 This function depends on the feature "luks". See also
4517 "$g->feature-available".
4518 $g->lvcreate ($logvol, $volgroup, $mbytes);
4520 This creates an LVM logical volume called "logvol" on the volume
4521 group "volgroup", with "size" megabytes.
4522 This function depends on the feature "lvm2". See also
4524 "$g->feature-available".
4525 $g->lvcreate_free ($logvol, $volgroup, $percent);
4527 Create an LVM logical volume called /dev/volgroup/logvol, using
4528 approximately "percent" % of the free space remaining in the volume
4529 group. Most usefully, when "percent" is 100 this will create the
4530 largest possible LV.
4531 This function depends on the feature "lvm2". See also
4533 "$g->feature-available".
4534 $lv = $g->lvm_canonical_lv_name ($lvname);
4536 This converts alternative naming schemes for LVs that you might
4537 find to the canonical name. For example, /dev/mapper/VG-LV is
4538 converted to /dev/VG/LV.
4539 This command returns an error if the "lvname" parameter does not
4541 refer to a logical volume.
4542 See also "$g->is_lv", "$g->canonical_device_name".
4544 $g->lvm_clear_filter ();
4546 This undoes the effect of "$g->lvm_set_filter". LVM will be able
4547 to see every block device.
4548 This command also clears the LVM cache and performs a volume group
4550 scan.
4551 $g->lvm_remove_all ();
4553 This command removes all LVM logical volumes, volume groups and
4554 physical volumes.
4555 This function depends on the feature "lvm2". See also
4557 "$g->feature-available".
4558 $g->lvm_scan ($activate);
4560 This scans all block devices and rebuilds the list of LVM physical
4561 volumes, volume groups and logical volumes.
4562 If the "activate" parameter is "true" then newly found volume
4564 groups and logical volumes are activated, meaning the LV /dev/VG/LV
4565 devices become visible.
4566 When a libguestfs handle is launched it scans for existing devices,
4568 so you do not normally need to use this API. However it is useful
4569 when you have added a new device or deleted an existing device
4570 (such as when the "$g->luks_open" API is used).
4571 $g->lvm_set_filter (\@devices);
4573 This sets the LVM device filter so that LVM will only be able to
4574 "see" the block devices in the list "devices", and will ignore all
4575 other attached block devices.
4576 Where disk image(s) contain duplicate PVs or VGs, this command is
4578 useful to get LVM to ignore the duplicates, otherwise LVM can get
4579 confused. Note also there are two types of duplication possible:
4580 either cloned PVs/VGs which have identical UUIDs; or VGs that are
4581 not cloned but just happen to have the same name. In normal
4582 operation you cannot create this situation, but you can do it
4583 outside LVM, eg. by cloning disk images or by bit twiddling inside
4584 the LVM metadata.
4585 This command also clears the LVM cache and performs a volume group
4587 scan.
4588 You can filter whole block devices or individual partitions.
4590 You cannot use this if any VG is currently in use (eg. contains a
4592 mounted filesystem), even if you are not filtering out that VG.
4593 This function depends on the feature "lvm2". See also
4595 "$g->feature-available".
4596 $g->lvremove ($device);
4598 Remove an LVM logical volume "device", where "device" is the path
4599 to the LV, such as /dev/VG/LV.
4600 You can also remove all LVs in a volume group by specifying the VG
4602 name, /dev/VG.
4603 This function depends on the feature "lvm2". See also
4605 "$g->feature-available".
4606 $g->lvrename ($logvol, $newlogvol);
4608 Rename a logical volume "logvol" with the new name "newlogvol".
4609 $g->lvresize ($device, $mbytes);
4611 This resizes (expands or shrinks) an existing LVM logical volume to
4612 "mbytes". When reducing, data in the reduced part is lost.
4613 This function depends on the feature "lvm2". See also
4615 "$g->feature-available".
4616 $g->lvresize_free ($lv, $percent);
4618 This expands an existing logical volume "lv" so that it fills "pc"%
4619 of the remaining free space in the volume group. Commonly you
4620 would call this with pc = 100 which expands the logical volume as
4621 much as possible, using all remaining free space in the volume
4622 group.
4623 This function depends on the feature "lvm2". See also
4625 "$g->feature-available".
4626 @logvols = $g->lvs ();
4628 List all the logical volumes detected. This is the equivalent of
4629 the lvs(8) command.
4630 This returns a list of the logical volume device names (eg.
4632 /dev/VolGroup00/LogVol00).
4633 See also "$g->lvs_full", "$g->list_filesystems".
4635 This function depends on the feature "lvm2". See also
4637 "$g->feature-available".
4638 @logvols = $g->lvs_full ();
4640 List all the logical volumes detected. This is the equivalent of
4641 the lvs(8) command. The "full" version includes all fields.
4642 This function depends on the feature "lvm2". See also
4644 "$g->feature-available".
4645 $uuid = $g->lvuuid ($device);
4647 This command returns the UUID of the LVM LV "device".
4648 @xattrs = $g->lxattrlist ($path, \@names);
4650 This call allows you to get the extended attributes of multiple
4651 files, where all files are in the directory "path". "names" is the
4652 list of files from this directory.
4653 On return you get a flat list of xattr structs which must be
4655 interpreted sequentially. The first xattr struct always has a
4656 zero-length "attrname". "attrval" in this struct is zero-length to
4657 indicate there was an error doing "lgetxattr" for this file, or is
4658 a C string which is a decimal number (the number of following
4659 attributes for this file, which could be "0"). Then after the
4660 first xattr struct are the zero or more attributes for the first
4661 named file. This repeats for the second and subsequent files.
4662 This call is intended for programs that want to efficiently list a
4664 directory contents without making many round-trips. See also
4665 "$g->lstatlist" for a similarly efficient call for getting standard
4666 stats.
4667 This function depends on the feature "linuxxattrs". See also
4669 "$g->feature-available".
4670 $disks = $g->max_disks ();
4672 Return the maximum number of disks that may be added to a handle
4673 (eg. by "$g->add_drive_opts" and similar calls).
4674 This function was added in libguestfs 1.19.7. In previous versions
4676 of libguestfs the limit was 25.
4677 See "MAXIMUM NUMBER OF DISKS" in guestfs(3) for additional
4679 information on this topic.
4680 $g->md_create ($name, \@devices [, missingbitmap => $missingbitmap] [,
4682 nrdevices => $nrdevices] [, spare => $spare] [, chunk => $chunk] [,
4683 level => $level]);
4684 Create a Linux md (RAID) device named "name" on the devices in the
4685 list "devices".
4686 The optional parameters are:
4688 "missingbitmap"
4690 A bitmap of missing devices. If a bit is set it means that a
4691 missing device is added to the array. The least significant
4692 bit corresponds to the first device in the array.
4693 As examples:
4695 If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
4697 resulting array would be "[<missing>, "/dev/sda"]".
4698 If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
4700 resulting array would be "["/dev/sda", <missing>]".
4701 This defaults to 0 (no missing devices).
4703 The length of "devices" + the number of bits set in
4705 "missingbitmap" must equal "nrdevices" + "spare".
4706 "nrdevices"
4708 The number of active RAID devices.
4709 If not set, this defaults to the length of "devices" plus the
4711 number of bits set in "missingbitmap".
4712 "spare"
4714 The number of spare devices.
4715 If not set, this defaults to 0.
4717 "chunk"
4719 The chunk size in bytes.
4720 "level"
4722 The RAID level, which can be one of: linear, raid0, 0, stripe,
4723 raid1, 1, mirror, raid4, 4, raid5, 5, raid6, 6, raid10, 10.
4724 Some of these are synonymous, and more levels may be added in
4725 future.
4726 If not set, this defaults to "raid1".
4728 This function depends on the feature "mdadm". See also
4730 "$g->feature-available".
4731 %info = $g->md_detail ($md);
4733 This command exposes the output of 'mdadm -DY <md>'. The following
4734 fields are usually present in the returned hash. Other fields may
4735 also be present.
4736 "level"
4738 The raid level of the MD device.
4739 "devices"
4741 The number of underlying devices in the MD device.
4742 "metadata"
4744 The metadata version used.
4745 "uuid"
4747 The UUID of the MD device.
4748 "name"
4750 The name of the MD device.
4751 This function depends on the feature "mdadm". See also
4753 "$g->feature-available".
4754 @devices = $g->md_stat ($md);
4756 This call returns a list of the underlying devices which make up
4757 the single software RAID array device "md".
4758 To get a list of software RAID devices, call "$g->list_md_devices".
4760 Each structure returned corresponds to one device along with
4762 additional status information:
4763 "mdstat_device"
4765 The name of the underlying device.
4766 "mdstat_index"
4768 The index of this device within the array.
4769 "mdstat_flags"
4771 Flags associated with this device. This is a string containing
4772 (in no specific order) zero or more of the following flags:
4773 "W" write-mostly
4775 "F" device is faulty
4777 "S" device is a RAID spare
4779 "R" replacement
4781 This function depends on the feature "mdadm". See also
4783 "$g->feature-available".
4784 $g->md_stop ($md);
4786 This command deactivates the MD array named "md". The device is
4787 stopped, but it is not destroyed or zeroed.
4788 This function depends on the feature "mdadm". See also
4790 "$g->feature-available".
4791 $g->mkdir ($path);
4793 Create a directory named "path".
4794 $g->mkdir_mode ($path, $mode);
4796 This command creates a directory, setting the initial permissions
4797 of the directory to "mode".
4798 For common Linux filesystems, the actual mode which is set will be
4800 "mode & ~umask & 01777". Non-native-Linux filesystems may
4801 interpret the mode in other ways.
4802 See also "$g->mkdir", "$g->umask"
4804 $g->mkdir_p ($path);
4806 Create a directory named "path", creating any parent directories as
4807 necessary. This is like the "mkdir -p" shell command.
4808 $dir = $g->mkdtemp ($tmpl);
4810 This command creates a temporary directory. The "tmpl" parameter
4811 should be a full pathname for the temporary directory name with the
4812 final six characters being "XXXXXX".
4813 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the
4815 second one being suitable for Windows filesystems.
4816 The name of the temporary directory that was created is returned.
4818 The temporary directory is created with mode 0700 and is owned by
4820 root.
4821 The caller is responsible for deleting the temporary directory and
4823 its contents after use.
4824 See also: mkdtemp(3)
4826 $g->mke2fs ($device [, blockscount => $blockscount] [, blocksize =>
4828 $blocksize] [, fragsize => $fragsize] [, blockspergroup =>
4829 $blockspergroup] [, numberofgroups => $numberofgroups] [, bytesperinode
4830 => $bytesperinode] [, inodesize => $inodesize] [, journalsize =>
4831 $journalsize] [, numberofinodes => $numberofinodes] [, stridesize =>
4832 $stridesize] [, stripewidth => $stripewidth] [, maxonlineresize =>
4833 $maxonlineresize] [, reservedblockspercentage =>
4834 $reservedblockspercentage] [, mmpupdateinterval => $mmpupdateinterval]
4835 [, journaldevice => $journaldevice] [, label => $label] [,
4836 lastmounteddir => $lastmounteddir] [, creatoros => $creatoros] [,
4837 fstype => $fstype] [, usagetype => $usagetype] [, uuid => $uuid] [,
4838 forcecreate => $forcecreate] [, writesbandgrouponly =>
4839 $writesbandgrouponly] [, lazyitableinit => $lazyitableinit] [,
4840 lazyjournalinit => $lazyjournalinit] [, testfs => $testfs] [, discard
4841 => $discard] [, quotatype => $quotatype] [, extent => $extent] [,
4842 filetype => $filetype] [, flexbg => $flexbg] [, hasjournal =>
4843 $hasjournal] [, journaldev => $journaldev] [, largefile => $largefile]
4844 [, quota => $quota] [, resizeinode => $resizeinode] [, sparsesuper =>
4845 $sparsesuper] [, uninitbg => $uninitbg]);
4846 "mke2fs" is used to create an ext2, ext3, or ext4 filesystem on
4847 "device".
4848 The optional "blockscount" is the size of the filesystem in blocks.
4850 If omitted it defaults to the size of "device". Note if the
4851 filesystem is too small to contain a journal, "mke2fs" will
4852 silently create an ext2 filesystem instead.
4853 $g->mke2fs_J ($fstype, $blocksize, $device, $journal);
4855 This creates an ext2/3/4 filesystem on "device" with an external
4856 journal on "journal". It is equivalent to the command:
4857 mke2fs -t fstype -b blocksize -J device=<journal> <device>
4859 See also "$g->mke2journal".
4861 This function is deprecated. In new code, use the "mke2fs" call
4863 instead.
4864 Deprecated functions will not be removed from the API, but the fact
4866 that they are deprecated indicates that there are problems with
4867 correct use of these functions.
4868 $g->mke2fs_JL ($fstype, $blocksize, $device, $label);
4870 This creates an ext2/3/4 filesystem on "device" with an external
4871 journal on the journal labeled "label".
4872 See also "$g->mke2journal_L".
4874 This function is deprecated. In new code, use the "mke2fs" call
4876 instead.
4877 Deprecated functions will not be removed from the API, but the fact
4879 that they are deprecated indicates that there are problems with
4880 correct use of these functions.
4881 $g->mke2fs_JU ($fstype, $blocksize, $device, $uuid);
4883 This creates an ext2/3/4 filesystem on "device" with an external
4884 journal on the journal with UUID "uuid".
4885 See also "$g->mke2journal_U".
4887 This function depends on the feature "linuxfsuuid". See also
4889 "$g->feature-available".
4890 This function is deprecated. In new code, use the "mke2fs" call
4892 instead.
4893 Deprecated functions will not be removed from the API, but the fact
4895 that they are deprecated indicates that there are problems with
4896 correct use of these functions.
4897 $g->mke2journal ($blocksize, $device);
4899 This creates an ext2 external journal on "device". It is
4900 equivalent to the command:
4901 mke2fs -O journal_dev -b blocksize device
4903 This function is deprecated. In new code, use the "mke2fs" call
4905 instead.
4906 Deprecated functions will not be removed from the API, but the fact
4908 that they are deprecated indicates that there are problems with
4909 correct use of these functions.
4910 $g->mke2journal_L ($blocksize, $label, $device);
4912 This creates an ext2 external journal on "device" with label
4913 "label".
4914 This function is deprecated. In new code, use the "mke2fs" call
4916 instead.
4917 Deprecated functions will not be removed from the API, but the fact
4919 that they are deprecated indicates that there are problems with
4920 correct use of these functions.
4921 $g->mke2journal_U ($blocksize, $uuid, $device);
4923 This creates an ext2 external journal on "device" with UUID "uuid".
4924 This function depends on the feature "linuxfsuuid". See also
4926 "$g->feature-available".
4927 This function is deprecated. In new code, use the "mke2fs" call
4929 instead.
4930 Deprecated functions will not be removed from the API, but the fact
4932 that they are deprecated indicates that there are problems with
4933 correct use of these functions.
4934 $g->mkfifo ($mode, $path);
4936 This call creates a FIFO (named pipe) called "path" with mode
4937 "mode". It is just a convenient wrapper around "$g->mknod".
4938 Unlike with "$g->mknod", "mode" must contain only permissions bits.
4940 The mode actually set is affected by the umask.
4942 This function depends on the feature "mknod". See also
4944 "$g->feature-available".
4945 $g->mkfs ($fstype, $device [, blocksize => $blocksize] [, features =>
4947 $features] [, inode => $inode] [, sectorsize => $sectorsize] [, label
4948 => $label]);
4949 This function creates a filesystem on "device". The filesystem
4950 type is "fstype", for example "ext3".
4951 The optional arguments are:
4953 "blocksize"
4955 The filesystem block size. Supported block sizes depend on the
4956 filesystem type, but typically they are 1024, 2048 or 4096 for
4957 Linux ext2/3 filesystems.
4958 For VFAT and NTFS the "blocksize" parameter is treated as the
4960 requested cluster size.
4961 For UFS block sizes, please see mkfs.ufs(8).
4963 "features"
4965 This passes the -O parameter to the external mkfs program.
4966 For certain filesystem types, this allows extra filesystem
4968 features to be selected. See mke2fs(8) and mkfs.ufs(8) for
4969 more details.
4970 You cannot use this optional parameter with the "gfs" or "gfs2"
4972 filesystem type.
4973 "inode"
4975 This passes the -I parameter to the external mke2fs(8) program
4976 which sets the inode size (only for ext2/3/4 filesystems at
4977 present).
4978 "sectorsize"
4980 This passes the -S parameter to external mkfs.ufs(8) program,
4981 which sets sector size for ufs filesystem.
4982 $g->mkfs_opts ($fstype, $device [, blocksize => $blocksize] [, features
4984 => $features] [, inode => $inode] [, sectorsize => $sectorsize] [,
4985 label => $label]);
4986 This is an alias of "mkfs".
4987 $g->mkfs_b ($fstype, $blocksize, $device);
4989 This call is similar to "$g->mkfs", but it allows you to control
4990 the block size of the resulting filesystem. Supported block sizes
4991 depend on the filesystem type, but typically they are 1024, 2048 or
4992 4096 only.
4993 For VFAT and NTFS the "blocksize" parameter is treated as the
4995 requested cluster size.
4996 This function is deprecated. In new code, use the "mkfs" call
4998 instead.
4999 Deprecated functions will not be removed from the API, but the fact
5001 that they are deprecated indicates that there are problems with
5002 correct use of these functions.
5003 $g->mkfs_btrfs (\@devices [, allocstart => $allocstart] [, bytecount =>
5005 $bytecount] [, datatype => $datatype] [, leafsize => $leafsize] [,
5006 label => $label] [, metadata => $metadata] [, nodesize => $nodesize] [,
5007 sectorsize => $sectorsize]);
5008 Create a btrfs filesystem, allowing all configurables to be set.
5009 For more information on the optional arguments, see mkfs.btrfs(8).
5010 Since btrfs filesystems can span multiple devices, this takes a
5012 non-empty list of devices.
5013 To create general filesystems, use "$g->mkfs".
5015 This function depends on the feature "btrfs". See also
5017 "$g->feature-available".
5018 $g->mklost_and_found ($mountpoint);
5020 Make the "lost+found" directory, normally in the root directory of
5021 an ext2/3/4 filesystem. "mountpoint" is the directory under which
5022 we try to create the "lost+found" directory.
5023 $g->mkmountpoint ($exemptpath);
5025 "$g->mkmountpoint" and "$g->rmmountpoint" are specialized calls
5026 that can be used to create extra mountpoints before mounting the
5027 first filesystem.
5028 These calls are only necessary in some very limited circumstances,
5030 mainly the case where you want to mount a mix of unrelated and/or
5031 read-only filesystems together.
5032 For example, live CDs often contain a "Russian doll" nest of
5034 filesystems, an ISO outer layer, with a squashfs image inside, with
5035 an ext2/3 image inside that. You can unpack this as follows in
5036 guestfish:
5037 add-ro Fedora-11-i686-Live.iso
5039 run
5040 mkmountpoint /cd
5041 mkmountpoint /sqsh
5042 mkmountpoint /ext3fs
5043 mount /dev/sda /cd
5044 mount-loop /cd/LiveOS/squashfs.img /sqsh
5045 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
5046 The inner filesystem is now unpacked under the /ext3fs mountpoint.
5048 "$g->mkmountpoint" is not compatible with "$g->umount_all". You
5050 may get unexpected errors if you try to mix these calls. It is
5051 safest to manually unmount filesystems and remove mountpoints after
5052 use.
5053 "$g->umount_all" unmounts filesystems by sorting the paths longest
5055 first, so for this to work for manual mountpoints, you must ensure
5056 that the innermost mountpoints have the longest pathnames, as in
5057 the example code above.
5058 For more details see
5060 <https://bugzilla.redhat.com/show_bug.cgi?id=599503>
5061 Autosync [see "$g->set_autosync", this is set by default on
5063 handles] can cause "$g->umount_all" to be called when the handle is
5064 closed which can also trigger these issues.
5065 $g->mknod ($mode, $devmajor, $devminor, $path);
5067 This call creates block or character special devices, or named
5068 pipes (FIFOs).
5069 The "mode" parameter should be the mode, using the standard
5071 constants. "devmajor" and "devminor" are the device major and
5072 minor numbers, only used when creating block and character special
5073 devices.
5074 Note that, just like mknod(2), the mode must be bitwise OR'd with
5076 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just
5077 creates a regular file). These constants are available in the
5078 standard Linux header files, or you can use "$g->mknod_b",
5079 "$g->mknod_c" or "$g->mkfifo" which are wrappers around this
5080 command which bitwise OR in the appropriate constant for you.
5081 The mode actually set is affected by the umask.
5083 This function depends on the feature "mknod". See also
5085 "$g->feature-available".
5086 $g->mknod_b ($mode, $devmajor, $devminor, $path);
5088 This call creates a block device node called "path" with mode
5089 "mode" and device major/minor "devmajor" and "devminor". It is
5090 just a convenient wrapper around "$g->mknod".
5091 Unlike with "$g->mknod", "mode" must contain only permissions bits.
5093 The mode actually set is affected by the umask.
5095 This function depends on the feature "mknod". See also
5097 "$g->feature-available".
5098 $g->mknod_c ($mode, $devmajor, $devminor, $path);
5100 This call creates a char device node called "path" with mode "mode"
5101 and device major/minor "devmajor" and "devminor". It is just a
5102 convenient wrapper around "$g->mknod".
5103 Unlike with "$g->mknod", "mode" must contain only permissions bits.
5105 The mode actually set is affected by the umask.
5107 This function depends on the feature "mknod". See also
5109 "$g->feature-available".
5110 $g->mksquashfs ($path, $filename [, compress => $compress] [, excludes
5112 => $excludes]);
5113 Create a squashfs filesystem for the specified "path".
5114 The optional "compress" flag controls compression. If not given,
5116 then the output compressed using "gzip". Otherwise one of the
5117 following strings may be given to select the compression type of
5118 the squashfs: "gzip", "lzma", "lzo", "lz4", "xz".
5119 The other optional arguments are:
5121 "excludes"
5123 A list of wildcards. Files are excluded if they match any of
5124 the wildcards.
5125 Please note that this API may fail when used to compress
5127 directories with large files, such as the resulting squashfs will
5128 be over 3GB big.
5129 This function depends on the feature "squashfs". See also
5131 "$g->feature-available".
5132 $g->mkswap ($device [, label => $label] [, uuid => $uuid]);
5134 Create a Linux swap partition on "device".
5135 The option arguments "label" and "uuid" allow you to set the label
5137 and/or UUID of the new swap partition.
5138 $g->mkswap_opts ($device [, label => $label] [, uuid => $uuid]);
5140 This is an alias of "mkswap".
5141 $g->mkswap_L ($label, $device);
5143 Create a swap partition on "device" with label "label".
5144 Note that you cannot attach a swap label to a block device (eg.
5146 /dev/sda), just to a partition. This appears to be a limitation of
5147 the kernel or swap tools.
5148 This function is deprecated. In new code, use the "mkswap" call
5150 instead.
5151 Deprecated functions will not be removed from the API, but the fact
5153 that they are deprecated indicates that there are problems with
5154 correct use of these functions.
5155 $g->mkswap_U ($uuid, $device);
5157 Create a swap partition on "device" with UUID "uuid".
5158 This function depends on the feature "linuxfsuuid". See also
5160 "$g->feature-available".
5161 This function is deprecated. In new code, use the "mkswap" call
5163 instead.
5164 Deprecated functions will not be removed from the API, but the fact
5166 that they are deprecated indicates that there are problems with
5167 correct use of these functions.
5168 $g->mkswap_file ($path);
5170 Create a swap file.
5171 This command just writes a swap file signature to an existing file.
5173 To create the file itself, use something like "$g->fallocate".
5174 $path = $g->mktemp ($tmpl [, suffix => $suffix]);
5176 This command creates a temporary file. The "tmpl" parameter should
5177 be a full pathname for the temporary directory name with the final
5178 six characters being "XXXXXX".
5179 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the
5181 second one being suitable for Windows filesystems.
5182 The name of the temporary file that was created is returned.
5184 The temporary file is created with mode 0600 and is owned by root.
5186 The caller is responsible for deleting the temporary file after
5188 use.
5189 If the optional "suffix" parameter is given, then the suffix (eg.
5191 ".txt") is appended to the temporary name.
5192 See also: "$g->mkdtemp".
5194 $g->modprobe ($modulename);
5196 This loads a kernel module in the appliance.
5197 This function depends on the feature "linuxmodules". See also
5199 "$g->feature-available".
5200 $g->mount ($mountable, $mountpoint);
5202 Mount a guest disk at a position in the filesystem. Block devices
5203 are named /dev/sda, /dev/sdb and so on, as they were added to the
5204 guest. If those block devices contain partitions, they will have
5205 the usual names (eg. /dev/sda1). Also LVM /dev/VG/LV-style names
5206 can be used, or XmountableX strings returned by
5207 "$g->list_filesystems" or "$g->inspect_get_mountpoints".
5208 The rules are the same as for mount(2): A filesystem must first be
5210 mounted on / before others can be mounted. Other filesystems can
5211 only be mounted on directories which already exist.
5212 The mounted filesystem is writable, if we have sufficient
5214 permissions on the underlying device.
5215 Before libguestfs 1.13.16, this call implicitly added the options
5217 "sync" and "noatime". The "sync" option greatly slowed writes and
5218 caused many problems for users. If your program might need to work
5219 with older versions of libguestfs, use "$g->mount_options" instead
5220 (using an empty string for the first parameter if you don't want
5221 any options).
5222 $g->mount_9p ($mounttag, $mountpoint [, options => $options]);
5224 Mount the virtio-9p filesystem with the tag "mounttag" on the
5225 directory "mountpoint".
5226 If required, "trans=virtio" will be automatically added to the
5228 options. Any other options required can be passed in the optional
5229 "options" parameter.
5230 $g->mount_local ($localmountpoint [, readonly => $readonly] [, options
5232 => $options] [, cachetimeout => $cachetimeout] [, debugcalls =>
5233 $debugcalls]);
5234 This call exports the libguestfs-accessible filesystem to a local
5235 mountpoint (directory) called "localmountpoint". Ordinary reads
5236 and writes to files and directories under "localmountpoint" are
5237 redirected through libguestfs.
5238 If the optional "readonly" flag is set to true, then writes to the
5240 filesystem return error "EROFS".
5241 "options" is a comma-separated list of mount options. See
5243 guestmount(1) for some useful options.
5244 "cachetimeout" sets the timeout (in seconds) for cached directory
5246 entries. The default is 60 seconds. See guestmount(1) for further
5247 information.
5248 If "debugcalls" is set to true, then additional debugging
5250 information is generated for every FUSE call.
5251 When "$g->mount_local" returns, the filesystem is ready, but is not
5253 processing requests (access to it will block). You have to call
5254 "$g->mount_local_run" to run the main loop.
5255 See "MOUNT LOCAL" in guestfs(3) for full documentation.
5257 $g->mount_local_run ();
5259 Run the main loop which translates kernel calls to libguestfs
5260 calls.
5261 This should only be called after "$g->mount_local" returns
5263 successfully. The call will not return until the filesystem is
5264 unmounted.
5265 Note you must not make concurrent libguestfs calls on the same
5267 handle from another thread.
5268 You may call this from a different thread than the one which called
5270 "$g->mount_local", subject to the usual rules for threads and
5271 libguestfs (see "MULTIPLE HANDLES AND MULTIPLE THREADS" in
5272 guestfs(3)).
5273 See "MOUNT LOCAL" in guestfs(3) for full documentation.
5275 $g->mount_loop ($file, $mountpoint);
5277 This command lets you mount file (a filesystem image in a file) on
5278 a mount point. It is entirely equivalent to the command "mount -o
5279 loop file mountpoint".
5280 $g->mount_options ($options, $mountable, $mountpoint);
5282 This is the same as the "$g->mount" command, but it allows you to
5283 set the mount options as for the mount(8) -o flag.
5284 If the "options" parameter is an empty string, then no options are
5286 passed (all options default to whatever the filesystem uses).
5287 $g->mount_ro ($mountable, $mountpoint);
5289 This is the same as the "$g->mount" command, but it mounts the
5290 filesystem with the read-only (-o ro) flag.
5291 $g->mount_vfs ($options, $vfstype, $mountable, $mountpoint);
5293 This is the same as the "$g->mount" command, but it allows you to
5294 set both the mount options and the vfstype as for the mount(8) -o
5295 and -t flags.
5296 $device = $g->mountable_device ($mountable);
5298 Returns the device name of a mountable. In quite a lot of cases,
5299 the mountable is the device name.
5300 However this doesn't apply for btrfs subvolumes, where the
5302 mountable is a combination of both the device name and the
5303 subvolume path (see also "$g->mountable_subvolume" to extract the
5304 subvolume path of the mountable if any).
5305 $subvolume = $g->mountable_subvolume ($mountable);
5307 Returns the subvolume path of a mountable. Btrfs subvolumes
5308 mountables are a combination of both the device name and the
5309 subvolume path (see also "$g->mountable_device" to extract the
5310 device of the mountable).
5311 If the mountable does not represent a btrfs subvolume, then this
5313 function fails and the "errno" is set to "EINVAL".
5314 %mps = $g->mountpoints ();
5316 This call is similar to "$g->mounts". That call returns a list of
5317 devices. This one returns a hash table (map) of device name to
5318 directory where the device is mounted.
5319 @devices = $g->mounts ();
5321 This returns the list of currently mounted filesystems. It returns
5322 the list of devices (eg. /dev/sda1, /dev/VG/LV).
5323 Some internal mounts are not shown.
5325 See also: "$g->mountpoints"
5327 $g->mv ($src, $dest);
5329 This moves a file from "src" to "dest" where "dest" is either a
5330 destination filename or destination directory.
5331 See also: "$g->rename".
5333 $nrdisks = $g->nr_devices ();
5335 This returns the number of whole block devices that were added.
5336 This is the same as the number of devices that would be returned if
5337 you called "$g->list_devices".
5338 To find out the maximum number of devices that could be added, call
5340 "$g->max_disks".
5341 $status = $g->ntfs_3g_probe ($rw, $device);
5343 This command runs the ntfs-3g.probe(8) command which probes an NTFS
5344 "device" for mountability. (Not all NTFS volumes can be mounted
5345 read-write, and some cannot be mounted at all).
5346 "rw" is a boolean flag. Set it to true if you want to test if the
5348 volume can be mounted read-write. Set it to false if you want to
5349 test if the volume can be mounted read-only.
5350 The return value is an integer which 0 if the operation would
5352 succeed, or some non-zero value documented in the ntfs-3g.probe(8)
5353 manual page.
5354 This function depends on the feature "ntfs3g". See also
5356 "$g->feature-available".
5357 $g->ntfscat_i ($device, $inode, $filename);
5359 Download a file given its inode from a NTFS filesystem and save it
5360 as filename on the local machine.
5361 This allows to download some otherwise inaccessible files such as
5363 the ones within the $Extend folder.
5364 The filesystem from which to extract the file must be unmounted,
5366 otherwise the call will fail.
5367 $g->ntfsclone_in ($backupfile, $device);
5369 Restore the "backupfile" (from a previous call to
5370 "$g->ntfsclone_out") to "device", overwriting any existing contents
5371 of this device.
5372 This function depends on the feature "ntfs3g". See also
5374 "$g->feature-available".
5375 $g->ntfsclone_out ($device, $backupfile [, metadataonly =>
5377 $metadataonly] [, rescue => $rescue] [, ignorefscheck =>
5378 $ignorefscheck] [, preservetimestamps => $preservetimestamps] [, force
5379 => $force]);
5380 Stream the NTFS filesystem "device" to the local file "backupfile".
5381 The format used for the backup file is a special format used by the
5382 ntfsclone(8) tool.
5383 If the optional "metadataonly" flag is true, then only the metadata
5385 is saved, losing all the user data (this is useful for diagnosing
5386 some filesystem problems).
5387 The optional "rescue", "ignorefscheck", "preservetimestamps" and
5389 "force" flags have precise meanings detailed in the ntfsclone(8)
5390 man page.
5391 Use "$g->ntfsclone_in" to restore the file back to a libguestfs
5393 device.
5394 This function depends on the feature "ntfs3g". See also
5396 "$g->feature-available".
5397 $g->ntfsfix ($device [, clearbadsectors => $clearbadsectors]);
5399 This command repairs some fundamental NTFS inconsistencies, resets
5400 the NTFS journal file, and schedules an NTFS consistency check for
5401 the first boot into Windows.
5402 This is not an equivalent of Windows "chkdsk". It does not scan
5404 the filesystem for inconsistencies.
5405 The optional "clearbadsectors" flag clears the list of bad sectors.
5407 This is useful after cloning a disk with bad sectors to a new disk.
5408 This function depends on the feature "ntfs3g". See also
5410 "$g->feature-available".
5411 $g->ntfsresize ($device [, size => $size] [, force => $force]);
5413 This command resizes an NTFS filesystem, expanding or shrinking it
5414 to the size of the underlying device.
5415 The optional parameters are:
5417 "size"
5419 The new size (in bytes) of the filesystem. If omitted, the
5420 filesystem is resized to fit the container (eg. partition).
5421 "force"
5423 If this option is true, then force the resize of the filesystem
5424 even if the filesystem is marked as requiring a consistency
5425 check.
5426 After the resize operation, the filesystem is always marked as
5428 requiring a consistency check (for safety). You have to boot
5429 into Windows to perform this check and clear this condition.
5430 If you don't set the "force" option then it is not possible to
5431 call "$g->ntfsresize" multiple times on a single filesystem
5432 without booting into Windows between each resize.
5433 See also ntfsresize(8).
5435 This function depends on the feature "ntfsprogs". See also
5437 "$g->feature-available".
5438 $g->ntfsresize_opts ($device [, size => $size] [, force => $force]);
5440 This is an alias of "ntfsresize".
5441 $g->ntfsresize_size ($device, $size);
5443 This command is the same as "$g->ntfsresize" except that it allows
5444 you to specify the new size (in bytes) explicitly.
5445 This function depends on the feature "ntfsprogs". See also
5447 "$g->feature-available".
5448 This function is deprecated. In new code, use the "ntfsresize"
5450 call instead.
5451 Deprecated functions will not be removed from the API, but the fact
5453 that they are deprecated indicates that there are problems with
5454 correct use of these functions.
5455 $g->parse_environment ();
5457 Parse the programXs environment and set flags in the handle
5458 accordingly. For example if "LIBGUESTFS_DEBUG=1" then the
5459 XverboseX flag is set in the handle.
5460 Most programs do not need to call this. It is done implicitly when
5462 you call "$g->create".
5463 See "ENVIRONMENT VARIABLES" in guestfs(3) for a list of environment
5465 variables that can affect libguestfs handles. See also
5466 "guestfs_create_flags" in guestfs(3), and
5467 "$g->parse_environment_list".
5468 $g->parse_environment_list (\@environment);
5470 Parse the list of strings in the argument "environment" and set
5471 flags in the handle accordingly. For example if
5472 "LIBGUESTFS_DEBUG=1" is a string in the list, then the XverboseX
5473 flag is set in the handle.
5474 This is the same as "$g->parse_environment" except that it parses
5476 an explicit list of strings instead of the program's environment.
5477 $g->part_add ($device, $prlogex, $startsect, $endsect);
5479 This command adds a partition to "device". If there is no
5480 partition table on the device, call "$g->part_init" first.
5481 The "prlogex" parameter is the type of partition. Normally you
5483 should pass "p" or "primary" here, but MBR partition tables also
5484 support "l" (or "logical") and "e" (or "extended") partition types.
5485 "startsect" and "endsect" are the start and end of the partition in
5487 sectors. "endsect" may be negative, which means it counts
5488 backwards from the end of the disk ("-1" is the last sector).
5489 Creating a partition which covers the whole disk is not so easy.
5491 Use "$g->part_disk" to do that.
5492 $g->part_del ($device, $partnum);
5494 This command deletes the partition numbered "partnum" on "device".
5495 Note that in the case of MBR partitioning, deleting an extended
5497 partition also deletes any logical partitions it contains.
5498 $g->part_disk ($device, $parttype);
5500 This command is simply a combination of "$g->part_init" followed by
5501 "$g->part_add" to create a single primary partition covering the
5502 whole disk.
5503 "parttype" is the partition table type, usually "mbr" or "gpt", but
5505 other possible values are described in "$g->part_init".
5506 $g->part_expand_gpt ($device);
5508 Move backup GPT data structures to the end of the disk. This is
5509 useful in case of in-place image expand since disk space after
5510 backup GPT header is not usable. This is equivalent to "sgdisk
5511 -e".
5512 See also sgdisk(8).
5514 This function depends on the feature "gdisk". See also
5516 "$g->feature-available".
5517 $bootable = $g->part_get_bootable ($device, $partnum);
5519 This command returns true if the partition "partnum" on "device"
5520 has the bootable flag set.
5521 See also "$g->part_set_bootable".
5523 $guid = $g->part_get_disk_guid ($device);
5525 Return the disk identifier (GUID) of a GPT-partitioned "device".
5526 Behaviour is undefined for other partition types.
5527 This function depends on the feature "gdisk". See also
5529 "$g->feature-available".
5530 $attributes = $g->part_get_gpt_attributes ($device, $partnum);
5532 Return the attribute flags of numbered GPT partition "partnum". An
5533 error is returned for MBR partitions.
5534 This function depends on the feature "gdisk". See also
5536 "$g->feature-available".
5537 $guid = $g->part_get_gpt_guid ($device, $partnum);
5539 Return the GUID of numbered GPT partition "partnum".
5540 This function depends on the feature "gdisk". See also
5542 "$g->feature-available".
5543 $guid = $g->part_get_gpt_type ($device, $partnum);
5545 Return the type GUID of numbered GPT partition "partnum". For MBR
5546 partitions, return an appropriate GUID corresponding to the MBR
5547 type. Behaviour is undefined for other partition types.
5548 This function depends on the feature "gdisk". See also
5550 "$g->feature-available".
5551 $idbyte = $g->part_get_mbr_id ($device, $partnum);
5553 Returns the MBR type byte (also known as the ID byte) from the
5554 numbered partition "partnum".
5555 Note that only MBR (old DOS-style) partitions have type bytes. You
5557 will get undefined results for other partition table types (see
5558 "$g->part_get_parttype").
5559 $partitiontype = $g->part_get_mbr_part_type ($device, $partnum);
5561 This returns the partition type of an MBR partition numbered
5562 "partnum" on device "device".
5563 It returns "primary", "logical", or "extended".
5565 $name = $g->part_get_name ($device, $partnum);
5567 This gets the partition name on partition numbered "partnum" on
5568 device "device". Note that partitions are numbered from 1.
5569 The partition name can only be read on certain types of partition
5571 table. This works on "gpt" but not on "mbr" partitions.
5572 $parttype = $g->part_get_parttype ($device);
5574 This command examines the partition table on "device" and returns
5575 the partition table type (format) being used.
5576 Common return values include: "msdos" (a DOS/Windows style MBR
5578 partition table), "gpt" (a GPT/EFI-style partition table). Other
5579 values are possible, although unusual. See "$g->part_init" for a
5580 full list.
5581 $g->part_init ($device, $parttype);
5583 This creates an empty partition table on "device" of one of the
5584 partition types listed below. Usually "parttype" should be either
5585 "msdos" or "gpt" (for large disks).
5586 Initially there are no partitions. Following this, you should call
5588 "$g->part_add" for each partition required.
5589 Possible values for "parttype" are:
5591 efi
5593 gpt Intel EFI / GPT partition table.
5594 This is recommended for >= 2 TB partitions that will be
5596 accessed from Linux and Intel-based Mac OS X. It also has
5597 limited backwards compatibility with the "mbr" format.
5598 mbr
5600 msdos
5601 The standard PC "Master Boot Record" (MBR) format used by MS-
5602 DOS and Windows. This partition type will only work for device
5603 sizes up to 2 TB. For large disks we recommend using "gpt".
5604 Other partition table types that may work but are not supported
5606 include:
5607 aix AIX disk labels.
5609 amiga
5611 rdb Amiga "Rigid Disk Block" format.
5612 bsd BSD disk labels.
5614 dasd
5616 DASD, used on IBM mainframes.
5617 dvh MIPS/SGI volumes.
5619 mac Old Mac partition format. Modern Macs use "gpt".
5621 pc98
5623 NEC PC-98 format, common in Japan apparently.
5624 sun Sun disk labels.
5626 @partitions = $g->part_list ($device);
5628 This command parses the partition table on "device" and returns the
5629 list of partitions found.
5630 The fields in the returned structure are:
5632 part_num
5634 Partition number, counting from 1.
5635 part_start
5637 Start of the partition in bytes. To get sectors you have to
5638 divide by the deviceXs sector size, see "$g->blockdev_getss".
5639 part_end
5641 End of the partition in bytes.
5642 part_size
5644 Size of the partition in bytes.
5645 $g->part_resize ($device, $partnum, $endsect);
5647 This command resizes the partition numbered "partnum" on "device"
5648 by moving the end position.
5649 Note that this does not modify any filesystem present in the
5651 partition. If you wish to do this, you will need to use filesystem
5652 resizing commands like "$g->resize2fs".
5653 When growing a partition you will want to grow the filesystem
5655 afterwards, but when shrinking, you need to shrink the filesystem
5656 before the partition.
5657 $g->part_set_bootable ($device, $partnum, $bootable);
5659 This sets the bootable flag on partition numbered "partnum" on
5660 device "device". Note that partitions are numbered from 1.
5661 The bootable flag is used by some operating systems (notably
5663 Windows) to determine which partition to boot from. It is by no
5664 means universally recognized.
5665 $g->part_set_disk_guid ($device, $guid);
5667 Set the disk identifier (GUID) of a GPT-partitioned "device" to
5668 "guid". Return an error if the partition table of "device" isn't
5669 GPT, or if "guid" is not a valid GUID.
5670 This function depends on the feature "gdisk". See also
5672 "$g->feature-available".
5673 $g->part_set_disk_guid_random ($device);
5675 Set the disk identifier (GUID) of a GPT-partitioned "device" to a
5676 randomly generated value. Return an error if the partition table
5677 of "device" isn't GPT.
5678 This function depends on the feature "gdisk". See also
5680 "$g->feature-available".
5681 $g->part_set_gpt_attributes ($device, $partnum, $attributes);
5683 Set the attribute flags of numbered GPT partition "partnum" to
5684 "attributes". Return an error if the partition table of "device"
5685 isn't GPT.
5686 See
5688 <https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_entries>
5689 for a useful list of partition attributes.
5690 This function depends on the feature "gdisk". See also
5692 "$g->feature-available".
5693 $g->part_set_gpt_guid ($device, $partnum, $guid);
5695 Set the GUID of numbered GPT partition "partnum" to "guid". Return
5696 an error if the partition table of "device" isn't GPT, or if "guid"
5697 is not a valid GUID.
5698 This function depends on the feature "gdisk". See also
5700 "$g->feature-available".
5701 $g->part_set_gpt_type ($device, $partnum, $guid);
5703 Set the type GUID of numbered GPT partition "partnum" to "guid".
5704 Return an error if the partition table of "device" isn't GPT, or if
5705 "guid" is not a valid GUID.
5706 See
5708 <http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs>
5709 for a useful list of type GUIDs.
5710 This function depends on the feature "gdisk". See also
5712 "$g->feature-available".
5713 $g->part_set_mbr_id ($device, $partnum, $idbyte);
5715 Sets the MBR type byte (also known as the ID byte) of the numbered
5716 partition "partnum" to "idbyte". Note that the type bytes quoted
5717 in most documentation are in fact hexadecimal numbers, but usually
5718 documented without any leading "0x" which might be confusing.
5719 Note that only MBR (old DOS-style) partitions have type bytes. You
5721 will get undefined results for other partition table types (see
5722 "$g->part_get_parttype").
5723 $g->part_set_name ($device, $partnum, $name);
5725 This sets the partition name on partition numbered "partnum" on
5726 device "device". Note that partitions are numbered from 1.
5727 The partition name can only be set on certain types of partition
5729 table. This works on "gpt" but not on "mbr" partitions.
5730 $device = $g->part_to_dev ($partition);
5732 This function takes a partition name (eg. "/dev/sdb1") and removes
5733 the partition number, returning the device name (eg. "/dev/sdb").
5734 The named partition must exist, for example as a string returned
5736 from "$g->list_partitions".
5737 See also "$g->part_to_partnum", "$g->device_index".
5739 $partnum = $g->part_to_partnum ($partition);
5741 This function takes a partition name (eg. "/dev/sdb1") and returns
5742 the partition number (eg. 1).
5743 The named partition must exist, for example as a string returned
5745 from "$g->list_partitions".
5746 See also "$g->part_to_dev".
5748 $g->ping_daemon ();
5750 This is a test probe into the guestfs daemon running inside the
5751 libguestfs appliance. Calling this function checks that the daemon
5752 responds to the ping message, without affecting the daemon or
5753 attached block device(s) in any other way.
5754 $content = $g->pread ($path, $count, $offset);
5756 This command lets you read part of a file. It reads "count" bytes
5757 of the file, starting at "offset", from file "path".
5758 This may read fewer bytes than requested. For further details see
5760 the pread(2) system call.
5761 See also "$g->pwrite", "$g->pread_device".
5763 Because of the message protocol, there is a transfer limit of
5765 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5766 guestfs(3).
5767 $content = $g->pread_device ($device, $count, $offset);
5769 This command lets you read part of a block device. It reads
5770 "count" bytes of "device", starting at "offset".
5771 This may read fewer bytes than requested. For further details see
5773 the pread(2) system call.
5774 See also "$g->pread".
5776 Because of the message protocol, there is a transfer limit of
5778 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5779 guestfs(3).
5780 $g->pvchange_uuid ($device);
5782 Generate a new random UUID for the physical volume "device".
5783 This function depends on the feature "lvm2". See also
5785 "$g->feature-available".
5786 $g->pvchange_uuid_all ();
5788 Generate new random UUIDs for all physical volumes.
5789 This function depends on the feature "lvm2". See also
5791 "$g->feature-available".
5792 $g->pvcreate ($device);
5794 This creates an LVM physical volume on the named "device", where
5795 "device" should usually be a partition name such as /dev/sda1.
5796 This function depends on the feature "lvm2". See also
5798 "$g->feature-available".
5799 $g->pvremove ($device);
5801 This wipes a physical volume "device" so that LVM will no longer
5802 recognise it.
5803 The implementation uses the "pvremove" command which refuses to
5805 wipe physical volumes that contain any volume groups, so you have
5806 to remove those first.
5807 This function depends on the feature "lvm2". See also
5809 "$g->feature-available".
5810 $g->pvresize ($device);
5812 This resizes (expands or shrinks) an existing LVM physical volume
5813 to match the new size of the underlying device.
5814 This function depends on the feature "lvm2". See also
5816 "$g->feature-available".
5817 $g->pvresize_size ($device, $size);
5819 This command is the same as "$g->pvresize" except that it allows
5820 you to specify the new size (in bytes) explicitly.
5821 This function depends on the feature "lvm2". See also
5823 "$g->feature-available".
5824 @physvols = $g->pvs ();
5826 List all the physical volumes detected. This is the equivalent of
5827 the pvs(8) command.
5828 This returns a list of just the device names that contain PVs (eg.
5830 /dev/sda2).
5831 See also "$g->pvs_full".
5833 This function depends on the feature "lvm2". See also
5835 "$g->feature-available".
5836 @physvols = $g->pvs_full ();
5838 List all the physical volumes detected. This is the equivalent of
5839 the pvs(8) command. The "full" version includes all fields.
5840 This function depends on the feature "lvm2". See also
5842 "$g->feature-available".
5843 $uuid = $g->pvuuid ($device);
5845 This command returns the UUID of the LVM PV "device".
5846 $nbytes = $g->pwrite ($path, $content, $offset);
5848 This command writes to part of a file. It writes the data buffer
5849 "content" to the file "path" starting at offset "offset".
5850 This command implements the pwrite(2) system call, and like that
5852 system call it may not write the full data requested. The return
5853 value is the number of bytes that were actually written to the
5854 file. This could even be 0, although short writes are unlikely for
5855 regular files in ordinary circumstances.
5856 See also "$g->pread", "$g->pwrite_device".
5858 Because of the message protocol, there is a transfer limit of
5860 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5861 guestfs(3).
5862 $nbytes = $g->pwrite_device ($device, $content, $offset);
5864 This command writes to part of a device. It writes the data buffer
5865 "content" to "device" starting at offset "offset".
5866 This command implements the pwrite(2) system call, and like that
5868 system call it may not write the full data requested (although
5869 short writes to disk devices and partitions are probably impossible
5870 with standard Linux kernels).
5871 See also "$g->pwrite".
5873 Because of the message protocol, there is a transfer limit of
5875 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5876 guestfs(3).
5877 $content = $g->read_file ($path);
5879 This calls returns the contents of the file "path" as a buffer.
5880 Unlike "$g->cat", this function can correctly handle files that
5882 contain embedded ASCII NUL characters.
5883 @lines = $g->read_lines ($path);
5885 Return the contents of the file named "path".
5886 The file contents are returned as a list of lines. Trailing "LF"
5888 and "CRLF" character sequences are not returned.
5889 Note that this function cannot correctly handle binary files
5891 (specifically, files containing "\0" character which is treated as
5892 end of string). For those you need to use the "$g->read_file"
5893 function and split the buffer into lines yourself.
5894 @entries = $g->readdir ($dir);
5896 This returns the list of directory entries in directory "dir".
5897 All entries in the directory are returned, including "." and "..".
5899 The entries are not sorted, but returned in the same order as the
5900 underlying filesystem.
5901 Also this call returns basic file type information about each file.
5903 The "ftyp" field will contain one of the following characters:
5904 'b' Block special
5906 'c' Char special
5908 'd' Directory
5910 'f' FIFO (named pipe)
5912 'l' Symbolic link
5914 'r' Regular file
5916 's' Socket
5918 'u' Unknown file type
5920 '?' The readdir(3) call returned a "d_type" field with an
5922 unexpected value
5923 This function is primarily intended for use by programs. To get a
5925 simple list of names, use "$g->ls". To get a printable directory
5926 for human consumption, use "$g->ll".
5927 Because of the message protocol, there is a transfer limit of
5929 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5930 guestfs(3).
5931 $link = $g->readlink ($path);
5933 This command reads the target of a symbolic link.
5934 @links = $g->readlinklist ($path, \@names);
5936 This call allows you to do a "readlink" operation on multiple
5937 files, where all files are in the directory "path". "names" is the
5938 list of files from this directory.
5939 On return you get a list of strings, with a one-to-one
5941 correspondence to the "names" list. Each string is the value of
5942 the symbolic link.
5943 If the readlink(2) operation fails on any name, then the
5945 corresponding result string is the empty string "". However the
5946 whole operation is completed even if there were readlink(2) errors,
5947 and so you can call this function with names where you don't know
5948 if they are symbolic links already (albeit slightly less
5949 efficient).
5950 This call is intended for programs that want to efficiently list a
5952 directory contents without making many round-trips.
5953 $rpath = $g->realpath ($path);
5955 Return the canonicalized absolute pathname of "path". The returned
5956 path has no ".", ".." or symbolic link path elements.
5957 $g->remount ($mountpoint [, rw => $rw]);
5959 This call allows you to change the "rw" (readonly/read-write) flag
5960 on an already mounted filesystem at "mountpoint", converting a
5961 readonly filesystem to be read-write, or vice-versa.
5962 Note that at the moment you must supply the "optional" "rw"
5964 parameter. In future we may allow other flags to be adjusted.
5965 $g->remove_drive ($label);
5967 This function is conceptually the opposite of "$g->add_drive_opts".
5968 It removes the drive that was previously added with label "label".
5969 Note that in order to remove drives, you have to add them with
5971 labels (see the optional "label" argument to "$g->add_drive_opts").
5972 If you didn't use a label, then they cannot be removed.
5973 You can call this function before or after launching the handle.
5975 If called after launch, if the backend supports it, we try to hot
5976 unplug the drive: see "HOTPLUGGING" in guestfs(3). The disk must
5977 not be in use (eg. mounted) when you do this. We try to detect if
5978 the disk is in use and stop you from doing this.
5979 $g->removexattr ($xattr, $path);
5981 This call removes the extended attribute named "xattr" of the file
5982 "path".
5983 See also: "$g->lremovexattr", attr(5).
5985 This function depends on the feature "linuxxattrs". See also
5987 "$g->feature-available".
5988 $g->rename ($oldpath, $newpath);
5990 Rename a file to a new place on the same filesystem. This is the
5991 same as the Linux rename(2) system call. In most cases you are
5992 better to use "$g->mv" instead.
5993 $g->resize2fs ($device);
5995 This resizes an ext2, ext3 or ext4 filesystem to match the size of
5996 the underlying device.
5997 See also "RESIZE2FS ERRORS" in guestfs(3).
5999 $g->resize2fs_M ($device);
6001 This command is the same as "$g->resize2fs", but the filesystem is
6002 resized to its minimum size. This works like the -M option to the
6003 "resize2fs" command.
6004 To get the resulting size of the filesystem you should call
6006 "$g->tune2fs_l" and read the "Block size" and "Block count" values.
6007 These two numbers, multiplied together, give the resulting size of
6008 the minimal filesystem in bytes.
6009 See also "RESIZE2FS ERRORS" in guestfs(3).
6011 $g->resize2fs_size ($device, $size);
6013 This command is the same as "$g->resize2fs" except that it allows
6014 you to specify the new size (in bytes) explicitly.
6015 See also "RESIZE2FS ERRORS" in guestfs(3).
6017 $g->rm ($path);
6019 Remove the single file "path".
6020 $g->rm_f ($path);
6022 Remove the file "path".
6023 If the file doesn't exist, that error is ignored. (Other errors,
6025 eg. I/O errors or bad paths, are not ignored)
6026 This call cannot remove directories. Use "$g->rmdir" to remove an
6028 empty directory, or "$g->rm_rf" to remove directories recursively.
6029 $g->rm_rf ($path);
6031 Remove the file or directory "path", recursively removing the
6032 contents if its a directory. This is like the "rm -rf" shell
6033 command.
6034 $g->rmdir ($path);
6036 Remove the single directory "path".
6037 $g->rmmountpoint ($exemptpath);
6039 This call removes a mountpoint that was previously created with
6040 "$g->mkmountpoint". See "$g->mkmountpoint" for full details.
6041 $g->rsync ($src, $dest [, archive => $archive] [, deletedest =>
6043 $deletedest]);
6044 This call may be used to copy or synchronize two directories under
6045 the same libguestfs handle. This uses the rsync(1) program which
6046 uses a fast algorithm that avoids copying files unnecessarily.
6047 "src" and "dest" are the source and destination directories. Files
6049 are copied from "src" to "dest".
6050 The optional arguments are:
6052 "archive"
6054 Turns on archive mode. This is the same as passing the
6055 --archive flag to "rsync".
6056 "deletedest"
6058 Delete files at the destination that do not exist at the
6059 source.
6060 This function depends on the feature "rsync". See also
6062 "$g->feature-available".
6063 $g->rsync_in ($remote, $dest [, archive => $archive] [, deletedest =>
6065 $deletedest]);
6066 This call may be used to copy or synchronize the filesystem on the
6067 host or on a remote computer with the filesystem within libguestfs.
6068 This uses the rsync(1) program which uses a fast algorithm that
6069 avoids copying files unnecessarily.
6070 This call only works if the network is enabled. See
6072 "$g->set_network" or the --network option to various tools like
6073 guestfish(1).
6074 Files are copied from the remote server and directory specified by
6076 "remote" to the destination directory "dest".
6077 The format of the remote server string is defined by rsync(1).
6079 Note that there is no way to supply a password or passphrase so the
6080 target must be set up not to require one.
6081 The optional arguments are the same as those of "$g->rsync".
6083 This function depends on the feature "rsync". See also
6085 "$g->feature-available".
6086 $g->rsync_out ($src, $remote [, archive => $archive] [, deletedest =>
6088 $deletedest]);
6089 This call may be used to copy or synchronize the filesystem within
6090 libguestfs with a filesystem on the host or on a remote computer.
6091 This uses the rsync(1) program which uses a fast algorithm that
6092 avoids copying files unnecessarily.
6093 This call only works if the network is enabled. See
6095 "$g->set_network" or the --network option to various tools like
6096 guestfish(1).
6097 Files are copied from the source directory "src" to the remote
6099 server and directory specified by "remote".
6100 The format of the remote server string is defined by rsync(1).
6102 Note that there is no way to supply a password or passphrase so the
6103 target must be set up not to require one.
6104 The optional arguments are the same as those of "$g->rsync".
6106 Globbing does not happen on the "src" parameter. In programs which
6108 use the API directly you have to expand wildcards yourself (see
6109 "$g->glob_expand"). In guestfish you can use the "glob" command
6110 (see "glob" in guestfish(1)), for example:
6111 ><fs> glob rsync-out /* rsync://remote/
6113 This function depends on the feature "rsync". See also
6115 "$g->feature-available".
6116 $g->scrub_device ($device);
6118 This command writes patterns over "device" to make data retrieval
6119 more difficult.
6120 It is an interface to the scrub(1) program. See that manual page
6122 for more details.
6123 This function depends on the feature "scrub". See also
6125 "$g->feature-available".
6126 $g->scrub_file ($file);
6128 This command writes patterns over a file to make data retrieval
6129 more difficult.
6130 The file is removed after scrubbing.
6132 It is an interface to the scrub(1) program. See that manual page
6134 for more details.
6135 This function depends on the feature "scrub". See also
6137 "$g->feature-available".
6138 $g->scrub_freespace ($dir);
6140 This command creates the directory "dir" and then fills it with
6141 files until the filesystem is full, and scrubs the files as for
6142 "$g->scrub_file", and deletes them. The intention is to scrub any
6143 free space on the partition containing "dir".
6144 It is an interface to the scrub(1) program. See that manual page
6146 for more details.
6147 This function depends on the feature "scrub". See also
6149 "$g->feature-available".
6150 $g->selinux_relabel ($specfile, $path [, force => $force]);
6152 SELinux relabel parts of the filesystem.
6153 The "specfile" parameter controls the policy spec file used. You
6155 have to parse "/etc/selinux/config" to find the correct SELinux
6156 policy and then pass the spec file, usually: "/etc/selinux/" +
6157 selinuxtype + "/contexts/files/file_contexts".
6158 The required "path" parameter is the top level directory where
6160 relabelling starts. Normally you should pass "path" as "/" to
6161 relabel the whole guest filesystem.
6162 The optional "force" boolean controls whether the context is reset
6164 for customizable files, and also whether the user, role and range
6165 parts of the file context is changed.
6166 This function depends on the feature "selinuxrelabel". See also
6168 "$g->feature-available".
6169 $g->set_append ($append);
6171 This function is used to add additional options to the libguestfs
6172 appliance kernel command line.
6173 The default is "NULL" unless overridden by setting
6175 "LIBGUESTFS_APPEND" environment variable.
6176 Setting "append" to "NULL" means no additional options are passed
6178 (libguestfs always adds a few of its own).
6179 $g->set_attach_method ($backend);
6181 Set the method that libguestfs uses to connect to the backend
6182 guestfsd daemon.
6183 See "BACKEND" in guestfs(3).
6185 This function is deprecated. In new code, use the "set_backend"
6187 call instead.
6188 Deprecated functions will not be removed from the API, but the fact
6190 that they are deprecated indicates that there are problems with
6191 correct use of these functions.
6192 $g->set_autosync ($autosync);
6194 If "autosync" is true, this enables autosync. Libguestfs will make
6195 a best effort attempt to make filesystems consistent and
6196 synchronized when the handle is closed (also if the program exits
6197 without closing handles).
6198 This is enabled by default (since libguestfs 1.5.24, previously it
6200 was disabled by default).
6201 $g->set_backend ($backend);
6203 Set the method that libguestfs uses to connect to the backend
6204 guestfsd daemon.
6205 This handle property was previously called the "attach method".
6207 See "BACKEND" in guestfs(3).
6209 $g->set_backend_setting ($name, $val);
6211 Append "name=value" to the backend settings string list. However
6212 if a string already exists matching "name" or beginning with
6213 "name=", then that setting is replaced.
6214 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
6216 $g->set_backend_settings (\@settings);
6218 Set a list of zero or more settings which are passed through to the
6219 current backend. Each setting is a string which is interpreted in
6220 a backend-specific way, or ignored if not understood by the
6221 backend.
6222 The default value is an empty list, unless the environment variable
6224 "LIBGUESTFS_BACKEND_SETTINGS" was set when the handle was created.
6225 This environment variable contains a colon-separated list of
6226 settings.
6227 This call replaces all backend settings. If you want to replace a
6229 single backend setting, see "$g->set_backend_setting". If you want
6230 to clear a single backend setting, see "$g->clear_backend_setting".
6231 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
6233 $g->set_cachedir ($cachedir);
6235 Set the directory used by the handle to store the appliance cache,
6236 when using a supermin appliance. The appliance is cached and
6237 shared between all handles which have the same effective user ID.
6238 The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR"
6240 control the default value: If "LIBGUESTFS_CACHEDIR" is set, then
6241 that is the default. Else if "TMPDIR" is set, then that is the
6242 default. Else /var/tmp is the default.
6243 $g->set_direct ($direct);
6245 If the direct appliance mode flag is enabled, then stdin and stdout
6246 are passed directly through to the appliance once it is launched.
6247 One consequence of this is that log messages aren't caught by the
6249 library and handled by "$g->set_log_message_callback", but go
6250 straight to stdout.
6251 You probably don't want to use this unless you know what you are
6253 doing.
6254 The default is disabled.
6256 This function is deprecated. In new code, use the
6258 "internal_get_console_socket" call instead.
6259 Deprecated functions will not be removed from the API, but the fact
6261 that they are deprecated indicates that there are problems with
6262 correct use of these functions.
6263 $g->set_e2attrs ($file, $attrs [, clear => $clear]);
6265 This sets or clears the file attributes "attrs" associated with the
6266 inode file.
6267 "attrs" is a string of characters representing file attributes.
6269 See "$g->get_e2attrs" for a list of possible attributes. Not all
6270 attributes can be changed.
6271 If optional boolean "clear" is not present or false, then the
6273 "attrs" listed are set in the inode.
6274 If "clear" is true, then the "attrs" listed are cleared in the
6276 inode.
6277 In both cases, other attributes not present in the "attrs" string
6279 are left unchanged.
6280 These attributes are only present when the file is located on an
6282 ext2/3/4 filesystem. Using this call on other filesystem types
6283 will result in an error.
6284 $g->set_e2generation ($file, $generation);
6286 This sets the ext2 file generation of a file.
6287 See "$g->get_e2generation".
6289 $g->set_e2label ($device, $label);
6291 This sets the ext2/3/4 filesystem label of the filesystem on
6292 "device" to "label". Filesystem labels are limited to 16
6293 characters.
6294 You can use either "$g->tune2fs_l" or "$g->get_e2label" to return
6296 the existing label on a filesystem.
6297 This function is deprecated. In new code, use the "set_label" call
6299 instead.
6300 Deprecated functions will not be removed from the API, but the fact
6302 that they are deprecated indicates that there are problems with
6303 correct use of these functions.
6304 $g->set_e2uuid ($device, $uuid);
6306 This sets the ext2/3/4 filesystem UUID of the filesystem on
6307 "device" to "uuid". The format of the UUID and alternatives such
6308 as "clear", "random" and "time" are described in the tune2fs(8)
6309 manpage.
6310 You can use "$g->vfs_uuid" to return the existing UUID of a
6312 filesystem.
6313 This function is deprecated. In new code, use the "set_uuid" call
6315 instead.
6316 Deprecated functions will not be removed from the API, but the fact
6318 that they are deprecated indicates that there are problems with
6319 correct use of these functions.
6320 $g->set_hv ($hv);
6322 Set the hypervisor binary that we will use. The hypervisor depends
6323 on the backend, but is usually the location of the qemu/KVM
6324 hypervisor. For the uml backend, it is the location of the "linux"
6325 or "vmlinux" binary.
6326 The default is chosen when the library was compiled by the
6328 configure script.
6329 You can also override this by setting the "LIBGUESTFS_HV"
6331 environment variable.
6332 Note that you should call this function as early as possible after
6334 creating the handle. This is because some pre-launch operations
6335 depend on testing qemu features (by running "qemu -help"). If the
6336 qemu binary changes, we don't retest features, and so you might see
6337 inconsistent results. Using the environment variable
6338 "LIBGUESTFS_HV" is safest of all since that picks the qemu binary
6339 at the same time as the handle is created.
6340 $g->set_identifier ($identifier);
6342 This is an informative string which the caller may optionally set
6343 in the handle. It is printed in various places, allowing the
6344 current handle to be identified in debugging output.
6345 One important place is when tracing is enabled. If the identifier
6347 string is not an empty string, then trace messages change from
6348 this:
6349 libguestfs: trace: get_tmpdir
6351 libguestfs: trace: get_tmpdir = "/tmp"
6352 to this:
6354 libguestfs: trace: ID: get_tmpdir
6356 libguestfs: trace: ID: get_tmpdir = "/tmp"
6357 where "ID" is the identifier string set by this call.
6359 The identifier must only contain alphanumeric ASCII characters,
6361 underscore and minus sign. The default is the empty string.
6362 See also "$g->set_program", "$g->set_trace", "$g->get_identifier".
6364 $g->set_label ($mountable, $label);
6366 Set the filesystem label on "mountable" to "label".
6367 Only some filesystem types support labels, and libguestfs supports
6369 setting labels on only a subset of these.
6370 ext2, ext3, ext4
6372 Labels are limited to 16 bytes.
6373 NTFS
6375 Labels are limited to 128 unicode characters.
6376 XFS The label is limited to 12 bytes. The filesystem must not be
6378 mounted when trying to set the label.
6379 btrfs
6381 The label is limited to 255 bytes and some characters are not
6382 allowed. Setting the label on a btrfs subvolume will set the
6383 label on its parent filesystem. The filesystem must not be
6384 mounted when trying to set the label.
6385 fat The label is limited to 11 bytes.
6387 swap
6389 The label is limited to 16 bytes.
6390 If there is no support for changing the label for the type of the
6392 specified filesystem, set_label will fail and set errno as ENOTSUP.
6393 To read the label on a filesystem, call "$g->vfs_label".
6395 $g->set_libvirt_requested_credential ($index, $cred);
6397 After requesting the "index"'th credential from the user, call this
6398 function to pass the answer back to libvirt.
6399 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
6401 example code.
6402 $g->set_libvirt_supported_credentials (\@creds);
6404 Call this function before setting an event handler for
6405 "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential
6406 types that the program knows how to process.
6407 The "creds" list must be a non-empty list of strings. Possible
6409 strings are:
6410 "username"
6412 "authname"
6413 "language"
6414 "cnonce"
6415 "passphrase"
6416 "echoprompt"
6417 "noechoprompt"
6418 "realm"
6419 "external"
6420 See libvirt documentation for the meaning of these credential
6422 types.
6423 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
6425 example code.
6426 $g->set_memsize ($memsize);
6428 This sets the memory size in megabytes allocated to the hypervisor.
6429 This only has any effect if called before "$g->launch".
6430 You can also change this by setting the environment variable
6432 "LIBGUESTFS_MEMSIZE" before the handle is created.
6433 For more information on the architecture of libguestfs, see
6435 guestfs(3).
6436 $g->set_network ($network);
6438 If "network" is true, then the network is enabled in the libguestfs
6439 appliance. The default is false.
6440 This affects whether commands are able to access the network (see
6442 "RUNNING COMMANDS" in guestfs(3)).
6443 You must call this before calling "$g->launch", otherwise it has no
6445 effect.
6446 $g->set_path ($searchpath);
6448 Set the path that libguestfs searches for kernel and initrd.img.
6449 The default is "$libdir/guestfs" unless overridden by setting
6451 "LIBGUESTFS_PATH" environment variable.
6452 Setting "path" to "NULL" restores the default path.
6454 $g->set_pgroup ($pgroup);
6456 If "pgroup" is true, child processes are placed into their own
6457 process group.
6458 The practical upshot of this is that signals like "SIGINT" (from
6460 users pressing "^C") won't be received by the child process.
6461 The default for this flag is false, because usually you want "^C"
6463 to kill the subprocess. Guestfish sets this flag to true when used
6464 interactively, so that "^C" can cancel long-running commands
6465 gracefully (see "$g->user_cancel").
6466 $g->set_program ($program);
6468 Set the program name. This is an informative string which the main
6469 program may optionally set in the handle.
6470 When the handle is created, the program name in the handle is set
6472 to the basename from "argv[0]". The program name can never be
6473 "NULL".
6474 $g->set_qemu ($hv);
6476 Set the hypervisor binary (usually qemu) that we will use.
6477 The default is chosen when the library was compiled by the
6479 configure script.
6480 You can also override this by setting the "LIBGUESTFS_HV"
6482 environment variable.
6483 Setting "hv" to "NULL" restores the default qemu binary.
6485 Note that you should call this function as early as possible after
6487 creating the handle. This is because some pre-launch operations
6488 depend on testing qemu features (by running "qemu -help"). If the
6489 qemu binary changes, we don't retest features, and so you might see
6490 inconsistent results. Using the environment variable
6491 "LIBGUESTFS_HV" is safest of all since that picks the qemu binary
6492 at the same time as the handle is created.
6493 This function is deprecated. In new code, use the "set_hv" call
6495 instead.
6496 Deprecated functions will not be removed from the API, but the fact
6498 that they are deprecated indicates that there are problems with
6499 correct use of these functions.
6500 $g->set_recovery_proc ($recoveryproc);
6502 If this is called with the parameter "false" then "$g->launch" does
6503 not create a recovery process. The purpose of the recovery process
6504 is to stop runaway hypervisor processes in the case where the main
6505 program aborts abruptly.
6506 This only has any effect if called before "$g->launch", and the
6508 default is true.
6509 About the only time when you would want to disable this is if the
6511 main process will fork itself into the background ("daemonize"
6512 itself). In this case the recovery process thinks that the main
6513 program has disappeared and so kills the hypervisor, which is not
6514 very helpful.
6515 $g->set_selinux ($selinux);
6517 This sets the selinux flag that is passed to the appliance at boot
6518 time. The default is "selinux=0" (disabled).
6519 Note that if SELinux is enabled, it is always in Permissive mode
6521 ("enforcing=0").
6522 For more information on the architecture of libguestfs, see
6524 guestfs(3).
6525 This function is deprecated. In new code, use the
6527 "selinux_relabel" call instead.
6528 Deprecated functions will not be removed from the API, but the fact
6530 that they are deprecated indicates that there are problems with
6531 correct use of these functions.
6532 $g->set_smp ($smp);
6534 Change the number of virtual CPUs assigned to the appliance. The
6535 default is 1. Increasing this may improve performance, though
6536 often it has no effect.
6537 This function must be called before "$g->launch".
6539 $g->set_tmpdir ($tmpdir);
6541 Set the directory used by the handle to store temporary files.
6542 The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control
6544 the default value: If "LIBGUESTFS_TMPDIR" is set, then that is the
6545 default. Else if "TMPDIR" is set, then that is the default. Else
6546 /tmp is the default.
6547 $g->set_trace ($trace);
6549 If the command trace flag is set to 1, then libguestfs calls,
6550 parameters and return values are traced.
6551 If you want to trace C API calls into libguestfs (and other
6553 libraries) then possibly a better way is to use the external
6554 ltrace(1) command.
6555 Command traces are disabled unless the environment variable
6557 "LIBGUESTFS_TRACE" is defined and set to 1.
6558 Trace messages are normally sent to "stderr", unless you register a
6560 callback to send them somewhere else (see
6561 "$g->set_event_callback").
6562 $g->set_uuid ($device, $uuid);
6564 Set the filesystem UUID on "device" to "uuid". If this fails and
6565 the errno is ENOTSUP, means that there is no support for changing
6566 the UUID for the type of the specified filesystem.
6567 Only some filesystem types support setting UUIDs.
6569 To read the UUID on a filesystem, call "$g->vfs_uuid".
6571 $g->set_uuid_random ($device);
6573 Set the filesystem UUID on "device" to a random UUID. If this
6574 fails and the errno is ENOTSUP, means that there is no support for
6575 changing the UUID for the type of the specified filesystem.
6576 Only some filesystem types support setting UUIDs.
6578 To read the UUID on a filesystem, call "$g->vfs_uuid".
6580 $g->set_verbose ($verbose);
6582 If "verbose" is true, this turns on verbose messages.
6583 Verbose messages are disabled unless the environment variable
6585 "LIBGUESTFS_DEBUG" is defined and set to 1.
6586 Verbose messages are normally sent to "stderr", unless you register
6588 a callback to send them somewhere else (see
6589 "$g->set_event_callback").
6590 $g->setcon ($context);
6592 This sets the SELinux security context of the daemon to the string
6593 "context".
6594 See the documentation about SELINUX in guestfs(3).
6596 This function depends on the feature "selinux". See also
6598 "$g->feature-available".
6599 This function is deprecated. In new code, use the
6601 "selinux_relabel" call instead.
6602 Deprecated functions will not be removed from the API, but the fact
6604 that they are deprecated indicates that there are problems with
6605 correct use of these functions.
6606 $g->setxattr ($xattr, $val, $vallen, $path);
6608 This call sets the extended attribute named "xattr" of the file
6609 "path" to the value "val" (of length "vallen"). The value is
6610 arbitrary 8 bit data.
6611 See also: "$g->lsetxattr", attr(5).
6613 This function depends on the feature "linuxxattrs". See also
6615 "$g->feature-available".
6616 $g->sfdisk ($device, $cyls, $heads, $sectors, \@lines);
6618 This is a direct interface to the sfdisk(8) program for creating
6619 partitions on block devices.
6620 "device" should be a block device, for example /dev/sda.
6622 "cyls", "heads" and "sectors" are the number of cylinders, heads
6624 and sectors on the device, which are passed directly to sfdisk as
6625 the -C, -H and -S parameters. If you pass 0 for any of these, then
6626 the corresponding parameter is omitted. Usually for XlargeX disks,
6627 you can just pass 0 for these, but for small (floppy-sized) disks,
6628 sfdisk (or rather, the kernel) cannot work out the right geometry
6629 and you will need to tell it.
6630 "lines" is a list of lines that we feed to "sfdisk". For more
6632 information refer to the sfdisk(8) manpage.
6633 To create a single partition occupying the whole disk, you would
6635 pass "lines" as a single element list, when the single element
6636 being the string "," (comma).
6637 See also: "$g->sfdisk_l", "$g->sfdisk_N", "$g->part_init"
6639 This function is deprecated. In new code, use the "part_add" call
6641 instead.
6642 Deprecated functions will not be removed from the API, but the fact
6644 that they are deprecated indicates that there are problems with
6645 correct use of these functions.
6646 $g->sfdiskM ($device, \@lines);
6648 This is a simplified interface to the "$g->sfdisk" command, where
6649 partition sizes are specified in megabytes only (rounded to the
6650 nearest cylinder) and you don't need to specify the cyls, heads and
6651 sectors parameters which were rarely if ever used anyway.
6652 See also: "$g->sfdisk", the sfdisk(8) manpage and "$g->part_disk"
6654 This function is deprecated. In new code, use the "part_add" call
6656 instead.
6657 Deprecated functions will not be removed from the API, but the fact
6659 that they are deprecated indicates that there are problems with
6660 correct use of these functions.
6661 $g->sfdisk_N ($device, $partnum, $cyls, $heads, $sectors, $line);
6663 This runs sfdisk(8) option to modify just the single partition "n"
6664 (note: "n" counts from 1).
6665 For other parameters, see "$g->sfdisk". You should usually pass 0
6667 for the cyls/heads/sectors parameters.
6668 See also: "$g->part_add"
6670 This function is deprecated. In new code, use the "part_add" call
6672 instead.
6673 Deprecated functions will not be removed from the API, but the fact
6675 that they are deprecated indicates that there are problems with
6676 correct use of these functions.
6677 $partitions = $g->sfdisk_disk_geometry ($device);
6679 This displays the disk geometry of "device" read from the partition
6680 table. Especially in the case where the underlying block device
6681 has been resized, this can be different from the kernelXs idea of
6682 the geometry (see "$g->sfdisk_kernel_geometry").
6683 The result is in human-readable format, and not designed to be
6685 parsed.
6686 $partitions = $g->sfdisk_kernel_geometry ($device);
6688 This displays the kernelXs idea of the geometry of "device".
6689 The result is in human-readable format, and not designed to be
6691 parsed.
6692 $partitions = $g->sfdisk_l ($device);
6694 This displays the partition table on "device", in the human-
6695 readable output of the sfdisk(8) command. It is not intended to be
6696 parsed.
6697 See also: "$g->part_list"
6699 This function is deprecated. In new code, use the "part_list" call
6701 instead.
6702 Deprecated functions will not be removed from the API, but the fact
6704 that they are deprecated indicates that there are problems with
6705 correct use of these functions.
6706 $output = $g->sh ($command);
6708 This call runs a command from the guest filesystem via the guestXs
6709 /bin/sh.
6710 This is like "$g->command", but passes the command to:
6712 /bin/sh -c "command"
6714 Depending on the guestXs shell, this usually results in wildcards
6716 being expanded, shell expressions being interpolated and so on.
6717 All the provisos about "$g->command" apply to this call.
6719 @lines = $g->sh_lines ($command);
6721 This is the same as "$g->sh", but splits the result into a list of
6722 lines.
6723 See also: "$g->command_lines"
6725 $g->shutdown ();
6727 This is the opposite of "$g->launch". It performs an orderly
6728 shutdown of the backend process(es). If the autosync flag is set
6729 (which is the default) then the disk image is synchronized.
6730 If the subprocess exits with an error then this function will
6732 return an error, which should not be ignored (it may indicate that
6733 the disk image could not be written out properly).
6734 It is safe to call this multiple times. Extra calls are ignored.
6736 This call does not close or free up the handle. You still need to
6738 call "$g->close" afterwards.
6739 "$g->close" will call this if you don't do it explicitly, but note
6741 that any errors are ignored in that case.
6742 $g->sleep ($secs);
6744 Sleep for "secs" seconds.
6745 %statbuf = $g->stat ($path);
6747 Returns file information for the given "path".
6748 This is the same as the stat(2) system call.
6750 This function is deprecated. In new code, use the "statns" call
6752 instead.
6753 Deprecated functions will not be removed from the API, but the fact
6755 that they are deprecated indicates that there are problems with
6756 correct use of these functions.
6757 %statbuf = $g->statns ($path);
6759 Returns file information for the given "path".
6760 This is the same as the stat(2) system call.
6762 %statbuf = $g->statvfs ($path);
6764 Returns file system statistics for any mounted file system. "path"
6765 should be a file or directory in the mounted file system (typically
6766 it is the mount point itself, but it doesn't need to be).
6767 This is the same as the statvfs(2) system call.
6769 @stringsout = $g->strings ($path);
6771 This runs the strings(1) command on a file and returns the list of
6772 printable strings found.
6773 The "strings" command has, in the past, had problems with parsing
6775 untrusted files. These are mitigated in the current version of
6776 libguestfs, but see "CVE-2014-8484" in guestfs(3).
6777 Because of the message protocol, there is a transfer limit of
6779 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
6780 guestfs(3).
6781 @stringsout = $g->strings_e ($encoding, $path);
6783 This is like the "$g->strings" command, but allows you to specify
6784 the encoding of strings that are looked for in the source file
6785 "path".
6786 Allowed encodings are:
6788 s Single 7-bit-byte characters like ASCII and the ASCII-
6790 compatible parts of ISO-8859-X (this is what "$g->strings"
6791 uses).
6792 S Single 8-bit-byte characters.
6794 b 16-bit big endian strings such as those encoded in UTF-16BE or
6796 UCS-2BE.
6797 l (lower case letter L)
6799 16-bit little endian such as UTF-16LE and UCS-2LE. This is
6800 useful for examining binaries in Windows guests.
6801 B 32-bit big endian such as UCS-4BE.
6803 L 32-bit little endian such as UCS-4LE.
6805 The returned strings are transcoded to UTF-8.
6807 The "strings" command has, in the past, had problems with parsing
6809 untrusted files. These are mitigated in the current version of
6810 libguestfs, but see "CVE-2014-8484" in guestfs(3).
6811 Because of the message protocol, there is a transfer limit of
6813 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
6814 guestfs(3).
6815 $g->swapoff_device ($device);
6817 This command disables the libguestfs appliance swap device or
6818 partition named "device". See "$g->swapon_device".
6819 $g->swapoff_file ($file);
6821 This command disables the libguestfs appliance swap on file.
6822 $g->swapoff_label ($label);
6824 This command disables the libguestfs appliance swap on labeled swap
6825 partition.
6826 $g->swapoff_uuid ($uuid);
6828 This command disables the libguestfs appliance swap partition with
6829 the given UUID.
6830 This function depends on the feature "linuxfsuuid". See also
6832 "$g->feature-available".
6833 $g->swapon_device ($device);
6835 This command enables the libguestfs appliance to use the swap
6836 device or partition named "device". The increased memory is made
6837 available for all commands, for example those run using
6838 "$g->command" or "$g->sh".
6839 Note that you should not swap to existing guest swap partitions
6841 unless you know what you are doing. They may contain hibernation
6842 information, or other information that the guest doesn't want you
6843 to trash. You also risk leaking information about the host to the
6844 guest this way. Instead, attach a new host device to the guest and
6845 swap on that.
6846 $g->swapon_file ($file);
6848 This command enables swap to a file. See "$g->swapon_device" for
6849 other notes.
6850 $g->swapon_label ($label);
6852 This command enables swap to a labeled swap partition. See
6853 "$g->swapon_device" for other notes.
6854 $g->swapon_uuid ($uuid);
6856 This command enables swap to a swap partition with the given UUID.
6857 See "$g->swapon_device" for other notes.
6858 This function depends on the feature "linuxfsuuid". See also
6860 "$g->feature-available".
6861 $g->sync ();
6863 This syncs the disk, so that any writes are flushed through to the
6864 underlying disk image.
6865 You should always call this if you have modified a disk image,
6867 before closing the handle.
6868 $g->syslinux ($device [, directory => $directory]);
6870 Install the SYSLINUX bootloader on "device".
6871 The device parameter must be either a whole disk formatted as a FAT
6873 filesystem, or a partition formatted as a FAT filesystem. In the
6874 latter case, the partition should be marked as "active"
6875 ("$g->part_set_bootable") and a Master Boot Record must be
6876 installed (eg. using "$g->pwrite_device") on the first sector of
6877 the whole disk. The SYSLINUX package comes with some suitable
6878 Master Boot Records. See the syslinux(1) man page for further
6879 information.
6880 The optional arguments are:
6882 directory
6884 Install SYSLINUX in the named subdirectory, instead of in the
6885 root directory of the FAT filesystem.
6886 Additional configuration can be supplied to SYSLINUX by placing a
6888 file called syslinux.cfg on the FAT filesystem, either in the root
6889 directory, or under directory if that optional argument is being
6890 used. For further information about the contents of this file, see
6891 syslinux(1).
6892 See also "$g->extlinux".
6894 This function depends on the feature "syslinux". See also
6896 "$g->feature-available".
6897 @lines = $g->tail ($path);
6899 This command returns up to the last 10 lines of a file as a list of
6900 strings.
6901 Because of the message protocol, there is a transfer limit of
6903 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
6904 guestfs(3).
6905 @lines = $g->tail_n ($nrlines, $path);
6907 If the parameter "nrlines" is a positive number, this returns the
6908 last "nrlines" lines of the file "path".
6909 If the parameter "nrlines" is a negative number, this returns lines
6911 from the file "path", starting with the "-nrlines"th line.
6912 If the parameter "nrlines" is zero, this returns an empty list.
6914 Because of the message protocol, there is a transfer limit of
6916 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
6917 guestfs(3).
6918 $g->tar_in ($tarfile, $directory [, compress => $compress] [, xattrs =>
6920 $xattrs] [, selinux => $selinux] [, acls => $acls]);
6921 This command uploads and unpacks local file "tarfile" into
6922 directory.
6923 The optional "compress" flag controls compression. If not given,
6925 then the input should be an uncompressed tar file. Otherwise one
6926 of the following strings may be given to select the compression
6927 type of the input file: "compress", "gzip", "bzip2", "xz", "lzop".
6928 (Note that not all builds of libguestfs will support all of these
6929 compression types).
6930 The other optional arguments are:
6932 "xattrs"
6934 If set to true, extended attributes are restored from the tar
6935 file.
6936 "selinux"
6938 If set to true, SELinux contexts are restored from the tar
6939 file.
6940 "acls"
6942 If set to true, POSIX ACLs are restored from the tar file.
6943 $g->tar_in_opts ($tarfile, $directory [, compress => $compress] [,
6945 xattrs => $xattrs] [, selinux => $selinux] [, acls => $acls]);
6946 This is an alias of "tar_in".
6947 $g->tar_out ($directory, $tarfile [, compress => $compress] [,
6949 numericowner => $numericowner] [, excludes => $excludes] [, xattrs =>
6950 $xattrs] [, selinux => $selinux] [, acls => $acls]);
6951 This command packs the contents of directory and downloads it to
6952 local file "tarfile".
6953 The optional "compress" flag controls compression. If not given,
6955 then the output will be an uncompressed tar file. Otherwise one of
6956 the following strings may be given to select the compression type
6957 of the output file: "compress", "gzip", "bzip2", "xz", "lzop".
6958 (Note that not all builds of libguestfs will support all of these
6959 compression types).
6960 The other optional arguments are:
6962 "excludes"
6964 A list of wildcards. Files are excluded if they match any of
6965 the wildcards.
6966 "numericowner"
6968 If set to true, the output tar file will contain UID/GID
6969 numbers instead of user/group names.
6970 "xattrs"
6972 If set to true, extended attributes are saved in the output
6973 tar.
6974 "selinux"
6976 If set to true, SELinux contexts are saved in the output tar.
6977 "acls"
6979 If set to true, POSIX ACLs are saved in the output tar.
6980 $g->tar_out_opts ($directory, $tarfile [, compress => $compress] [,
6982 numericowner => $numericowner] [, excludes => $excludes] [, xattrs =>
6983 $xattrs] [, selinux => $selinux] [, acls => $acls]);
6984 This is an alias of "tar_out".
6985 $g->tgz_in ($tarball, $directory);
6987 This command uploads and unpacks local file "tarball" (a gzip
6988 compressed tar file) into directory.
6989 This function is deprecated. In new code, use the "tar_in" call
6991 instead.
6992 Deprecated functions will not be removed from the API, but the fact
6994 that they are deprecated indicates that there are problems with
6995 correct use of these functions.
6996 $g->tgz_out ($directory, $tarball);
6998 This command packs the contents of directory and downloads it to
6999 local file "tarball".
7000 This function is deprecated. In new code, use the "tar_out" call
7002 instead.
7003 Deprecated functions will not be removed from the API, but the fact
7005 that they are deprecated indicates that there are problems with
7006 correct use of these functions.
7007 $g->touch ($path);
7009 Touch acts like the touch(1) command. It can be used to update the
7010 timestamps on a file, or, if the file does not exist, to create a
7011 new zero-length file.
7012 This command only works on regular files, and will fail on other
7014 file types such as directories, symbolic links, block special etc.
7015 $g->truncate ($path);
7017 This command truncates "path" to a zero-length file. The file must
7018 exist already.
7019 $g->truncate_size ($path, $size);
7021 This command truncates "path" to size "size" bytes. The file must
7022 exist already.
7023 If the current file size is less than "size" then the file is
7025 extended to the required size with zero bytes. This creates a
7026 sparse file (ie. disk blocks are not allocated for the file until
7027 you write to it). To create a non-sparse file of zeroes, use
7028 "$g->fallocate64" instead.
7029 $g->tune2fs ($device [, force => $force] [, maxmountcount =>
7031 $maxmountcount] [, mountcount => $mountcount] [, errorbehavior =>
7032 $errorbehavior] [, group => $group] [, intervalbetweenchecks =>
7033 $intervalbetweenchecks] [, reservedblockspercentage =>
7034 $reservedblockspercentage] [, lastmounteddirectory =>
7035 $lastmounteddirectory] [, reservedblockscount => $reservedblockscount]
7036 [, user => $user]);
7037 This call allows you to adjust various filesystem parameters of an
7038 ext2/ext3/ext4 filesystem called "device".
7039 The optional parameters are:
7041 "force"
7043 Force tune2fs to complete the operation even in the face of
7044 errors. This is the same as the tune2fs "-f" option.
7045 "maxmountcount"
7047 Set the number of mounts after which the filesystem is checked
7048 by e2fsck(8). If this is 0 then the number of mounts is
7049 disregarded. This is the same as the tune2fs "-c" option.
7050 "mountcount"
7052 Set the number of times the filesystem has been mounted. This
7053 is the same as the tune2fs "-C" option.
7054 "errorbehavior"
7056 Change the behavior of the kernel code when errors are
7057 detected. Possible values currently are: "continue",
7058 "remount-ro", "panic". In practice these options don't really
7059 make any difference, particularly for write errors.
7060 This is the same as the tune2fs "-e" option.
7062 "group"
7064 Set the group which can use reserved filesystem blocks. This
7065 is the same as the tune2fs "-g" option except that it can only
7066 be specified as a number.
7067 "intervalbetweenchecks"
7069 Adjust the maximal time between two filesystem checks (in
7070 seconds). If the option is passed as 0 then time-dependent
7071 checking is disabled.
7072 This is the same as the tune2fs "-i" option.
7074 "reservedblockspercentage"
7076 Set the percentage of the filesystem which may only be
7077 allocated by privileged processes. This is the same as the
7078 tune2fs "-m" option.
7079 "lastmounteddirectory"
7081 Set the last mounted directory. This is the same as the
7082 tune2fs "-M" option.
7083 "reservedblockscount" Set the number of reserved filesystem blocks.
7085 This is the same as the tune2fs "-r" option.
7086 "user"
7087 Set the user who can use the reserved filesystem blocks. This
7088 is the same as the tune2fs "-u" option except that it can only
7089 be specified as a number.
7090 To get the current values of filesystem parameters, see
7092 "$g->tune2fs_l". For precise details of how tune2fs works, see the
7093 tune2fs(8) man page.
7094 %superblock = $g->tune2fs_l ($device);
7096 This returns the contents of the ext2, ext3 or ext4 filesystem
7097 superblock on "device".
7098 It is the same as running "tune2fs -l device". See tune2fs(8)
7100 manpage for more details. The list of fields returned isn't
7101 clearly defined, and depends on both the version of "tune2fs" that
7102 libguestfs was built against, and the filesystem itself.
7103 $g->txz_in ($tarball, $directory);
7105 This command uploads and unpacks local file "tarball" (an xz
7106 compressed tar file) into directory.
7107 This function depends on the feature "xz". See also
7109 "$g->feature-available".
7110 This function is deprecated. In new code, use the "tar_in" call
7112 instead.
7113 Deprecated functions will not be removed from the API, but the fact
7115 that they are deprecated indicates that there are problems with
7116 correct use of these functions.
7117 $g->txz_out ($directory, $tarball);
7119 This command packs the contents of directory and downloads it to
7120 local file "tarball" (as an xz compressed tar archive).
7121 This function depends on the feature "xz". See also
7123 "$g->feature-available".
7124 This function is deprecated. In new code, use the "tar_out" call
7126 instead.
7127 Deprecated functions will not be removed from the API, but the fact
7129 that they are deprecated indicates that there are problems with
7130 correct use of these functions.
7131 $oldmask = $g->umask ($mask);
7133 This function sets the mask used for creating new files and device
7134 nodes to "mask & 0777".
7135 Typical umask values would be 022 which creates new files with
7137 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which
7138 creates new files with permissions like "-rw-rw-r--" or
7139 "-rwxrwxr-x".
7140 The default umask is 022. This is important because it means that
7142 directories and device nodes will be created with 0644 or 0755 mode
7143 even if you specify 0777.
7144 See also "$g->get_umask", umask(2), "$g->mknod", "$g->mkdir".
7146 This call returns the previous umask.
7148 $g->umount ($pathordevice [, force => $force] [, lazyunmount =>
7150 $lazyunmount]);
7151 This unmounts the given filesystem. The filesystem may be
7152 specified either by its mountpoint (path) or the device which
7153 contains the filesystem.
7154 $g->umount_opts ($pathordevice [, force => $force] [, lazyunmount =>
7156 $lazyunmount]);
7157 This is an alias of "umount".
7158 $g->umount_all ();
7160 This unmounts all mounted filesystems.
7161 Some internal mounts are not unmounted by this call.
7163 $g->umount_local ([retry => $retry]);
7165 If libguestfs is exporting the filesystem on a local mountpoint,
7166 then this unmounts it.
7167 See "MOUNT LOCAL" in guestfs(3) for full documentation.
7169 $g->upload ($filename, $remotefilename);
7171 Upload local file filename to remotefilename on the filesystem.
7172 filename can also be a named pipe.
7174 See also "$g->download".
7176 $g->upload_offset ($filename, $remotefilename, $offset);
7178 Upload local file filename to remotefilename on the filesystem.
7179 remotefilename is overwritten starting at the byte "offset"
7181 specified. The intention is to overwrite parts of existing files
7182 or devices, although if a non-existent file is specified then it is
7183 created with a "hole" before "offset". The size of the data
7184 written is implicit in the size of the source filename.
7185 Note that there is no limit on the amount of data that can be
7187 uploaded with this call, unlike with "$g->pwrite", and this call
7188 always writes the full amount unless an error occurs.
7189 See also "$g->upload", "$g->pwrite".
7191 $g->user_cancel ();
7193 This function cancels the current upload or download operation.
7194 Unlike most other libguestfs calls, this function is signal safe
7196 and thread safe. You can call it from a signal handler or from
7197 another thread, without needing to do any locking.
7198 The transfer that was in progress (if there is one) will stop
7200 shortly afterwards, and will return an error. The errno (see
7201 "guestfs_last_errno") is set to "EINTR", so you can test for this
7202 to find out if the operation was cancelled or failed because of
7203 another error.
7204 No cleanup is performed: for example, if a file was being uploaded
7206 then after cancellation there may be a partially uploaded file. It
7207 is the callerXs responsibility to clean up if necessary.
7208 There are two common places that you might call "$g->user_cancel":
7210 In an interactive text-based program, you might call it from a
7212 "SIGINT" signal handler so that pressing "^C" cancels the current
7213 operation. (You also need to call "guestfs_set_pgroup" so that
7214 child processes don't receive the "^C" signal).
7215 In a graphical program, when the main thread is displaying a
7217 progress bar with a cancel button, wire up the cancel button to
7218 call this function.
7219 $g->utimens ($path, $atsecs, $atnsecs, $mtsecs, $mtnsecs);
7221 This command sets the timestamps of a file with nanosecond
7222 precision.
7223 "atsecs, atnsecs" are the last access time (atime) in secs and
7225 nanoseconds from the epoch.
7226 "mtsecs, mtnsecs" are the last modification time (mtime) in secs
7228 and nanoseconds from the epoch.
7229 If the *nsecs field contains the special value "-1" then the
7231 corresponding timestamp is set to the current time. (The *secs
7232 field is ignored in this case).
7233 If the *nsecs field contains the special value "-2" then the
7235 corresponding timestamp is left unchanged. (The *secs field is
7236 ignored in this case).
7237 %uts = $g->utsname ();
7239 This returns the kernel version of the appliance, where this is
7240 available. This information is only useful for debugging. Nothing
7241 in the returned structure is defined by the API.
7242 %version = $g->version ();
7244 Return the libguestfs version number that the program is linked
7245 against.
7246 Note that because of dynamic linking this is not necessarily the
7248 version of libguestfs that you compiled against. You can compile
7249 the program, and then at runtime dynamically link against a
7250 completely different libguestfs.so library.
7251 This call was added in version 1.0.58. In previous versions of
7253 libguestfs there was no way to get the version number. From C code
7254 you can use dynamic linker functions to find out if this symbol
7255 exists (if it doesn't, then itXs an earlier version).
7256 The call returns a structure with four elements. The first three
7258 ("major", "minor" and "release") are numbers and correspond to the
7259 usual version triplet. The fourth element ("extra") is a string
7260 and is normally empty, but may be used for distro-specific
7261 information.
7262 To construct the original version string:
7264 "$major.$minor.$release$extra"
7265 See also: "LIBGUESTFS VERSION NUMBERS" in guestfs(3).
7267 Note: Don't use this call to test for availability of features. In
7269 enterprise distributions we backport features from later versions
7270 into earlier versions, making this an unreliable way to test for
7271 features. Use "$g->available" or "$g->feature_available" instead.
7272 $label = $g->vfs_label ($mountable);
7274 This returns the label of the filesystem on "mountable".
7275 If the filesystem is unlabeled, this returns the empty string.
7277 To find a filesystem from the label, use "$g->findfs_label".
7279 $sizeinbytes = $g->vfs_minimum_size ($mountable);
7281 Get the minimum size of filesystem in bytes. This is the minimum
7282 possible size for filesystem shrinking.
7283 If getting minimum size of specified filesystem is not supported,
7285 this will fail and set errno as ENOTSUP.
7286 See also ntfsresize(8), resize2fs(8), btrfs(8), xfs_info(8).
7288 $fstype = $g->vfs_type ($mountable);
7290 This command gets the filesystem type corresponding to the
7291 filesystem on "mountable".
7292 For most filesystems, the result is the name of the Linux VFS
7294 module which would be used to mount this filesystem if you mounted
7295 it without specifying the filesystem type. For example a string
7296 such as "ext3" or "ntfs".
7297 $uuid = $g->vfs_uuid ($mountable);
7299 This returns the filesystem UUID of the filesystem on "mountable".
7300 If the filesystem does not have a UUID, this returns the empty
7302 string.
7303 To find a filesystem from the UUID, use "$g->findfs_uuid".
7305 $g->vg_activate ($activate, \@volgroups);
7307 This command activates or (if "activate" is false) deactivates all
7308 logical volumes in the listed volume groups "volgroups".
7309 This command is the same as running "vgchange -a y|n volgroups..."
7311 Note that if "volgroups" is an empty list then all volume groups
7313 are activated or deactivated.
7314 This function depends on the feature "lvm2". See also
7316 "$g->feature-available".
7317 $g->vg_activate_all ($activate);
7319 This command activates or (if "activate" is false) deactivates all
7320 logical volumes in all volume groups.
7321 This command is the same as running "vgchange -a y|n"
7323 This function depends on the feature "lvm2". See also
7325 "$g->feature-available".
7326 $g->vgchange_uuid ($vg);
7328 Generate a new random UUID for the volume group "vg".
7329 This function depends on the feature "lvm2". See also
7331 "$g->feature-available".
7332 $g->vgchange_uuid_all ();
7334 Generate new random UUIDs for all volume groups.
7335 This function depends on the feature "lvm2". See also
7337 "$g->feature-available".
7338 $g->vgcreate ($volgroup, \@physvols);
7340 This creates an LVM volume group called "volgroup" from the non-
7341 empty list of physical volumes "physvols".
7342 This function depends on the feature "lvm2". See also
7344 "$g->feature-available".
7345 @uuids = $g->vglvuuids ($vgname);
7347 Given a VG called "vgname", this returns the UUIDs of all the
7348 logical volumes created in this volume group.
7349 You can use this along with "$g->lvs" and "$g->lvuuid" calls to
7351 associate logical volumes and volume groups.
7352 See also "$g->vgpvuuids".
7354 $metadata = $g->vgmeta ($vgname);
7356 "vgname" is an LVM volume group. This command examines the volume
7357 group and returns its metadata.
7358 Note that the metadata is an internal structure used by LVM,
7360 subject to change at any time, and is provided for information
7361 only.
7362 This function depends on the feature "lvm2". See also
7364 "$g->feature-available".
7365 @uuids = $g->vgpvuuids ($vgname);
7367 Given a VG called "vgname", this returns the UUIDs of all the
7368 physical volumes that this volume group resides on.
7369 You can use this along with "$g->pvs" and "$g->pvuuid" calls to
7371 associate physical volumes and volume groups.
7372 See also "$g->vglvuuids".
7374 $g->vgremove ($vgname);
7376 Remove an LVM volume group "vgname", (for example "VG").
7377 This also forcibly removes all logical volumes in the volume group
7379 (if any).
7380 This function depends on the feature "lvm2". See also
7382 "$g->feature-available".
7383 $g->vgrename ($volgroup, $newvolgroup);
7385 Rename a volume group "volgroup" with the new name "newvolgroup".
7386 @volgroups = $g->vgs ();
7388 List all the volumes groups detected. This is the equivalent of
7389 the vgs(8) command.
7390 This returns a list of just the volume group names that were
7392 detected (eg. "VolGroup00").
7393 See also "$g->vgs_full".
7395 This function depends on the feature "lvm2". See also
7397 "$g->feature-available".
7398 @volgroups = $g->vgs_full ();
7400 List all the volumes groups detected. This is the equivalent of
7401 the vgs(8) command. The "full" version includes all fields.
7402 This function depends on the feature "lvm2". See also
7404 "$g->feature-available".
7405 $g->vgscan ();
7407 This rescans all block devices and rebuilds the list of LVM
7408 physical volumes, volume groups and logical volumes.
7409 This function is deprecated. In new code, use the "lvm_scan" call
7411 instead.
7412 Deprecated functions will not be removed from the API, but the fact
7414 that they are deprecated indicates that there are problems with
7415 correct use of these functions.
7416 $uuid = $g->vguuid ($vgname);
7418 This command returns the UUID of the LVM VG named "vgname".
7419 $g->wait_ready ();
7421 This function is a no op.
7422 In versions of the API < 1.0.71 you had to call this function just
7424 after calling "$g->launch" to wait for the launch to complete.
7425 However this is no longer necessary because "$g->launch" now does
7426 the waiting.
7427 If you see any calls to this function in code then you can just
7429 remove them, unless you want to retain compatibility with older
7430 versions of the API.
7431 This function is deprecated. There is no replacement. Consult the
7433 API documentation in guestfs(3) for further information.
7434 Deprecated functions will not be removed from the API, but the fact
7436 that they are deprecated indicates that there are problems with
7437 correct use of these functions.
7438 $chars = $g->wc_c ($path);
7440 This command counts the characters in a file, using the "wc -c"
7441 external command.
7442 $lines = $g->wc_l ($path);
7444 This command counts the lines in a file, using the "wc -l" external
7445 command.
7446 $words = $g->wc_w ($path);
7448 This command counts the words in a file, using the "wc -w" external
7449 command.
7450 $g->wipefs ($device);
7452 This command erases filesystem or RAID signatures from the
7453 specified "device" to make the filesystem invisible to libblkid.
7454 This does not erase the filesystem itself nor any other data from
7456 the "device".
7457 Compare with "$g->zero" which zeroes the first few blocks of a
7459 device.
7460 This function depends on the feature "wipefs". See also
7462 "$g->feature-available".
7463 $g->write ($path, $content);
7465 This call creates a file called "path". The content of the file is
7466 the string "content" (which can contain any 8 bit data).
7467 See also "$g->write_append".
7469 $g->write_append ($path, $content);
7471 This call appends "content" to the end of file "path". If "path"
7472 does not exist, then a new file is created.
7473 See also "$g->write".
7475 $g->write_file ($path, $content, $size);
7477 This call creates a file called "path". The contents of the file
7478 is the string "content" (which can contain any 8 bit data), with
7479 length "size".
7480 As a special case, if "size" is 0 then the length is calculated
7482 using "strlen" (so in this case the content cannot contain embedded
7483 ASCII NULs).
7484 NB. Owing to a bug, writing content containing ASCII NUL characters
7486 does not work, even if the length is specified.
7487 Because of the message protocol, there is a transfer limit of
7489 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7490 guestfs(3).
7491 This function is deprecated. In new code, use the "write" call
7493 instead.
7494 Deprecated functions will not be removed from the API, but the fact
7496 that they are deprecated indicates that there are problems with
7497 correct use of these functions.
7498 $g->xfs_admin ($device [, extunwritten => $extunwritten] [, imgfile =>
7500 $imgfile] [, v2log => $v2log] [, projid32bit => $projid32bit] [,
7501 lazycounter => $lazycounter] [, label => $label] [, uuid => $uuid]);
7502 Change the parameters of the XFS filesystem on "device".
7503 Devices that are mounted cannot be modified. Administrators must
7505 unmount filesystems before this call can modify parameters.
7506 Some of the parameters of a mounted filesystem can be examined and
7508 modified using the "$g->xfs_info" and "$g->xfs_growfs" calls.
7509 This function depends on the feature "xfs". See also
7511 "$g->feature-available".
7512 $g->xfs_growfs ($path [, datasec => $datasec] [, logsec => $logsec] [,
7514 rtsec => $rtsec] [, datasize => $datasize] [, logsize => $logsize] [,
7515 rtsize => $rtsize] [, rtextsize => $rtextsize] [, maxpct => $maxpct]);
7516 Grow the XFS filesystem mounted at "path".
7517 The returned struct contains geometry information. Missing fields
7519 are returned as "-1" (for numeric fields) or empty string.
7520 This function depends on the feature "xfs". See also
7522 "$g->feature-available".
7523 %info = $g->xfs_info ($pathordevice);
7525 "pathordevice" is a mounted XFS filesystem or a device containing
7526 an XFS filesystem. This command returns the geometry of the
7527 filesystem.
7528 The returned struct contains geometry information. Missing fields
7530 are returned as "-1" (for numeric fields) or empty string.
7531 This function depends on the feature "xfs". See also
7533 "$g->feature-available".
7534 $status = $g->xfs_repair ($device [, forcelogzero => $forcelogzero] [,
7536 nomodify => $nomodify] [, noprefetch => $noprefetch] [, forcegeometry
7537 => $forcegeometry] [, maxmem => $maxmem] [, ihashsize => $ihashsize] [,
7538 bhashsize => $bhashsize] [, agstride => $agstride] [, logdev =>
7539 $logdev] [, rtdev => $rtdev]);
7540 Repair corrupt or damaged XFS filesystem on "device".
7541 The filesystem is specified using the "device" argument which
7543 should be the device name of the disk partition or volume
7544 containing the filesystem. If given the name of a block device,
7545 "xfs_repair" will attempt to find the raw device associated with
7546 the specified block device and will use the raw device instead.
7547 Regardless, the filesystem to be repaired must be unmounted,
7549 otherwise, the resulting filesystem may be inconsistent or corrupt.
7550 The returned status indicates whether filesystem corruption was
7552 detected (returns 1) or was not detected (returns 0).
7553 This function depends on the feature "xfs". See also
7555 "$g->feature-available".
7556 $g->yara_destroy ();
7558 Destroy previously loaded Yara rules in order to free libguestfs
7559 resources.
7560 This function depends on the feature "libyara". See also
7562 "$g->feature-available".
7563 $g->yara_load ($filename);
7565 Upload a set of Yara rules from local file filename.
7566 Yara rules allow to categorize files based on textual or binary
7568 patterns within their content. See "$g->yara_scan" to see how to
7569 scan files with the loaded rules.
7570 Rules can be in binary format, as when compiled with yarac command,
7572 or in source code format. In the latter case, the rules will be
7573 first compiled and then loaded.
7574 Rules in source code format cannot include external files. In such
7576 cases, it is recommended to compile them first.
7577 Previously loaded rules will be destroyed.
7579 This function depends on the feature "libyara". See also
7581 "$g->feature-available".
7582 @detections = $g->yara_scan ($path);
7584 Scan a file with the previously loaded Yara rules.
7585 For each matching rule, a "yara_detection" structure is returned.
7587 The "yara_detection" structure contains the following fields.
7589 "yara_name"
7591 Path of the file matching a Yara rule.
7592 "yara_rule"
7594 Identifier of the Yara rule which matched against the given
7595 file.
7596 This function depends on the feature "libyara". See also
7598 "$g->feature-available".
7599 @lines = $g->zegrep ($regex, $path);
7601 This calls the external "zegrep" program and returns the matching
7602 lines.
7603 Because of the message protocol, there is a transfer limit of
7605 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7606 guestfs(3).
7607 This function is deprecated. In new code, use the "grep" call
7609 instead.
7610 Deprecated functions will not be removed from the API, but the fact
7612 that they are deprecated indicates that there are problems with
7613 correct use of these functions.
7614 @lines = $g->zegrepi ($regex, $path);
7616 This calls the external "zegrep -i" program and returns the
7617 matching lines.
7618 Because of the message protocol, there is a transfer limit of
7620 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7621 guestfs(3).
7622 This function is deprecated. In new code, use the "grep" call
7624 instead.
7625 Deprecated functions will not be removed from the API, but the fact
7627 that they are deprecated indicates that there are problems with
7628 correct use of these functions.
7629 $g->zero ($device);
7631 This command writes zeroes over the first few blocks of "device".
7632 How many blocks are zeroed isn't specified (but itXs not enough to
7634 securely wipe the device). It should be sufficient to remove any
7635 partition tables, filesystem superblocks and so on.
7636 If blocks are already zero, then this command avoids writing
7638 zeroes. This prevents the underlying device from becoming non-
7639 sparse or growing unnecessarily.
7640 See also: "$g->zero_device", "$g->scrub_device",
7642 "$g->is_zero_device"
7643 $g->zero_device ($device);
7645 This command writes zeroes over the entire "device". Compare with
7646 "$g->zero" which just zeroes the first few blocks of a device.
7647 If blocks are already zero, then this command avoids writing
7649 zeroes. This prevents the underlying device from becoming non-
7650 sparse or growing unnecessarily.
7651 $g->zero_free_space ($directory);
7653 Zero the free space in the filesystem mounted on directory. The
7654 filesystem must be mounted read-write.
7655 The filesystem contents are not affected, but any free space in the
7657 filesystem is freed.
7658 Free space is not "trimmed". You may want to call "$g->fstrim"
7660 either as an alternative to this, or after calling this, depending
7661 on your requirements.
7662 $g->zerofree ($device);
7664 This runs the zerofree program on "device". This program claims to
7665 zero unused inodes and disk blocks on an ext2/3 filesystem, thus
7666 making it possible to compress the filesystem more effectively.
7667 You should not run this program if the filesystem is mounted.
7669 It is possible that using this program can damage the filesystem or
7671 data on the filesystem.
7672 This function depends on the feature "zerofree". See also
7674 "$g->feature-available".
7675 @lines = $g->zfgrep ($pattern, $path);
7677 This calls the external "zfgrep" program and returns the matching
7678 lines.
7679 Because of the message protocol, there is a transfer limit of
7681 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7682 guestfs(3).
7683 This function is deprecated. In new code, use the "grep" call
7685 instead.
7686 Deprecated functions will not be removed from the API, but the fact
7688 that they are deprecated indicates that there are problems with
7689 correct use of these functions.
7690 @lines = $g->zfgrepi ($pattern, $path);
7692 This calls the external "zfgrep -i" program and returns the
7693 matching lines.
7694 Because of the message protocol, there is a transfer limit of
7696 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7697 guestfs(3).
7698 This function is deprecated. In new code, use the "grep" call
7700 instead.
7701 Deprecated functions will not be removed from the API, but the fact
7703 that they are deprecated indicates that there are problems with
7704 correct use of these functions.
7705 $description = $g->zfile ($meth, $path);
7707 This command runs file after first decompressing "path" using
7708 "method".
7709 "method" must be one of "gzip", "compress" or "bzip2".
7711 Since 1.0.63, use "$g->file" instead which can now process
7713 compressed files.
7714 This function is deprecated. In new code, use the "file" call
7716 instead.
7717 Deprecated functions will not be removed from the API, but the fact
7719 that they are deprecated indicates that there are problems with
7720 correct use of these functions.
7721 @lines = $g->zgrep ($regex, $path);
7723 This calls the external "zgrep" program and returns the matching
7724 lines.
7725 Because of the message protocol, there is a transfer limit of
7727 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7728 guestfs(3).
7729 This function is deprecated. In new code, use the "grep" call
7731 instead.
7732 Deprecated functions will not be removed from the API, but the fact
7734 that they are deprecated indicates that there are problems with
7735 correct use of these functions.
7736 @lines = $g->zgrepi ($regex, $path);
7738 This calls the external "zgrep -i" program and returns the matching
7739 lines.
7740 Because of the message protocol, there is a transfer limit of
7742 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7743 guestfs(3).
7744 This function is deprecated. In new code, use the "grep" call
7746 instead.
7747 Deprecated functions will not be removed from the API, but the fact
7749 that they are deprecated indicates that there are problems with
7750 correct use of these functions.
7751
7753 From time to time we add new libguestfs APIs. Also some libguestfs
7754 APIs won't be available in all builds of libguestfs (the Fedora build
7755 is full-featured, but other builds may disable features). How do you
7756 test whether the APIs that your Perl program needs are available in the
7757 version of "Sys::Guestfs" that you are using?
7758 To test if a particular function is available in the "Sys::Guestfs"
7760 class, use the ordinary Perl UNIVERSAL method "can(METHOD)" (see
7761 perlobj(1)). For example:
7762 use Sys::Guestfs;
7764 if (defined (Sys::Guestfs->can ("set_verbose"))) {
7765 print "\$g->set_verbose is available\n";
7766 }
7767 To test if particular features are supported by the current build, use
7769 the "feature_available" method like the example below. Note that the
7770 appliance must be launched first.
7771 $g->feature_available ( ["augeas"] );
7773 For further discussion on this topic, refer to "AVAILABILITY" in
7775 guestfs(3).
7776
7778 The handle returned from "new" is a hash reference. The hash normally
7779 contains some elements:
7780 {
7782 _g => [private data used by libguestfs],
7783 _flags => [flags provided when creating the handle]
7784 }
7785 Callers can add other elements to this hash to store data for their own
7787 purposes. The data lasts for the lifetime of the handle.
7788 Any fields whose names begin with an underscore are reserved for
7790 private use by libguestfs. We may add more in future.
7791 It is recommended that callers prefix the name of their field(s) with
7793 some unique string, to avoid conflicts with other users.
7794
7796 Copyright (C) 2009-2019 Red Hat Inc.
7797
7799 Please see the file COPYING.LIB for the full license.
7800
7802 guestfs(3), guestfish(1), <http://libguestfs.org>.
7803perl v5.28.1 2019-03-26 Sys::Guestfs(3)