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 <https://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 <https://libvirt.org/uri.html>). If this is not set then we
252 connect to the default libvirt URI (or one set through an
253 environment variable, see the libvirt documentation for full
254 details).
255 The optional "live" flag controls whether this call will try to
257 connect to a running virtual machine "guestfsd" process if it sees
258 a suitable <channel> element in the libvirt XML definition. The
259 default (if the flag is omitted) is never to try. See "ATTACHING
260 TO RUNNING DAEMONS" in guestfs(3) for more information.
261 If the "allowuuid" flag is true (default is false) then a UUID may
263 be passed instead of the domain name. The "dom" string is treated
264 as a UUID first and looked up, and if that lookup fails then we
265 treat "dom" as a name as usual.
266 The optional "readonlydisk" parameter controls what we do for disks
268 which are marked <readonly/> in the libvirt XML. Possible values
269 are:
270 readonlydisk = "error"
272 If "readonly" is false:
273 The whole call is aborted with an error if any disk with the
275 <readonly/> flag is found.
276 If "readonly" is true:
278 Disks with the <readonly/> flag are added read-only.
280 readonlydisk = "read"
282 If "readonly" is false:
283 Disks with the <readonly/> flag are added read-only. Other
285 disks are added read/write.
286 If "readonly" is true:
288 Disks with the <readonly/> flag are added read-only.
290 readonlydisk = "write" (default)
292 If "readonly" is false:
293 Disks with the <readonly/> flag are added read/write.
295 If "readonly" is true:
297 Disks with the <readonly/> flag are added read-only.
299 readonlydisk = "ignore"
301 If "readonly" is true or false:
302 Disks with the <readonly/> flag are skipped.
304 If present, the value of "logical_block_size" attribute of
306 <blockio/> tag in libvirt XML will be passed as "blocksize"
307 parameter to "$g->add_drive_opts".
308 The other optional parameters are passed directly through to
310 "$g->add_drive_opts".
311 $g->add_drive ($filename [, readonly => $readonly] [, format =>
313 $format] [, iface => $iface] [, name => $name] [, label => $label] [,
314 protocol => $protocol] [, server => $server] [, username => $username]
315 [, secret => $secret] [, cachemode => $cachemode] [, discard =>
316 $discard] [, copyonread => $copyonread] [, blocksize => $blocksize]);
317 This function adds a disk image called filename to the handle.
318 filename may be a regular host file or a host device.
319 When this function is called before "$g->launch" (the usual case)
321 then the first time you call this function, the disk appears in the
322 API as /dev/sda, the second time as /dev/sdb, and so on.
323 In libguestfs X 1.20 you can also call this function after launch
325 (with some restrictions). This is called "hotplugging". When
326 hotplugging, you must specify a "label" so that the new disk gets a
327 predictable name. For more information see "HOTPLUGGING" in
328 guestfs(3).
329 You don't necessarily need to be root when using libguestfs.
331 However you obviously do need sufficient permissions to access the
332 filename for whatever operations you want to perform (ie. read
333 access if you just want to read the image or write access if you
334 want to modify the image).
335 This call checks that filename exists.
337 filename may be the special string "/dev/null". See "NULL DISKS"
339 in guestfs(3).
340 The optional arguments are:
342 "readonly"
344 If true then the image is treated as read-only. Writes are
345 still allowed, but they are stored in a temporary snapshot
346 overlay which is discarded at the end. The disk that you add
347 is not modified.
348 "format"
350 This forces the image format. If you omit this (or use
351 "$g->add_drive" or "$g->add_drive_ro") then the format is
352 automatically detected. Possible formats include "raw" and
353 "qcow2".
354 Automatic detection of the format opens you up to a potential
356 security hole when dealing with untrusted raw-format images.
357 See CVE-2010-3851 and RHBZ#642934. Specifying the format
358 closes this security hole.
359 "iface"
361 This rarely-used option lets you emulate the behaviour of the
362 deprecated "$g->add_drive_with_if" call (q.v.)
363 "name"
365 The name the drive had in the original guest, e.g. /dev/sdb.
366 This is used as a hint to the guest inspection process if it is
367 available.
368 "label"
370 Give the disk a label. The label should be a unique, short
371 string using only ASCII characters "[a-zA-Z]". As well as its
372 usual name in the API (such as /dev/sda), the drive will also
373 be named /dev/disk/guestfs/label.
374 See "DISK LABELS" in guestfs(3).
376 "protocol"
378 The optional protocol argument can be used to select an
379 alternate source protocol.
380 See also: "REMOTE STORAGE" in guestfs(3).
382 "protocol = "file""
384 filename is interpreted as a local file or device. This is
385 the default if the optional protocol parameter is omitted.
386 "protocol = "ftp"|"ftps"|"http"|"https"|"tftp""
388 Connect to a remote FTP, HTTP or TFTP server. The "server"
389 parameter must also be supplied - see below.
390 See also: "FTP, HTTP AND TFTP" in guestfs(3)
392 "protocol = "gluster""
394 Connect to the GlusterFS server. The "server" parameter
395 must also be supplied - see below.
396 See also: "GLUSTER" in guestfs(3)
398 "protocol = "iscsi""
400 Connect to the iSCSI server. The "server" parameter must
401 also be supplied - see below. The "username" parameter may
402 be supplied. See below. The "secret" parameter may be
403 supplied. See below.
404 See also: "ISCSI" in guestfs(3).
406 "protocol = "nbd""
408 Connect to the Network Block Device server. The "server"
409 parameter must also be supplied - see below.
410 See also: "NETWORK BLOCK DEVICE" in guestfs(3).
412 "protocol = "rbd""
414 Connect to the Ceph (librbd/RBD) server. The "server"
415 parameter must also be supplied - see below. The
416 "username" parameter may be supplied. See below. The
417 "secret" parameter may be supplied. See below.
418 See also: "CEPH" in guestfs(3).
420 "protocol = "sheepdog""
422 Connect to the Sheepdog server. The "server" parameter may
423 also be supplied - see below.
424 See also: "SHEEPDOG" in guestfs(3).
426 "protocol = "ssh""
428 Connect to the Secure Shell (ssh) server.
429 The "server" parameter must be supplied. The "username"
431 parameter may be supplied. See below.
432 See also: "SSH" in guestfs(3).
434 "server"
436 For protocols which require access to a remote server, this is
437 a list of server(s).
438 Protocol Number of servers required
440 -------- --------------------------
441 file List must be empty or param not used at all
442 ftp|ftps|http|https|tftp Exactly one
443 gluster Exactly one
444 iscsi Exactly one
445 nbd Exactly one
446 rbd Zero or more
447 sheepdog Zero or more
448 ssh Exactly one
449 Each list element is a string specifying a server. The string
451 must be in one of the following formats:
452 hostname
454 hostname:port
455 tcp:hostname
456 tcp:hostname:port
457 unix:/path/to/socket
458 If the port number is omitted, then the standard port number
460 for the protocol is used (see /etc/services).
461 "username"
463 For the "ftp", "ftps", "http", "https", "iscsi", "rbd", "ssh"
464 and "tftp" protocols, this specifies the remote username.
465 If not given, then the local username is used for "ssh", and no
467 authentication is attempted for ceph. But note this sometimes
468 may give unexpected results, for example if using the libvirt
469 backend and if the libvirt backend is configured to start the
470 qemu appliance as a special user such as "qemu.qemu". If in
471 doubt, specify the remote username you want.
472 "secret"
474 For the "rbd" protocol only, this specifies the XsecretX to use
475 when connecting to the remote device. It must be base64
476 encoded.
477 If not given, then a secret matching the given username will be
479 looked up in the default keychain locations, or if no username
480 is given, then no authentication will be used.
481 "cachemode"
483 Choose whether or not libguestfs will obey sync operations
484 (safe but slow) or not (unsafe but fast). The possible values
485 for this string are:
486 "cachemode = "writeback""
488 This is the default.
489 Write operations in the API do not return until a write(2)
491 call has completed in the host [but note this does not
492 imply that anything gets written to disk].
493 Sync operations in the API, including implicit syncs caused
495 by filesystem journalling, will not return until an
496 fdatasync(2) call has completed in the host, indicating
497 that data has been committed to disk.
498 "cachemode = "unsafe""
500 In this mode, there are no guarantees. Libguestfs may
501 cache anything and ignore sync requests. This is suitable
502 only for scratch or temporary disks.
503 "discard"
505 Enable or disable discard (a.k.a. trim or unmap) support on
506 this drive. If enabled, operations such as "$g->fstrim" will
507 be able to discard / make thin / punch holes in the underlying
508 host file or device.
509 Possible discard settings are:
511 "discard = "disable""
513 Disable discard support. This is the default.
514 "discard = "enable""
516 Enable discard support. Fail if discard is not possible.
517 "discard = "besteffort""
519 Enable discard support if possible, but don't fail if it is
520 not supported.
521 Since not all backends and not all underlying systems
523 support discard, this is a good choice if you want to use
524 discard if possible, but don't mind if it doesn't work.
525 "copyonread"
527 The boolean parameter "copyonread" enables copy-on-read
528 support. This only affects disk formats which have backing
529 files, and causes reads to be stored in the overlay layer,
530 speeding up multiple reads of the same area of disk.
531 The default is false.
533 "blocksize"
535 This parameter sets the sector size of the disk. Possible
536 values are 512 (the default if the parameter is omitted) or
537 4096. Use 4096 when handling an "Advanced Format" disk that
538 uses 4K sector size
539 (<https://en.wikipedia.org/wiki/Advanced_Format>).
540 Only a subset of the backends support this parameter (currently
542 only the libvirt and direct backends do).
543 $g->add_drive_opts ($filename [, readonly => $readonly] [, format =>
545 $format] [, iface => $iface] [, name => $name] [, label => $label] [,
546 protocol => $protocol] [, server => $server] [, username => $username]
547 [, secret => $secret] [, cachemode => $cachemode] [, discard =>
548 $discard] [, copyonread => $copyonread] [, blocksize => $blocksize]);
549 This is an alias of "add_drive".
550 $g->add_drive_ro ($filename);
552 This function is the equivalent of calling "$g->add_drive_opts"
553 with the optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set
554 to 1, so the disk is added read-only, with the format being
555 detected automatically.
556 $g->add_drive_ro_with_if ($filename, $iface);
558 This is the same as "$g->add_drive_ro" but it allows you to specify
559 the QEMU interface emulation to use at run time.
560 This function is deprecated. In new code, use the "add_drive" call
562 instead.
563 Deprecated functions will not be removed from the API, but the fact
565 that they are deprecated indicates that there are problems with
566 correct use of these functions.
567 $g->add_drive_scratch ($size [, name => $name] [, label => $label] [,
569 blocksize => $blocksize]);
570 This command adds a temporary scratch drive to the handle. The
571 "size" parameter is the virtual size (in bytes). The scratch drive
572 is blank initially (all reads return zeroes until you start writing
573 to it). The drive is deleted when the handle is closed.
574 The optional arguments "name", "label" and "blocksize" are passed
576 through to "$g->add_drive_opts".
577 $g->add_drive_with_if ($filename, $iface);
579 This is the same as "$g->add_drive" but it allows you to specify
580 the QEMU interface emulation to use at run time.
581 This function is deprecated. In new code, use the "add_drive" call
583 instead.
584 Deprecated functions will not be removed from the API, but the fact
586 that they are deprecated indicates that there are problems with
587 correct use of these functions.
588 $nrdisks = $g->add_libvirt_dom ($dom [, readonly => $readonly] [, iface
590 => $iface] [, live => $live] [, readonlydisk => $readonlydisk] [,
591 cachemode => $cachemode] [, discard => $discard] [, copyonread =>
592 $copyonread]);
593 This function adds the disk(s) attached to the libvirt domain
594 "dom". It works by requesting the domain XML from libvirt, parsing
595 it for disks, and calling "$g->add_drive_opts" on each one.
596 In the C API we declare "void *dom", but really it has type
598 "virDomainPtr dom". This is so we don't need <libvirt.h>.
599 The number of disks added is returned. This operation is atomic:
601 if an error is returned, then no disks are added.
602 This function does some minimal checks to make sure the libvirt
604 domain is not running (unless "readonly" is true). In a future
605 version we will try to acquire the libvirt lock on each disk.
606 Disks must be accessible locally. This often means that adding
608 disks from a remote libvirt connection (see
609 <https://libvirt.org/remote.html>) will fail unless those disks are
610 accessible via the same device path locally too.
611 The optional "live" flag controls whether this call will try to
613 connect to a running virtual machine "guestfsd" process if it sees
614 a suitable <channel> element in the libvirt XML definition. The
615 default (if the flag is omitted) is never to try. See "ATTACHING
616 TO RUNNING DAEMONS" in guestfs(3) for more information.
617 The optional "readonlydisk" parameter controls what we do for disks
619 which are marked <readonly/> in the libvirt XML. See
620 "$g->add_domain" for possible values.
621 If present, the value of "logical_block_size" attribute of
623 <blockio/> tag in libvirt XML will be passed as "blocksize"
624 parameter to "$g->add_drive_opts".
625 The other optional parameters are passed directly through to
627 "$g->add_drive_opts".
628 $g->aug_clear ($augpath);
630 Set the value associated with "path" to "NULL". This is the same
631 as the augtool(1) "clear" command.
632 $g->aug_close ();
634 Close the current Augeas handle and free up any resources used by
635 it. After calling this, you have to call "$g->aug_init" again
636 before you can use any other Augeas functions.
637 %nrnodescreated = $g->aug_defnode ($name, $expr, $val);
639 Defines a variable "name" whose value is the result of evaluating
640 "expr".
641 If "expr" evaluates to an empty nodeset, a node is created,
643 equivalent to calling "$g->aug_set" "expr", "val". "name" will be
644 the nodeset containing that single node.
645 On success this returns a pair containing the number of nodes in
647 the nodeset, and a boolean flag if a node was created.
648 $nrnodes = $g->aug_defvar ($name, $expr);
650 Defines an Augeas variable "name" whose value is the result of
651 evaluating "expr". If "expr" is NULL, then "name" is undefined.
652 On success this returns the number of nodes in "expr", or 0 if
654 "expr" evaluates to something which is not a nodeset.
655 $val = $g->aug_get ($augpath);
657 Look up the value associated with "path". If "path" matches
658 exactly one node, the "value" is returned.
659 $g->aug_init ($root, $flags);
661 Create a new Augeas handle for editing configuration files. If
662 there was any previous Augeas handle associated with this guestfs
663 session, then it is closed.
664 You must call this before using any other "$g->aug_*" commands.
666 "root" is the filesystem root. "root" must not be NULL, use /
668 instead.
669 The flags are the same as the flags defined in <augeas.h>, the
671 logical or of the following integers:
672 "AUG_SAVE_BACKUP" = 1
674 Keep the original file with a ".augsave" extension.
675 "AUG_SAVE_NEWFILE" = 2
677 Save changes into a file with extension ".augnew", and do not
678 overwrite original. Overrides "AUG_SAVE_BACKUP".
679 "AUG_TYPE_CHECK" = 4
681 Typecheck lenses.
682 This option is only useful when debugging Augeas lenses. Use
684 of this option may require additional memory for the libguestfs
685 appliance. You may need to set the "LIBGUESTFS_MEMSIZE"
686 environment variable or call "$g->set_memsize".
687 "AUG_NO_STDINC" = 8
689 Do not use standard load path for modules.
690 "AUG_SAVE_NOOP" = 16
692 Make save a no-op, just record what would have been changed.
693 "AUG_NO_LOAD" = 32
695 Do not load the tree in "$g->aug_init".
696 To close the handle, you can call "$g->aug_close".
698 To find out more about Augeas, see <http://augeas.net/>.
700 $g->aug_insert ($augpath, $label, $before);
702 Create a new sibling "label" for "path", inserting it into the tree
703 before or after "path" (depending on the boolean flag "before").
704 "path" must match exactly one existing node in the tree, and
706 "label" must be a label, ie. not contain /, "*" or end with a
707 bracketed index "[N]".
708 $label = $g->aug_label ($augpath);
710 The label (name of the last element) of the Augeas path expression
711 "augpath" is returned. "augpath" must match exactly one node, else
712 this function returns an error.
713 $g->aug_load ();
715 Load files into the tree.
716 See "aug_load" in the Augeas documentation for the full gory
718 details.
719 @matches = $g->aug_ls ($augpath);
721 This is just a shortcut for listing "$g->aug_match" "path/*" and
722 sorting the resulting nodes into alphabetical order.
723 @matches = $g->aug_match ($augpath);
725 Returns a list of paths which match the path expression "path".
726 The returned paths are sufficiently qualified so that they match
727 exactly one node in the current tree.
728 $g->aug_mv ($src, $dest);
730 Move the node "src" to "dest". "src" must match exactly one node.
731 "dest" is overwritten if it exists.
732 $nrnodes = $g->aug_rm ($augpath);
734 Remove "path" and all of its children.
735 On success this returns the number of entries which were removed.
737 $g->aug_save ();
739 This writes all pending changes to disk.
740 The flags which were passed to "$g->aug_init" affect exactly how
742 files are saved.
743 $g->aug_set ($augpath, $val);
745 Set the value associated with "augpath" to "val".
746 In the Augeas API, it is possible to clear a node by setting the
748 value to NULL. Due to an oversight in the libguestfs API you
749 cannot do that with this call. Instead you must use the
750 "$g->aug_clear" call.
751 $nodes = $g->aug_setm ($base, $sub, $val);
753 Change multiple Augeas nodes in a single operation. "base" is an
754 expression matching multiple nodes. "sub" is a path expression
755 relative to "base". All nodes matching "base" are found, and then
756 for each node, "sub" is changed to "val". "sub" may also be "NULL"
757 in which case the "base" nodes are modified.
758 This returns the number of nodes modified.
760 $g->aug_transform ($lens, $file [, remove => $remove]);
762 Add an Augeas transformation for the specified "lens" so it can
763 handle "file".
764 If "remove" is true ("false" by default), then the transformation
766 is removed.
767 $g->available (\@groups);
769 This command is used to check the availability of some groups of
770 functionality in the appliance, which not all builds of the
771 libguestfs appliance will be able to provide.
772 The libguestfs groups, and the functions that those groups
774 correspond to, are listed in "AVAILABILITY" in guestfs(3). You can
775 also fetch this list at runtime by calling
776 "$g->available_all_groups".
777 The argument "groups" is a list of group names, eg: "["inotify",
779 "augeas"]" would check for the availability of the Linux inotify
780 functions and Augeas (configuration file editing) functions.
781 The command returns no error if all requested groups are available.
783 It fails with an error if one or more of the requested groups is
785 unavailable in the appliance.
786 If an unknown group name is included in the list of groups then an
788 error is always returned.
789 Notes:
791 • "$g->feature_available" is the same as this call, but with a
793 slightly simpler to use API: that call returns a boolean
794 true/false instead of throwing an error.
795 • You must call "$g->launch" before calling this function.
797 The reason is because we don't know what groups are supported
799 by the appliance/daemon until it is running and can be queried.
800 • If a group of functions is available, this does not necessarily
802 mean that they will work. You still have to check for errors
803 when calling individual API functions even if they are
804 available.
805 • It is usually the job of distro packagers to build complete
807 functionality into the libguestfs appliance. Upstream
808 libguestfs, if built from source with all requirements
809 satisfied, will support everything.
810 • This call was added in version 1.0.80. In previous versions of
812 libguestfs all you could do would be to speculatively execute a
813 command to find out if the daemon implemented it. See also
814 "$g->version".
815 See also "$g->filesystem_available".
817 @groups = $g->available_all_groups ();
819 This command returns a list of all optional groups that this daemon
820 knows about. Note this returns both supported and unsupported
821 groups. To find out which ones the daemon can actually support you
822 have to call "$g->available" / "$g->feature_available" on each
823 member of the returned list.
824 See also "$g->available", "$g->feature_available" and
826 "AVAILABILITY" in guestfs(3).
827 $g->base64_in ($base64file, $filename);
829 This command uploads base64-encoded data from "base64file" to
830 filename.
831 $g->base64_out ($filename, $base64file);
833 This command downloads the contents of filename, writing it out to
834 local file "base64file" encoded as base64.
835 $g->blkdiscard ($device);
837 This discards all blocks on the block device "device", giving the
838 free space back to the host.
839 This operation requires support in libguestfs, the host filesystem,
841 qemu and the host kernel. If this support isn't present it may
842 give an error or even appear to run but do nothing. You must also
843 set the "discard" attribute on the underlying drive (see
844 "$g->add_drive_opts").
845 This function depends on the feature "blkdiscard". See also
847 "$g->feature-available".
848 $zeroes = $g->blkdiscardzeroes ($device);
850 This call returns true if blocks on "device" that have been
851 discarded by a call to "$g->blkdiscard" are returned as blocks of
852 zero bytes when read the next time.
853 If it returns false, then it may be that discarded blocks are read
855 as stale or random data.
856 This function depends on the feature "blkdiscardzeroes". See also
858 "$g->feature-available".
859 %info = $g->blkid ($device);
861 This command returns block device attributes for "device". The
862 following fields are usually present in the returned hash. Other
863 fields may also be present.
864 "UUID"
866 The uuid of this device.
867 "LABEL"
869 The label of this device.
870 "VERSION"
872 The version of blkid command.
873 "TYPE"
875 The filesystem type or RAID of this device.
876 "USAGE"
878 The usage of this device, for example "filesystem" or "raid".
879 $g->blockdev_flushbufs ($device);
881 This tells the kernel to flush internal buffers associated with
882 "device".
883 This uses the blockdev(8) command.
885 $blocksize = $g->blockdev_getbsz ($device);
887 This returns the block size of a device.
888 Note: this is different from both size in blocks and filesystem
890 block size. Also this setting is not really used by anything. You
891 should probably not use it for anything. Filesystems have their
892 own idea about what block size to choose.
893 This uses the blockdev(8) command.
895 $ro = $g->blockdev_getro ($device);
897 Returns a boolean indicating if the block device is read-only (true
898 if read-only, false if not).
899 This uses the blockdev(8) command.
901 $sizeinbytes = $g->blockdev_getsize64 ($device);
903 This returns the size of the device in bytes.
904 See also "$g->blockdev_getsz".
906 This uses the blockdev(8) command.
908 $sectorsize = $g->blockdev_getss ($device);
910 This returns the size of sectors on a block device. Usually 512,
911 but can be larger for modern devices.
912 (Note, this is not the size in sectors, use "$g->blockdev_getsz"
914 for that).
915 This uses the blockdev(8) command.
917 $sizeinsectors = $g->blockdev_getsz ($device);
919 This returns the size of the device in units of 512-byte sectors
920 (even if the sectorsize isn't 512 bytes ... weird).
921 See also "$g->blockdev_getss" for the real sector size of the
923 device, and "$g->blockdev_getsize64" for the more useful size in
924 bytes.
925 This uses the blockdev(8) command.
927 $g->blockdev_rereadpt ($device);
929 Reread the partition table on "device".
930 This uses the blockdev(8) command.
932 $g->blockdev_setbsz ($device, $blocksize);
934 This call does nothing and has never done anything because of a bug
935 in blockdev. Do not use it.
936 If you need to set the filesystem block size, use the "blocksize"
938 option of "$g->mkfs".
939 This function is deprecated. There is no replacement. Consult the
941 API documentation in guestfs(3) for further information.
942 Deprecated functions will not be removed from the API, but the fact
944 that they are deprecated indicates that there are problems with
945 correct use of these functions.
946 $g->blockdev_setra ($device, $sectors);
948 Set readahead (in 512-byte sectors) for the device.
949 This uses the blockdev(8) command.
951 $g->blockdev_setro ($device);
953 Sets the block device named "device" to read-only.
954 This uses the blockdev(8) command.
956 $g->blockdev_setrw ($device);
958 Sets the block device named "device" to read-write.
959 This uses the blockdev(8) command.
961 $g->btrfs_balance_cancel ($path);
963 Cancel a running balance on a btrfs filesystem.
964 This function depends on the feature "btrfs". See also
966 "$g->feature-available".
967 $g->btrfs_balance_pause ($path);
969 Pause a running balance on a btrfs filesystem.
970 This function depends on the feature "btrfs". See also
972 "$g->feature-available".
973 $g->btrfs_balance_resume ($path);
975 Resume a paused balance on a btrfs filesystem.
976 This function depends on the feature "btrfs". See also
978 "$g->feature-available".
979 %status = $g->btrfs_balance_status ($path);
981 Show the status of a running or paused balance on a btrfs
982 filesystem.
983 This function depends on the feature "btrfs". See also
985 "$g->feature-available".
986 $g->btrfs_device_add (\@devices, $fs);
988 Add the list of device(s) in "devices" to the btrfs filesystem
989 mounted at "fs". If "devices" is an empty list, this does nothing.
990 This function depends on the feature "btrfs". See also
992 "$g->feature-available".
993 $g->btrfs_device_delete (\@devices, $fs);
995 Remove the "devices" from the btrfs filesystem mounted at "fs". If
996 "devices" is an empty list, this does nothing.
997 This function depends on the feature "btrfs". See also
999 "$g->feature-available".
1000 $g->btrfs_filesystem_balance ($fs);
1002 Balance the chunks in the btrfs filesystem mounted at "fs" across
1003 the underlying devices.
1004 This function depends on the feature "btrfs". See also
1006 "$g->feature-available".
1007 $g->btrfs_filesystem_defragment ($path [, flush => $flush] [, compress
1009 => $compress]);
1010 Defragment a file or directory on a btrfs filesystem. compress is
1011 one of zlib or lzo.
1012 This function depends on the feature "btrfs". See also
1014 "$g->feature-available".
1015 $g->btrfs_filesystem_resize ($mountpoint [, size => $size]);
1017 This command resizes a btrfs filesystem.
1018 Note that unlike other resize calls, the filesystem has to be
1020 mounted and the parameter is the mountpoint not the device (this is
1021 a requirement of btrfs itself).
1022 The optional parameters are:
1024 "size"
1026 The new size (in bytes) of the filesystem. If omitted, the
1027 filesystem is resized to the maximum size.
1028 See also btrfs(8).
1030 This function depends on the feature "btrfs". See also
1032 "$g->feature-available".
1033 @devices = $g->btrfs_filesystem_show ($device);
1035 Show all the devices where the filesystems in "device" is spanned
1036 over.
1037 If not all the devices for the filesystems are present, then this
1039 function fails and the "errno" is set to "ENODEV".
1040 This function depends on the feature "btrfs". See also
1042 "$g->feature-available".
1043 $g->btrfs_filesystem_sync ($fs);
1045 Force sync on the btrfs filesystem mounted at "fs".
1046 This function depends on the feature "btrfs". See also
1048 "$g->feature-available".
1049 $g->btrfs_fsck ($device [, superblock => $superblock] [, repair =>
1051 $repair]);
1052 Used to check a btrfs filesystem, "device" is the device file where
1053 the filesystem is stored.
1054 This function depends on the feature "btrfs". See also
1056 "$g->feature-available".
1057 $g->btrfs_image (\@source, $image [, compresslevel => $compresslevel]);
1059 This is used to create an image of a btrfs filesystem. All data
1060 will be zeroed, but metadata and the like is preserved.
1061 This function depends on the feature "btrfs". See also
1063 "$g->feature-available".
1064 $g->btrfs_qgroup_assign ($src, $dst, $path);
1066 Add qgroup "src" to parent qgroup "dst". This command can group
1067 several qgroups into a parent qgroup to share common limit.
1068 This function depends on the feature "btrfs". See also
1070 "$g->feature-available".
1071 $g->btrfs_qgroup_create ($qgroupid, $subvolume);
1073 Create a quota group (qgroup) for subvolume at "subvolume".
1074 This function depends on the feature "btrfs". See also
1076 "$g->feature-available".
1077 $g->btrfs_qgroup_destroy ($qgroupid, $subvolume);
1079 Destroy a quota group.
1080 This function depends on the feature "btrfs". See also
1082 "$g->feature-available".
1083 $g->btrfs_qgroup_limit ($subvolume, $size);
1085 Limit the size of the subvolume with path "subvolume".
1086 This function depends on the feature "btrfs". See also
1088 "$g->feature-available".
1089 $g->btrfs_qgroup_remove ($src, $dst, $path);
1091 Remove qgroup "src" from the parent qgroup "dst".
1092 This function depends on the feature "btrfs". See also
1094 "$g->feature-available".
1095 @qgroups = $g->btrfs_qgroup_show ($path);
1097 Show all subvolume quota groups in a btrfs filesystem, including
1098 their usages.
1099 This function depends on the feature "btrfs". See also
1101 "$g->feature-available".
1102 $g->btrfs_quota_enable ($fs, $enable);
1104 Enable or disable subvolume quota support for filesystem which
1105 contains "path".
1106 This function depends on the feature "btrfs". See also
1108 "$g->feature-available".
1109 $g->btrfs_quota_rescan ($fs);
1111 Trash all qgroup numbers and scan the metadata again with the
1112 current config.
1113 This function depends on the feature "btrfs". See also
1115 "$g->feature-available".
1116 $g->btrfs_replace ($srcdev, $targetdev, $mntpoint);
1118 Replace device of a btrfs filesystem. On a live filesystem,
1119 duplicate the data to the target device which is currently stored
1120 on the source device. After completion of the operation, the
1121 source device is wiped out and removed from the filesystem.
1122 The "targetdev" needs to be same size or larger than the "srcdev".
1124 Devices which are currently mounted are never allowed to be used as
1125 the "targetdev".
1126 This function depends on the feature "btrfs". See also
1128 "$g->feature-available".
1129 $g->btrfs_rescue_chunk_recover ($device);
1131 Recover the chunk tree of btrfs filesystem by scanning the devices
1132 one by one.
1133 This function depends on the feature "btrfs". See also
1135 "$g->feature-available".
1136 $g->btrfs_rescue_super_recover ($device);
1138 Recover bad superblocks from good copies.
1139 This function depends on the feature "btrfs". See also
1141 "$g->feature-available".
1142 $g->btrfs_scrub_cancel ($path);
1144 Cancel a running scrub on a btrfs filesystem.
1145 This function depends on the feature "btrfs". See also
1147 "$g->feature-available".
1148 $g->btrfs_scrub_resume ($path);
1150 Resume a previously canceled or interrupted scrub on a btrfs
1151 filesystem.
1152 This function depends on the feature "btrfs". See also
1154 "$g->feature-available".
1155 $g->btrfs_scrub_start ($path);
1157 Reads all the data and metadata on the filesystem, and uses
1158 checksums and the duplicate copies from RAID storage to identify
1159 and repair any corrupt data.
1160 This function depends on the feature "btrfs". See also
1162 "$g->feature-available".
1163 %status = $g->btrfs_scrub_status ($path);
1165 Show status of running or finished scrub on a btrfs filesystem.
1166 This function depends on the feature "btrfs". See also
1168 "$g->feature-available".
1169 $g->btrfs_set_seeding ($device, $seeding);
1171 Enable or disable the seeding feature of a device that contains a
1172 btrfs filesystem.
1173 This function depends on the feature "btrfs". See also
1175 "$g->feature-available".
1176 $g->btrfs_subvolume_create ($dest [, qgroupid => $qgroupid]);
1178 Create a btrfs subvolume. The "dest" argument is the destination
1179 directory and the name of the subvolume, in the form
1180 /path/to/dest/name. The optional parameter "qgroupid" represents
1181 the qgroup which the newly created subvolume will be added to.
1182 This function depends on the feature "btrfs". See also
1184 "$g->feature-available".
1185 $g->btrfs_subvolume_create_opts ($dest [, qgroupid => $qgroupid]);
1187 This is an alias of "btrfs_subvolume_create".
1188 $g->btrfs_subvolume_delete ($subvolume);
1190 Delete the named btrfs subvolume or snapshot.
1191 This function depends on the feature "btrfs". See also
1193 "$g->feature-available".
1194 $id = $g->btrfs_subvolume_get_default ($fs);
1196 Get the default subvolume or snapshot of a filesystem mounted at
1197 "mountpoint".
1198 This function depends on the feature "btrfs". See also
1200 "$g->feature-available".
1201 @subvolumes = $g->btrfs_subvolume_list ($fs);
1203 List the btrfs snapshots and subvolumes of the btrfs filesystem
1204 which is mounted at "fs".
1205 This function depends on the feature "btrfs". See also
1207 "$g->feature-available".
1208 $g->btrfs_subvolume_set_default ($id, $fs);
1210 Set the subvolume of the btrfs filesystem "fs" which will be
1211 mounted by default. See "$g->btrfs_subvolume_list" to get a list
1212 of subvolumes.
1213 This function depends on the feature "btrfs". See also
1215 "$g->feature-available".
1216 %btrfssubvolumeinfo = $g->btrfs_subvolume_show ($subvolume);
1218 Return detailed information of the subvolume.
1219 This function depends on the feature "btrfs". See also
1221 "$g->feature-available".
1222 $g->btrfs_subvolume_snapshot ($source, $dest [, ro => $ro] [, qgroupid
1224 => $qgroupid]);
1225 Create a snapshot of the btrfs subvolume "source". The "dest"
1226 argument is the destination directory and the name of the snapshot,
1227 in the form /path/to/dest/name. By default the newly created
1228 snapshot is writable, if the value of optional parameter "ro" is
1229 true, then a readonly snapshot is created. The optional parameter
1230 "qgroupid" represents the qgroup which the newly created snapshot
1231 will be added to.
1232 This function depends on the feature "btrfs". See also
1234 "$g->feature-available".
1235 $g->btrfs_subvolume_snapshot_opts ($source, $dest [, ro => $ro] [,
1237 qgroupid => $qgroupid]);
1238 This is an alias of "btrfs_subvolume_snapshot".
1239 $g->btrfstune_enable_extended_inode_refs ($device);
1241 This will Enable extended inode refs.
1242 This function depends on the feature "btrfs". See also
1244 "$g->feature-available".
1245 $g->btrfstune_enable_skinny_metadata_extent_refs ($device);
1247 This enable skinny metadata extent refs.
1248 This function depends on the feature "btrfs". See also
1250 "$g->feature-available".
1251 $g->btrfstune_seeding ($device, $seeding);
1253 Enable seeding of a btrfs device, this will force a fs readonly so
1254 that you can use it to build other filesystems.
1255 This function depends on the feature "btrfs". See also
1257 "$g->feature-available".
1258 $ptr = $g->c_pointer ();
1260 In non-C language bindings, this allows you to retrieve the
1261 underlying C pointer to the handle (ie. "$g->h *"). The purpose of
1262 this is to allow other libraries to interwork with libguestfs.
1263 $canonical = $g->canonical_device_name ($device);
1265 This utility function is useful when displaying device names to the
1266 user. It takes a number of irregular device names and returns them
1267 in a consistent format:
1268 /dev/hdX
1270 /dev/vdX
1271 These are returned as /dev/sdX. Note this works for device
1272 names and partition names. This is approximately the reverse
1273 of the algorithm described in "BLOCK DEVICE NAMING" in
1274 guestfs(3).
1275 /dev/mapper/VG-LV
1277 /dev/dm-N
1278 Converted to /dev/VG/LV form using "$g->lvm_canonical_lv_name".
1279 Other strings are returned unmodified.
1281 $cap = $g->cap_get_file ($path);
1283 This function returns the Linux capabilities attached to "path".
1284 The capabilities set is returned in text form (see cap_to_text(3)).
1285 If no capabilities are attached to a file, an empty string is
1287 returned.
1288 This function depends on the feature "linuxcaps". See also
1290 "$g->feature-available".
1291 $g->cap_set_file ($path, $cap);
1293 This function sets the Linux capabilities attached to "path". The
1294 capabilities set "cap" should be passed in text form (see
1295 cap_from_text(3)).
1296 This function depends on the feature "linuxcaps". See also
1298 "$g->feature-available".
1299 $rpath = $g->case_sensitive_path ($path);
1301 This can be used to resolve case insensitive paths on a filesystem
1302 which is case sensitive. The use case is to resolve paths which
1303 you have read from Windows configuration files or the Windows
1304 Registry, to the true path.
1305 The command handles a peculiarity of the Linux ntfs-3g filesystem
1307 driver (and probably others), which is that although the underlying
1308 filesystem is case-insensitive, the driver exports the filesystem
1309 to Linux as case-sensitive.
1310 One consequence of this is that special directories such as
1312 C:\windows may appear as /WINDOWS or /windows (or other things)
1313 depending on the precise details of how they were created. In
1314 Windows itself this would not be a problem.
1315 Bug or feature? You decide:
1317 <https://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1>
1318 "$g->case_sensitive_path" attempts to resolve the true case of each
1320 element in the path. It will return a resolved path if either the
1321 full path or its parent directory exists. If the parent directory
1322 exists but the full path does not, the case of the parent directory
1323 will be correctly resolved, and the remainder appended unmodified.
1324 For example, if the file "/Windows/System32/netkvm.sys" exists:
1325 "$g->case_sensitive_path" ("/windows/system32/netkvm.sys")
1327 "Windows/System32/netkvm.sys"
1328 "$g->case_sensitive_path" ("/windows/system32/NoSuchFile")
1330 "Windows/System32/NoSuchFile"
1331 "$g->case_sensitive_path" ("/windows/system33/netkvm.sys")
1333 ERROR
1334 Note: Because of the above behaviour, "$g->case_sensitive_path"
1336 cannot be used to check for the existence of a file.
1337 Note: This function does not handle drive names, backslashes etc.
1339 See also "$g->realpath".
1341 $content = $g->cat ($path);
1343 Return the contents of the file named "path".
1344 Because, in C, this function returns a "char *", there is no way to
1346 differentiate between a "\0" character in a file and end of string.
1347 To handle binary files, use the "$g->read_file" or "$g->download"
1348 functions.
1349 $checksum = $g->checksum ($csumtype, $path);
1351 This call computes the MD5, SHAx or CRC checksum of the file named
1352 "path".
1353 The type of checksum to compute is given by the "csumtype"
1355 parameter which must have one of the following values:
1356 "crc"
1358 Compute the cyclic redundancy check (CRC) specified by POSIX
1359 for the "cksum" command.
1360 "md5"
1362 Compute the MD5 hash (using the md5sum(1) program).
1363 "sha1"
1365 Compute the SHA1 hash (using the sha1sum(1) program).
1366 "sha224"
1368 Compute the SHA224 hash (using the sha224sum(1) program).
1369 "sha256"
1371 Compute the SHA256 hash (using the sha256sum(1) program).
1372 "sha384"
1374 Compute the SHA384 hash (using the sha384sum(1) program).
1375 "sha512"
1377 Compute the SHA512 hash (using the sha512sum(1) program).
1378 The checksum is returned as a printable string.
1380 To get the checksum for a device, use "$g->checksum_device".
1382 To get the checksums for many files, use "$g->checksums_out".
1384 $checksum = $g->checksum_device ($csumtype, $device);
1386 This call computes the MD5, SHAx or CRC checksum of the contents of
1387 the device named "device". For the types of checksums supported
1388 see the "$g->checksum" command.
1389 $g->checksums_out ($csumtype, $directory, $sumsfile);
1391 This command computes the checksums of all regular files in
1392 directory and then emits a list of those checksums to the local
1393 output file "sumsfile".
1394 This can be used for verifying the integrity of a virtual machine.
1396 However to be properly secure you should pay attention to the
1397 output of the checksum command (it uses the ones from GNU
1398 coreutils). In particular when the filename is not printable,
1399 coreutils uses a special backslash syntax. For more information,
1400 see the GNU coreutils info file.
1401 $g->chmod ($mode, $path);
1403 Change the mode (permissions) of "path" to "mode". Only numeric
1404 modes are supported.
1405 Note: When using this command from guestfish, "mode" by default
1407 would be decimal, unless you prefix it with 0 to get octal, ie. use
1408 0700 not 700.
1409 The mode actually set is affected by the umask.
1411 $g->chown ($owner, $group, $path);
1413 Change the file owner to "owner" and group to "group".
1414 Only numeric uid and gid are supported. If you want to use names,
1416 you will need to locate and parse the password file yourself
1417 (Augeas support makes this relatively easy).
1418 $count = $g->clear_backend_setting ($name);
1420 If there is a backend setting string matching "name" or beginning
1421 with "name=", then that string is removed from the backend
1422 settings.
1423 This call returns the number of strings which were removed (which
1425 may be 0, 1 or greater than 1).
1426 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
1428 $output = $g->command (\@arguments);
1430 This call runs a command from the guest filesystem. The filesystem
1431 must be mounted, and must contain a compatible operating system
1432 (ie. something Linux, with the same or compatible processor
1433 architecture).
1434 The single parameter is an argv-style list of arguments. The first
1436 element is the name of the program to run. Subsequent elements are
1437 parameters. The list must be non-empty (ie. must contain a program
1438 name). Note that the command runs directly, and is not invoked via
1439 the shell (see "$g->sh").
1440 The return value is anything printed to stdout by the command.
1442 If the command returns a non-zero exit status, then this function
1444 returns an error message. The error message string is the content
1445 of stderr from the command.
1446 The $PATH environment variable will contain at least /usr/bin and
1448 /bin. If you require a program from another location, you should
1449 provide the full path in the first parameter.
1450 Shared libraries and data files required by the program must be
1452 available on filesystems which are mounted in the correct places.
1453 It is the callerXs responsibility to ensure all filesystems that
1454 are needed are mounted at the right locations.
1455 Because of the message protocol, there is a transfer limit of
1457 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1458 guestfs(3).
1459 @lines = $g->command_lines (\@arguments);
1461 This is the same as "$g->command", but splits the result into a
1462 list of lines.
1463 See also: "$g->sh_lines"
1465 Because of the message protocol, there is a transfer limit of
1467 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1468 guestfs(3).
1469 $g->compress_device_out ($ctype, $device, $zdevice [, level =>
1471 $level]);
1472 This command compresses "device" and writes it out to the local
1473 file "zdevice".
1474 The "ctype" and optional "level" parameters have the same meaning
1476 as in "$g->compress_out".
1477 $g->compress_out ($ctype, $file, $zfile [, level => $level]);
1479 This command compresses file and writes it out to the local file
1480 zfile.
1481 The compression program used is controlled by the "ctype"
1483 parameter. Currently this includes: "compress", "gzip", "bzip2",
1484 "xz" or "lzop". Some compression types may not be supported by
1485 particular builds of libguestfs, in which case you will get an
1486 error containing the substring "not supported".
1487 The optional "level" parameter controls compression level. The
1489 meaning and default for this parameter depends on the compression
1490 program being used.
1491 $g->config ($hvparam, $hvvalue);
1493 This can be used to add arbitrary hypervisor parameters of the form
1494 -param value. Actually itXs not quite arbitrary - we prevent you
1495 from setting some parameters which would interfere with parameters
1496 that we use.
1497 The first character of "hvparam" string must be a "-" (dash).
1499 "hvvalue" can be NULL.
1501 $g->copy_attributes ($src, $dest [, all => $all] [, mode => $mode] [,
1503 xattributes => $xattributes] [, ownership => $ownership]);
1504 Copy the attributes of a path (which can be a file or a directory)
1505 to another path.
1506 By default no attribute is copied, so make sure to specify any (or
1508 "all" to copy everything).
1509 The optional arguments specify which attributes can be copied:
1511 "mode"
1513 Copy part of the file mode from "source" to "destination". Only
1514 the UNIX permissions and the sticky/setuid/setgid bits can be
1515 copied.
1516 "xattributes"
1518 Copy the Linux extended attributes (xattrs) from "source" to
1519 "destination". This flag does nothing if the linuxxattrs
1520 feature is not available (see "$g->feature_available").
1521 "ownership"
1523 Copy the owner uid and the group gid of "source" to
1524 "destination".
1525 "all"
1527 Copy all the attributes from "source" to "destination".
1528 Enabling it enables all the other flags, if they are not
1529 specified already.
1530 $g->copy_device_to_device ($src, $dest [, srcoffset => $srcoffset] [,
1532 destoffset => $destoffset] [, size => $size] [, sparse => $sparse] [,
1533 append => $append]);
1534 The four calls "$g->copy_device_to_device",
1535 "$g->copy_device_to_file", "$g->copy_file_to_device", and
1536 "$g->copy_file_to_file" let you copy from a source (device|file) to
1537 a destination (device|file).
1538 Partial copies can be made since you can specify optionally the
1540 source offset, destination offset and size to copy. These values
1541 are all specified in bytes. If not given, the offsets both default
1542 to zero, and the size defaults to copying as much as possible until
1543 we hit the end of the source.
1544 The source and destination may be the same object. However
1546 overlapping regions may not be copied correctly.
1547 If the destination is a file, it is created if required. If the
1549 destination file is not large enough, it is extended.
1550 If the destination is a file and the "append" flag is not set, then
1552 the destination file is truncated. If the "append" flag is set,
1553 then the copy appends to the destination file. The "append" flag
1554 currently cannot be set for devices.
1555 If the "sparse" flag is true then the call avoids writing blocks
1557 that contain only zeroes, which can help in some situations where
1558 the backing disk is thin-provisioned. Note that unless the target
1559 is already zeroed, using this option will result in incorrect
1560 copying.
1561 $g->copy_device_to_file ($src, $dest [, srcoffset => $srcoffset] [,
1563 destoffset => $destoffset] [, size => $size] [, sparse => $sparse] [,
1564 append => $append]);
1565 See "$g->copy_device_to_device" for a general overview of this
1566 call.
1567 $g->copy_file_to_device ($src, $dest [, srcoffset => $srcoffset] [,
1569 destoffset => $destoffset] [, size => $size] [, sparse => $sparse] [,
1570 append => $append]);
1571 See "$g->copy_device_to_device" for a general overview of this
1572 call.
1573 $g->copy_file_to_file ($src, $dest [, srcoffset => $srcoffset] [,
1575 destoffset => $destoffset] [, size => $size] [, sparse => $sparse] [,
1576 append => $append]);
1577 See "$g->copy_device_to_device" for a general overview of this
1578 call.
1579 This is not the function you want for copying files. This is for
1581 copying blocks within existing files. See "$g->cp", "$g->cp_a" and
1582 "$g->mv" for general file copying and moving functions.
1583 $g->copy_in ($localpath, $remotedir);
1585 "$g->copy_in" copies local files or directories recursively into
1586 the disk image, placing them in the directory called "remotedir"
1587 (which must exist).
1588 Wildcards cannot be used.
1590 $g->copy_out ($remotepath, $localdir);
1592 "$g->copy_out" copies remote files or directories recursively out
1593 of the disk image, placing them on the host disk in a local
1594 directory called "localdir" (which must exist).
1595 To download to the current directory, use "." as in:
1597 C<$g-E<gt>copy_out> /home .
1599 Wildcards cannot be used.
1601 $g->copy_size ($src, $dest, $size);
1603 This command copies exactly "size" bytes from one source device or
1604 file "src" to another destination device or file "dest".
1605 Note this will fail if the source is too short or if the
1607 destination is not large enough.
1608 This function is deprecated. In new code, use the
1610 "copy_device_to_device" call instead.
1611 Deprecated functions will not be removed from the API, but the fact
1613 that they are deprecated indicates that there are problems with
1614 correct use of these functions.
1615 $g->cp ($src, $dest);
1617 This copies a file from "src" to "dest" where "dest" is either a
1618 destination filename or destination directory.
1619 $g->cp_a ($src, $dest);
1621 This copies a file or directory from "src" to "dest" recursively
1622 using the "cp -a" command.
1623 $g->cp_r ($src, $dest);
1625 This copies a file or directory from "src" to "dest" recursively
1626 using the "cp -rP" command.
1627 Most users should use "$g->cp_a" instead. This command is useful
1629 when you don't want to preserve permissions, because the target
1630 filesystem does not support it (primarily when writing to DOS FAT
1631 filesystems).
1632 $g->cpio_out ($directory, $cpiofile [, format => $format]);
1634 This command packs the contents of directory and downloads it to
1635 local file "cpiofile".
1636 The optional "format" parameter can be used to select the format.
1638 Only the following formats are currently permitted:
1639 "newc"
1641 New (SVR4) portable format. This format happens to be
1642 compatible with the cpio-like format used by the Linux kernel
1643 for initramfs.
1644 This is the default format.
1646 "crc"
1648 New (SVR4) portable format with a checksum.
1649 $g->cryptsetup_close ($device);
1651 This closes an encrypted device that was created earlier by
1652 "$g->cryptsetup_open". The "device" parameter must be the name of
1653 the mapping device (ie. /dev/mapper/mapname) and not the name of
1654 the underlying block device.
1655 This function depends on the feature "luks". See also
1657 "$g->feature-available".
1658 $g->cryptsetup_open ($device, $key, $mapname [, readonly => $readonly]
1660 [, crypttype => $crypttype]);
1661 This command opens a block device which has been encrypted
1662 according to the Linux Unified Key Setup (LUKS) standard, Windows
1663 BitLocker, or some other types.
1664 "device" is the encrypted block device or partition.
1666 The caller must supply one of the keys associated with the
1668 encrypted block device, in the "key" parameter.
1669 This creates a new block device called /dev/mapper/mapname. Reads
1671 and writes to this block device are decrypted from and encrypted to
1672 the underlying "device" respectively.
1673 "mapname" cannot be "control" because that name is reserved by
1675 device-mapper.
1676 If the optional "crypttype" parameter is not present then
1678 libguestfs tries to guess the correct type (for example LUKS or
1679 BitLocker). However you can override this by specifying one of the
1680 following types:
1681 "luks"
1683 A Linux LUKS device.
1684 "bitlk"
1686 A Windows BitLocker device.
1687 The optional "readonly" flag, if set to true, creates a read-only
1689 mapping.
1690 If this block device contains LVM volume groups, then calling
1692 "$g->lvm_scan" with the "activate" parameter "true" will make them
1693 visible.
1694 Use "$g->list_dm_devices" to list all device mapper devices.
1696 This function depends on the feature "luks". See also
1698 "$g->feature-available".
1699 $g->dd ($src, $dest);
1701 This command copies from one source device or file "src" to another
1702 destination device or file "dest". Normally you would use this to
1703 copy to or from a device or partition, for example to duplicate a
1704 filesystem.
1705 If the destination is a device, it must be as large or larger than
1707 the source file or device, otherwise the copy will fail. This
1708 command cannot do partial copies (see "$g->copy_device_to_device").
1709 This function is deprecated. In new code, use the
1711 "copy_device_to_device" call instead.
1712 Deprecated functions will not be removed from the API, but the fact
1714 that they are deprecated indicates that there are problems with
1715 correct use of these functions.
1716 $index = $g->device_index ($device);
1718 This function takes a device name (eg. "/dev/sdb") and returns the
1719 index of the device in the list of devices.
1720 Index numbers start from 0. The named device must exist, for
1722 example as a string returned from "$g->list_devices".
1723 See also "$g->list_devices", "$g->part_to_dev".
1725 $output = $g->df ();
1727 This command runs the df(1) command to report disk space used.
1728 This command is mostly useful for interactive sessions. It is not
1730 intended that you try to parse the output string. Use
1731 "$g->statvfs" from programs.
1732 $output = $g->df_h ();
1734 This command runs the "df -h" command to report disk space used in
1735 human-readable format.
1736 This command is mostly useful for interactive sessions. It is not
1738 intended that you try to parse the output string. Use
1739 "$g->statvfs" from programs.
1740 $g->disk_create ($filename, $format, $size [, backingfile =>
1742 $backingfile] [, backingformat => $backingformat] [, preallocation =>
1743 $preallocation] [, compat => $compat] [, clustersize => $clustersize]);
1744 Create a blank disk image called filename (a host file) with format
1745 "format" (usually "raw" or "qcow2"). The size is "size" bytes.
1746 If used with the optional "backingfile" parameter, then a snapshot
1748 is created on top of the backing file. In this case, "size" must
1749 be passed as "-1". The size of the snapshot is the same as the
1750 size of the backing file, which is discovered automatically. You
1751 are encouraged to also pass "backingformat" to describe the format
1752 of "backingfile".
1753 If filename refers to a block device, then the device is formatted.
1755 The "size" is ignored since block devices have an intrinsic size.
1756 The other optional parameters are:
1758 "preallocation"
1760 If format is "raw", then this can be either "off" (or "sparse")
1761 or "full" to create a sparse or fully allocated file
1762 respectively. The default is "off".
1763 If format is "qcow2", then this can be "off" (or "sparse"),
1765 "metadata" or "full". Preallocating metadata can be faster
1766 when doing lots of writes, but uses more space. The default is
1767 "off".
1768 "compat"
1770 "qcow2" only: Pass the string 1.1 to use the advanced qcow2
1771 format supported by qemu X 1.1.
1772 "clustersize"
1774 "qcow2" only: Change the qcow2 cluster size. The default is
1775 65536 (bytes) and this setting may be any power of two between
1776 512 and 2097152.
1777 Note that this call does not add the new disk to the handle. You
1779 may need to call "$g->add_drive_opts" separately.
1780 $format = $g->disk_format ($filename);
1782 Detect and return the format of the disk image called filename.
1783 filename can also be a host device, etc. If the format of the
1784 image could not be detected, then "unknown" is returned.
1785 Note that detecting the disk format can be insecure under some
1787 circumstances. See "CVE-2010-3851" in guestfs(3).
1788 See also: "DISK IMAGE FORMATS" in guestfs(3)
1790 $backingfile = $g->disk_has_backing_file ($filename);
1792 Detect and return whether the disk image filename has a backing
1793 file.
1794 Note that detecting disk features can be insecure under some
1796 circumstances. See "CVE-2010-3851" in guestfs(3).
1797 $size = $g->disk_virtual_size ($filename);
1799 Detect and return the virtual size in bytes of the disk image
1800 called filename.
1801 Note that detecting disk features can be insecure under some
1803 circumstances. See "CVE-2010-3851" in guestfs(3).
1804 $kmsgs = $g->dmesg ();
1806 This returns the kernel messages (dmesg(1) output) from the guest
1807 kernel. This is sometimes useful for extended debugging of
1808 problems.
1809 Another way to get the same information is to enable verbose
1811 messages with "$g->set_verbose" or by setting the environment
1812 variable "LIBGUESTFS_DEBUG=1" before running the program.
1813 $g->download ($remotefilename, $filename);
1815 Download file remotefilename and save it as filename on the local
1816 machine.
1817 filename can also be a named pipe.
1819 See also "$g->upload", "$g->cat".
1821 $g->download_blocks ($device, $start, $stop, $filename [, unallocated
1823 => $unallocated]);
1824 Download the data units from start address to stop from the disk
1825 partition (eg. /dev/sda1) and save them as filename on the local
1826 machine.
1827 The use of this API on sparse disk image formats such as QCOW, may
1829 result in large zero-filled files downloaded on the host.
1830 The size of a data unit varies across filesystem implementations.
1832 On NTFS filesystems data units are referred as clusters while on
1833 ExtX ones they are referred as fragments.
1834 If the optional "unallocated" flag is true (default is false), only
1836 the unallocated blocks will be extracted. This is useful to detect
1837 hidden data or to retrieve deleted files which data units have not
1838 been overwritten yet.
1839 This function depends on the feature "sleuthkit". See also
1841 "$g->feature-available".
1842 $g->download_inode ($device, $inode, $filename);
1844 Download a file given its inode from the disk partition (eg.
1845 /dev/sda1) and save it as filename on the local machine.
1846 It is not required to mount the disk to run this command.
1848 The command is capable of downloading deleted or inaccessible
1850 files.
1851 This function depends on the feature "sleuthkit". See also
1853 "$g->feature-available".
1854 $g->download_offset ($remotefilename, $filename, $offset, $size);
1856 Download file remotefilename and save it as filename on the local
1857 machine.
1858 remotefilename is read for "size" bytes starting at "offset" (this
1860 region must be within the file or device).
1861 Note that there is no limit on the amount of data that can be
1863 downloaded with this call, unlike with "$g->pread", and this call
1864 always reads the full amount unless an error occurs.
1865 See also "$g->download", "$g->pread".
1867 $g->drop_caches ($whattodrop);
1869 This instructs the guest kernel to drop its page cache, and/or
1870 dentries and inode caches. The parameter "whattodrop" tells the
1871 kernel what precisely to drop, see
1872 <https://linux-mm.org/Drop_Caches>
1873 Setting "whattodrop" to 3 should drop everything.
1875 This automatically calls sync(2) before the operation, so that the
1877 maximum guest memory is freed.
1878 $sizekb = $g->du ($path);
1880 This command runs the "du -s" command to estimate file space usage
1881 for "path".
1882 "path" can be a file or a directory. If "path" is a directory then
1884 the estimate includes the contents of the directory and all
1885 subdirectories (recursively).
1886 The result is the estimated size in kilobytes (ie. units of 1024
1888 bytes).
1889 $g->e2fsck ($device [, correct => $correct] [, forceall => $forceall]);
1891 This runs the ext2/ext3 filesystem checker on "device". It can
1892 take the following optional arguments:
1893 "correct"
1895 Automatically repair the file system. This option will cause
1896 e2fsck to automatically fix any filesystem problems that can be
1897 safely fixed without human intervention.
1898 This option may not be specified at the same time as the
1900 "forceall" option.
1901 "forceall"
1903 Assume an answer of XyesX to all questions; allows e2fsck to be
1904 used non-interactively.
1905 This option may not be specified at the same time as the
1907 "correct" option.
1908 $g->e2fsck_f ($device);
1910 This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
1911 checker on "device", noninteractively (-p), even if the filesystem
1912 appears to be clean (-f).
1913 This function is deprecated. In new code, use the "e2fsck" call
1915 instead.
1916 Deprecated functions will not be removed from the API, but the fact
1918 that they are deprecated indicates that there are problems with
1919 correct use of these functions.
1920 $output = $g->echo_daemon (\@words);
1922 This command concatenates the list of "words" passed with single
1923 spaces between them and returns the resulting string.
1924 You can use this command to test the connection through to the
1926 daemon.
1927 See also "$g->ping_daemon".
1929 @lines = $g->egrep ($regex, $path);
1931 This calls the external egrep(1) program and returns the matching
1932 lines.
1933 Because of the message protocol, there is a transfer limit of
1935 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1936 guestfs(3).
1937 This function is deprecated. In new code, use the "grep" call
1939 instead.
1940 Deprecated functions will not be removed from the API, but the fact
1942 that they are deprecated indicates that there are problems with
1943 correct use of these functions.
1944 @lines = $g->egrepi ($regex, $path);
1946 This calls the external "egrep -i" program and returns the matching
1947 lines.
1948 Because of the message protocol, there is a transfer limit of
1950 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1951 guestfs(3).
1952 This function is deprecated. In new code, use the "grep" call
1954 instead.
1955 Deprecated functions will not be removed from the API, but the fact
1957 that they are deprecated indicates that there are problems with
1958 correct use of these functions.
1959 $equality = $g->equal ($file1, $file2);
1961 This compares the two files file1 and file2 and returns true if
1962 their content is exactly equal, or false otherwise.
1963 The external cmp(1) program is used for the comparison.
1965 $existsflag = $g->exists ($path);
1967 This returns "true" if and only if there is a file, directory (or
1968 anything) with the given "path" name.
1969 See also "$g->is_file", "$g->is_dir", "$g->stat".
1971 $g->extlinux ($directory);
1973 Install the SYSLINUX bootloader on the device mounted at directory.
1974 Unlike "$g->syslinux" which requires a FAT filesystem, this can be
1975 used on an ext2/3/4 or btrfs filesystem.
1976 The directory parameter can be either a mountpoint, or a directory
1978 within the mountpoint.
1979 You also have to mark the partition as "active"
1981 ("$g->part_set_bootable") and a Master Boot Record must be
1982 installed (eg. using "$g->pwrite_device") on the first sector of
1983 the whole disk. The SYSLINUX package comes with some suitable
1984 Master Boot Records. See the extlinux(1) man page for further
1985 information.
1986 Additional configuration can be supplied to SYSLINUX by placing a
1988 file called extlinux.conf on the filesystem under directory. For
1989 further information about the contents of this file, see
1990 extlinux(1).
1991 See also "$g->syslinux".
1993 This function depends on the feature "extlinux". See also
1995 "$g->feature-available".
1996 $g->f2fs_expand ($device);
1998 This expands a f2fs filesystem to match the size of the underlying
1999 device.
2000 This function depends on the feature "f2fs". See also
2002 "$g->feature-available".
2003 $g->fallocate ($path, $len);
2005 This command preallocates a file (containing zero bytes) named
2006 "path" of size "len" bytes. If the file exists already, it is
2007 overwritten.
2008 Do not confuse this with the guestfish-specific "alloc" command
2010 which allocates a file in the host and attaches it as a device.
2011 This function is deprecated. In new code, use the "fallocate64"
2013 call instead.
2014 Deprecated functions will not be removed from the API, but the fact
2016 that they are deprecated indicates that there are problems with
2017 correct use of these functions.
2018 $g->fallocate64 ($path, $len);
2020 This command preallocates a file (containing zero bytes) named
2021 "path" of size "len" bytes. If the file exists already, it is
2022 overwritten.
2023 Note that this call allocates disk blocks for the file. To create
2025 a sparse file use "$g->truncate_size" instead.
2026 The deprecated call "$g->fallocate" does the same, but owing to an
2028 oversight it only allowed 30 bit lengths to be specified,
2029 effectively limiting the maximum size of files created through that
2030 call to 1GB.
2031 Do not confuse this with the guestfish-specific "alloc" and
2033 "sparse" commands which create a file in the host and attach it as
2034 a device.
2035 $isavailable = $g->feature_available (\@groups);
2037 This is the same as "$g->available", but unlike that call it
2038 returns a simple true/false boolean result, instead of throwing an
2039 exception if a feature is not found. For other documentation see
2040 "$g->available".
2041 @lines = $g->fgrep ($pattern, $path);
2043 This calls the external fgrep(1) program and returns the matching
2044 lines.
2045 Because of the message protocol, there is a transfer limit of
2047 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2048 guestfs(3).
2049 This function is deprecated. In new code, use the "grep" call
2051 instead.
2052 Deprecated functions will not be removed from the API, but the fact
2054 that they are deprecated indicates that there are problems with
2055 correct use of these functions.
2056 @lines = $g->fgrepi ($pattern, $path);
2058 This calls the external "fgrep -i" program and returns the matching
2059 lines.
2060 Because of the message protocol, there is a transfer limit of
2062 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2063 guestfs(3).
2064 This function is deprecated. In new code, use the "grep" call
2066 instead.
2067 Deprecated functions will not be removed from the API, but the fact
2069 that they are deprecated indicates that there are problems with
2070 correct use of these functions.
2071 $description = $g->file ($path);
2073 This call uses the standard file(1) command to determine the type
2074 or contents of the file.
2075 This call will also transparently look inside various types of
2077 compressed file.
2078 The exact command which runs is "file -zb path". Note in
2080 particular that the filename is not prepended to the output (the -b
2081 option).
2082 The output depends on the output of the underlying file(1) command
2084 and it can change in future in ways beyond our control. In other
2085 words, the output is not guaranteed by the ABI.
2086 See also: file(1), "$g->vfs_type", "$g->lstat", "$g->is_file",
2088 "$g->is_blockdev" (etc), "$g->is_zero".
2089 $arch = $g->file_architecture ($filename);
2091 This detects the architecture of the binary filename, and returns
2092 it if known.
2093 Currently defined architectures are:
2095 "aarch64"
2097 64 bit ARM.
2098 "arm"
2100 32 bit ARM.
2101 "i386"
2103 This string is returned for all 32 bit i386, i486, i586, i686
2104 binaries irrespective of the precise processor requirements of
2105 the binary.
2106 "ia64"
2108 Intel Itanium.
2109 "ppc"
2111 32 bit Power PC.
2112 "ppc64"
2114 64 bit Power PC (big endian).
2115 "ppc64le"
2117 64 bit Power PC (little endian).
2118 "riscv32"
2120 "riscv64"
2121 "riscv128"
2122 RISC-V 32-, 64- or 128-bit variants.
2123 "s390"
2125 31 bit IBM S/390.
2126 "s390x"
2128 64 bit IBM S/390.
2129 "sparc"
2131 32 bit SPARC.
2132 "sparc64"
2134 64 bit SPARC V9 and above.
2135 "x86_64"
2137 64 bit x86-64.
2138 Libguestfs may return other architecture strings in future.
2140 The function works on at least the following types of files:
2142 • many types of Un*x and Linux binary
2144 • many types of Un*x and Linux shared library
2146 • Windows Win32 and Win64 binaries
2148 • Windows Win32 and Win64 DLLs
2150 Win32 binaries and DLLs return "i386".
2152 Win64 binaries and DLLs return "x86_64".
2154 • Linux kernel modules
2156 • Linux new-style initrd images
2158 • some non-x86 Linux vmlinuz kernels
2160 What it can't do currently:
2162 • static libraries (libfoo.a)
2164 • Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
2166 • x86 Linux vmlinuz kernels
2168 x86 vmlinuz images (bzImage format) consist of a mix of 16-,
2170 32- and compressed code, and are horribly hard to unpack. If
2171 you want to find the architecture of a kernel, use the
2172 architecture of the associated initrd or kernel module(s)
2173 instead.
2174 $size = $g->filesize ($file);
2176 This command returns the size of file in bytes.
2177 To get other stats about a file, use "$g->stat", "$g->lstat",
2179 "$g->is_dir", "$g->is_file" etc. To get the size of block devices,
2180 use "$g->blockdev_getsize64".
2181 $fsavail = $g->filesystem_available ($filesystem);
2183 Check whether libguestfs supports the named filesystem. The
2184 argument "filesystem" is a filesystem name, such as "ext3".
2185 You must call "$g->launch" before using this command.
2187 This is mainly useful as a negative test. If this returns true, it
2189 doesn't mean that a particular filesystem can be created or
2190 mounted, since filesystems can fail for other reasons such as it
2191 being a later version of the filesystem, or having incompatible
2192 features, or lacking the right mkfs.<fs> tool.
2193 See also "$g->available", "$g->feature_available", "AVAILABILITY"
2195 in guestfs(3).
2196 @dirents = $g->filesystem_walk ($device);
2198 Walk through the internal structures of a disk partition (eg.
2199 /dev/sda1) in order to return a list of all the files and
2200 directories stored within.
2201 It is not necessary to mount the disk partition to run this
2203 command.
2204 All entries in the filesystem are returned. This function can list
2206 deleted or unaccessible files. The entries are not sorted.
2207 The "tsk_dirent" structure contains the following fields.
2209 "tsk_inode"
2211 Filesystem reference number of the node. It might be 0 if the
2212 node has been deleted.
2213 "tsk_type"
2215 Basic file type information. See below for a detailed list of
2216 values.
2217 "tsk_size"
2219 File size in bytes. It might be "-1" if the node has been
2220 deleted.
2221 "tsk_name"
2223 The file path relative to its directory.
2224 "tsk_flags"
2226 Bitfield containing extra information regarding the entry. It
2227 contains the logical OR of the following values:
2228 0x0001
2230 If set to 1, the file is allocated and visible within the
2231 filesystem. Otherwise, the file has been deleted. Under
2232 certain circumstances, the function "download_inode" can be
2233 used to recover deleted files.
2234 0x0002
2236 Filesystem such as NTFS and Ext2 or greater, separate the
2237 file name from the metadata structure. The bit is set to 1
2238 when the file name is in an unallocated state and the
2239 metadata structure is in an allocated one. This generally
2240 implies the metadata has been reallocated to a new file.
2241 Therefore, information such as file type, file size,
2242 timestamps, number of links and symlink target might not
2243 correspond with the ones of the original deleted entry.
2244 0x0004
2246 The bit is set to 1 when the file is compressed using
2247 filesystem native compression support (NTFS). The API is
2248 not able to detect application level compression.
2249 "tsk_atime_sec"
2251 "tsk_atime_nsec"
2252 "tsk_mtime_sec"
2253 "tsk_mtime_nsec"
2254 "tsk_ctime_sec"
2255 "tsk_ctime_nsec"
2256 "tsk_crtime_sec"
2257 "tsk_crtime_nsec"
2258 Respectively, access, modification, last status change and
2259 creation time in Unix format in seconds and nanoseconds.
2260 "tsk_nlink"
2262 Number of file names pointing to this entry.
2263 "tsk_link"
2265 If the entry is a symbolic link, this field will contain the
2266 path to the target file.
2267 The "tsk_type" field will contain one of the following characters:
2269 'b' Block special
2271 'c' Char special
2273 'd' Directory
2275 'f' FIFO (named pipe)
2277 'l' Symbolic link
2279 'r' Regular file
2281 's' Socket
2283 'h' Shadow inode (Solaris)
2285 'w' Whiteout inode (BSD)
2287 'u' Unknown file type
2289 This function depends on the feature "libtsk". See also
2291 "$g->feature-available".
2292 $g->fill ($c, $len, $path);
2294 This command creates a new file called "path". The initial content
2295 of the file is "len" octets of "c", where "c" must be a number in
2296 the range "[0..255]".
2297 To fill a file with zero bytes (sparsely), it is much more
2299 efficient to use "$g->truncate_size". To create a file with a
2300 pattern of repeating bytes use "$g->fill_pattern".
2301 $g->fill_dir ($dir, $nr);
2303 This function, useful for testing filesystems, creates "nr" empty
2304 files in the directory "dir" with names 00000000 through "nr-1"
2305 (ie. each file name is 8 digits long padded with zeroes).
2306 $g->fill_pattern ($pattern, $len, $path);
2308 This function is like "$g->fill" except that it creates a new file
2309 of length "len" containing the repeating pattern of bytes in
2310 "pattern". The pattern is truncated if necessary to ensure the
2311 length of the file is exactly "len" bytes.
2312 @names = $g->find ($directory);
2314 This command lists out all files and directories, recursively,
2315 starting at directory. It is essentially equivalent to running the
2316 shell command "find directory -print" but some post-processing
2317 happens on the output, described below.
2318 This returns a list of strings without any prefix. Thus if the
2320 directory structure was:
2321 /tmp/a
2323 /tmp/b
2324 /tmp/c/d
2325 then the returned list from "$g->find" /tmp would be 4 elements:
2327 a
2329 b
2330 c
2331 c/d
2332 If directory is not a directory, then this command returns an
2334 error.
2335 The returned list is sorted.
2337 $g->find0 ($directory, $files);
2339 This command lists out all files and directories, recursively,
2340 starting at directory, placing the resulting list in the external
2341 file called files.
2342 This command works the same way as "$g->find" with the following
2344 exceptions:
2345 • The resulting list is written to an external file.
2347 • Items (filenames) in the result are separated by "\0"
2349 characters. See find(1) option -print0.
2350 • The result list is not sorted.
2352 @dirents = $g->find_inode ($device, $inode);
2354 Searches all the entries associated with the given inode.
2355 For each entry, a "tsk_dirent" structure is returned. See
2357 "filesystem_walk" for more information about "tsk_dirent"
2358 structures.
2359 This function depends on the feature "libtsk". See also
2361 "$g->feature-available".
2362 $device = $g->findfs_label ($label);
2364 This command searches the filesystems and returns the one which has
2365 the given label. An error is returned if no such filesystem can be
2366 found.
2367 To find the label of a filesystem, use "$g->vfs_label".
2369 $device = $g->findfs_uuid ($uuid);
2371 This command searches the filesystems and returns the one which has
2372 the given UUID. An error is returned if no such filesystem can be
2373 found.
2374 To find the UUID of a filesystem, use "$g->vfs_uuid".
2376 $status = $g->fsck ($fstype, $device);
2378 This runs the filesystem checker (fsck) on "device" which should
2379 have filesystem type "fstype".
2380 The returned integer is the status. See fsck(8) for the list of
2382 status codes from "fsck".
2383 Notes:
2385 • Multiple status codes can be summed together.
2387 • A non-zero return code can mean "success", for example if
2389 errors have been corrected on the filesystem.
2390 • Checking or repairing NTFS volumes is not supported (by linux-
2392 ntfs).
2393 This command is entirely equivalent to running "fsck -a -t fstype
2395 device".
2396 $g->fstrim ($mountpoint [, offset => $offset] [, length => $length] [,
2398 minimumfreeextent => $minimumfreeextent]);
2399 Trim the free space in the filesystem mounted on "mountpoint". The
2400 filesystem must be mounted read-write.
2401 The filesystem contents are not affected, but any free space in the
2403 filesystem is "trimmed", that is, given back to the host device,
2404 thus making disk images more sparse, allowing unused space in qcow2
2405 files to be reused, etc.
2406 This operation requires support in libguestfs, the mounted
2408 filesystem, the host filesystem, qemu and the host kernel. If this
2409 support isn't present it may give an error or even appear to run
2410 but do nothing.
2411 In the case where the kernel vfs driver does not support trimming,
2413 this call will fail with errno set to "ENOTSUP". Currently this
2414 happens when trying to trim FAT filesystems.
2415 See also "$g->zero_free_space". That is a slightly different
2417 operation that turns free space in the filesystem into zeroes. It
2418 is valid to call "$g->fstrim" either instead of, or after calling
2419 "$g->zero_free_space".
2420 This function depends on the feature "fstrim". See also
2422 "$g->feature-available".
2423 $append = $g->get_append ();
2425 Return the additional kernel options which are added to the
2426 libguestfs appliance kernel command line.
2427 If "NULL" then no options are added.
2429 $backend = $g->get_attach_method ();
2431 Return the current backend.
2432 See "$g->set_backend" and "BACKEND" in guestfs(3).
2434 This function is deprecated. In new code, use the "get_backend"
2436 call instead.
2437 Deprecated functions will not be removed from the API, but the fact
2439 that they are deprecated indicates that there are problems with
2440 correct use of these functions.
2441 $autosync = $g->get_autosync ();
2443 Get the autosync flag.
2444 $backend = $g->get_backend ();
2446 Return the current backend.
2447 This handle property was previously called the "attach method".
2449 See "$g->set_backend" and "BACKEND" in guestfs(3).
2451 $val = $g->get_backend_setting ($name);
2453 Find a backend setting string which is either "name" or begins with
2454 "name=". If "name", this returns the string "1". If "name=", this
2455 returns the part after the equals sign (which may be an empty
2456 string).
2457 If no such setting is found, this function throws an error. The
2459 errno (see "$g->last_errno") will be "ESRCH" in this case.
2460 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
2462 @settings = $g->get_backend_settings ();
2464 Return the current backend settings.
2465 This call returns all backend settings strings. If you want to
2467 find a single backend setting, see "$g->get_backend_setting".
2468 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
2470 $cachedir = $g->get_cachedir ();
2472 Get the directory used by the handle to store the appliance cache.
2473 $direct = $g->get_direct ();
2475 Return the direct appliance mode flag.
2476 This function is deprecated. In new code, use the
2478 "internal_get_console_socket" call instead.
2479 Deprecated functions will not be removed from the API, but the fact
2481 that they are deprecated indicates that there are problems with
2482 correct use of these functions.
2483 $attrs = $g->get_e2attrs ($file);
2485 This returns the file attributes associated with file.
2486 The attributes are a set of bits associated with each inode which
2488 affect the behaviour of the file. The attributes are returned as a
2489 string of letters (described below). The string may be empty,
2490 indicating that no file attributes are set for this file.
2491 These attributes are only present when the file is located on an
2493 ext2/3/4 filesystem. Using this call on other filesystem types
2494 will result in an error.
2495 The characters (file attributes) in the returned string are
2497 currently:
2498 'A' When the file is accessed, its atime is not modified.
2500 'a' The file is append-only.
2502 'c' The file is compressed on-disk.
2504 'D' (Directories only.) Changes to this directory are written
2506 synchronously to disk.
2507 'd' The file is not a candidate for backup (see dump(8)).
2509 'E' The file has compression errors.
2511 'e' The file is using extents.
2513 'h' The file is storing its blocks in units of the filesystem
2515 blocksize instead of sectors.
2516 'I' (Directories only.) The directory is using hashed trees.
2518 'i' The file is immutable. It cannot be modified, deleted or
2520 renamed. No link can be created to this file.
2521 'j' The file is data-journaled.
2523 's' When the file is deleted, all its blocks will be zeroed.
2525 'S' Changes to this file are written synchronously to disk.
2527 'T' (Directories only.) This is a hint to the block allocator that
2529 subdirectories contained in this directory should be spread
2530 across blocks. If not present, the block allocator will try to
2531 group subdirectories together.
2532 't' For a file, this disables tail-merging. (Not used by upstream
2534 implementations of ext2.)
2535 'u' When the file is deleted, its blocks will be saved, allowing
2537 the file to be undeleted.
2538 'X' The raw contents of the compressed file may be accessed.
2540 'Z' The compressed file is dirty.
2542 More file attributes may be added to this list later. Not all file
2544 attributes may be set for all kinds of files. For detailed
2545 information, consult the chattr(1) man page.
2546 See also "$g->set_e2attrs".
2548 Don't confuse these attributes with extended attributes (see
2550 "$g->getxattr").
2551 $generation = $g->get_e2generation ($file);
2553 This returns the ext2 file generation of a file. The generation
2554 (which used to be called the "version") is a number associated with
2555 an inode. This is most commonly used by NFS servers.
2556 The generation is only present when the file is located on an
2558 ext2/3/4 filesystem. Using this call on other filesystem types
2559 will result in an error.
2560 See "$g->set_e2generation".
2562 $label = $g->get_e2label ($device);
2564 This returns the ext2/3/4 filesystem label of the filesystem on
2565 "device".
2566 This function is deprecated. In new code, use the "vfs_label" call
2568 instead.
2569 Deprecated functions will not be removed from the API, but the fact
2571 that they are deprecated indicates that there are problems with
2572 correct use of these functions.
2573 $uuid = $g->get_e2uuid ($device);
2575 This returns the ext2/3/4 filesystem UUID of the filesystem on
2576 "device".
2577 This function is deprecated. In new code, use the "vfs_uuid" call
2579 instead.
2580 Deprecated functions will not be removed from the API, but the fact
2582 that they are deprecated indicates that there are problems with
2583 correct use of these functions.
2584 $hv = $g->get_hv ();
2586 Return the current hypervisor binary.
2587 This is always non-NULL. If it wasn't set already, then this will
2589 return the default qemu binary name.
2590 $identifier = $g->get_identifier ();
2592 Get the handle identifier. See "$g->set_identifier".
2593 $challenge = $g->get_libvirt_requested_credential_challenge ($index);
2595 Get the challenge (provided by libvirt) for the "index"'th
2596 requested credential. If libvirt did not provide a challenge, this
2597 returns the empty string "".
2598 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2600 example code.
2601 $defresult = $g->get_libvirt_requested_credential_defresult ($index);
2603 Get the default result (provided by libvirt) for the "index"'th
2604 requested credential. If libvirt did not provide a default result,
2605 this returns the empty string "".
2606 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2608 example code.
2609 $prompt = $g->get_libvirt_requested_credential_prompt ($index);
2611 Get the prompt (provided by libvirt) for the "index"'th requested
2612 credential. If libvirt did not provide a prompt, this returns the
2613 empty string "".
2614 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2616 example code.
2617 @creds = $g->get_libvirt_requested_credentials ();
2619 This should only be called during the event callback for events of
2620 type "GUESTFS_EVENT_LIBVIRT_AUTH".
2621 Return the list of credentials requested by libvirt. Possible
2623 values are a subset of the strings provided when you called
2624 "$g->set_libvirt_supported_credentials".
2625 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2627 example code.
2628 $memsize = $g->get_memsize ();
2630 This gets the memory size in megabytes allocated to the hypervisor.
2631 If "$g->set_memsize" was not called on this handle, and if
2633 "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
2634 default value for memsize.
2635 For more information on the architecture of libguestfs, see
2637 guestfs(3).
2638 $network = $g->get_network ();
2640 This returns the enable network flag.
2641 $path = $g->get_path ();
2643 Return the current search path.
2644 This is always non-NULL. If it wasn't set already, then this will
2646 return the default path.
2647 $pgroup = $g->get_pgroup ();
2649 This returns the process group flag.
2650 $pid = $g->get_pid ();
2652 Return the process ID of the hypervisor. If there is no hypervisor
2653 running, then this will return an error.
2654 This is an internal call used for debugging and testing.
2656 $program = $g->get_program ();
2658 Get the program name. See "$g->set_program".
2659 $hv = $g->get_qemu ();
2661 Return the current hypervisor binary (usually qemu).
2662 This is always non-NULL. If it wasn't set already, then this will
2664 return the default qemu binary name.
2665 This function is deprecated. In new code, use the "get_hv" call
2667 instead.
2668 Deprecated functions will not be removed from the API, but the fact
2670 that they are deprecated indicates that there are problems with
2671 correct use of these functions.
2672 $recoveryproc = $g->get_recovery_proc ();
2674 Return the recovery process enabled flag.
2675 $selinux = $g->get_selinux ();
2677 This returns the current setting of the selinux flag which is
2678 passed to the appliance at boot time. See "$g->set_selinux".
2679 For more information on the architecture of libguestfs, see
2681 guestfs(3).
2682 This function is deprecated. In new code, use the
2684 "selinux_relabel" call instead.
2685 Deprecated functions will not be removed from the API, but the fact
2687 that they are deprecated indicates that there are problems with
2688 correct use of these functions.
2689 $smp = $g->get_smp ();
2691 This returns the number of virtual CPUs assigned to the appliance.
2692 $sockdir = $g->get_sockdir ();
2694 Get the directory used by the handle to store temporary socket
2695 files.
2696 This is different from "$g->get_tmpdir", as we need shorter paths
2698 for sockets (due to the limited buffers of filenames for UNIX
2699 sockets), and "$g->get_tmpdir" may be too long for them.
2700 The environment variable "XDG_RUNTIME_DIR" controls the default
2702 value: If "XDG_RUNTIME_DIR" is set, then that is the default. Else
2703 /tmp is the default.
2704 $state = $g->get_state ();
2706 This returns the current state as an opaque integer. This is only
2707 useful for printing debug and internal error messages.
2708 For more information on states, see guestfs(3).
2710 $tmpdir = $g->get_tmpdir ();
2712 Get the directory used by the handle to store temporary files.
2713 $trace = $g->get_trace ();
2715 Return the command trace flag.
2716 $mask = $g->get_umask ();
2718 Return the current umask. By default the umask is 022 unless it
2719 has been set by calling "$g->umask".
2720 $verbose = $g->get_verbose ();
2722 This returns the verbose messages flag.
2723 $context = $g->getcon ();
2725 This gets the SELinux security context of the daemon.
2726 See the documentation about SELINUX in guestfs(3), and "$g->setcon"
2728 This function depends on the feature "selinux". See also
2730 "$g->feature-available".
2731 This function is deprecated. In new code, use the
2733 "selinux_relabel" call instead.
2734 Deprecated functions will not be removed from the API, but the fact
2736 that they are deprecated indicates that there are problems with
2737 correct use of these functions.
2738 $xattr = $g->getxattr ($path, $name);
2740 Get a single extended attribute from file "path" named "name".
2741 This call follows symlinks. If you want to lookup an extended
2742 attribute for the symlink itself, use "$g->lgetxattr".
2743 Normally it is better to get all extended attributes from a file in
2745 one go by calling "$g->getxattrs". However some Linux filesystem
2746 implementations are buggy and do not provide a way to list out
2747 attributes. For these filesystems (notably ntfs-3g) you have to
2748 know the names of the extended attributes you want in advance and
2749 call this function.
2750 Extended attribute values are blobs of binary data. If there is no
2752 extended attribute named "name", this returns an error.
2753 See also: "$g->getxattrs", "$g->lgetxattr", attr(5).
2755 This function depends on the feature "linuxxattrs". See also
2757 "$g->feature-available".
2758 @xattrs = $g->getxattrs ($path);
2760 This call lists the extended attributes of the file or directory
2761 "path".
2762 At the system call level, this is a combination of the listxattr(2)
2764 and getxattr(2) calls.
2765 See also: "$g->lgetxattrs", attr(5).
2767 This function depends on the feature "linuxxattrs". See also
2769 "$g->feature-available".
2770 @paths = $g->glob_expand ($pattern [, directoryslash =>
2772 $directoryslash]);
2773 This command searches for all the pathnames matching "pattern"
2774 according to the wildcard expansion rules used by the shell.
2775 If no paths match, then this returns an empty list (note: not an
2777 error).
2778 It is just a wrapper around the C glob(3) function with flags
2780 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
2781 "directoryslash" controls whether use the "GLOB_MARK" flag for
2783 glob(3), and it defaults to true. It can be explicitly set as off
2784 to return no trailing slashes in filenames of directories.
2785 Notice that there is no equivalent command for expanding a device
2787 name (eg. /dev/sd*). Use "$g->list_devices", "$g->list_partitions"
2788 etc functions instead.
2789 @paths = $g->glob_expand_opts ($pattern [, directoryslash =>
2791 $directoryslash]);
2792 This is an alias of "glob_expand".
2793 @lines = $g->grep ($regex, $path [, extended => $extended] [, fixed =>
2795 $fixed] [, insensitive => $insensitive] [, compressed => $compressed]);
2796 This calls the external grep(1) program and returns the matching
2797 lines.
2798 The optional flags are:
2800 "extended"
2802 Use extended regular expressions. This is the same as using
2803 the -E flag.
2804 "fixed"
2806 Match fixed (don't use regular expressions). This is the same
2807 as using the -F flag.
2808 "insensitive"
2810 Match case-insensitive. This is the same as using the -i flag.
2811 "compressed"
2813 Use zgrep(1) instead of grep(1). This allows the input to be
2814 compress- or gzip-compressed.
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 @lines = $g->grep_opts ($regex, $path [, extended => $extended] [,
2821 fixed => $fixed] [, insensitive => $insensitive] [, compressed =>
2822 $compressed]);
2823 This is an alias of "grep".
2824 @lines = $g->grepi ($regex, $path);
2826 This calls the external "grep -i" program and returns the matching
2827 lines.
2828 Because of the message protocol, there is a transfer limit of
2830 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2831 guestfs(3).
2832 This function is deprecated. In new code, use the "grep" call
2834 instead.
2835 Deprecated functions will not be removed from the API, but the fact
2837 that they are deprecated indicates that there are problems with
2838 correct use of these functions.
2839 $g->grub_install ($root, $device);
2841 This command installs GRUB 1 (the Grand Unified Bootloader) on
2842 "device", with the root directory being "root".
2843 Notes:
2845 • There is currently no way in the API to install grub2, which is
2847 used by most modern Linux guests. It is possible to run the
2848 grub2 command from the guest, although see the caveats in
2849 "RUNNING COMMANDS" in guestfs(3).
2850 • This uses grub-install(8) from the host. Unfortunately grub is
2852 not always compatible with itself, so this only works in rather
2853 narrow circumstances. Careful testing with each guest version
2854 is advisable.
2855 • If grub-install reports the error "No suitable drive was found
2857 in the generated device map." it may be that you need to
2858 create a /boot/grub/device.map file first that contains the
2859 mapping between grub device names and Linux device names. It
2860 is usually sufficient to create a file containing:
2861 (hd0) /dev/vda
2863 replacing /dev/vda with the name of the installation device.
2865 This function depends on the feature "grub". See also
2867 "$g->feature-available".
2868 @lines = $g->head ($path);
2870 This command returns up to the first 10 lines of a file as a list
2871 of strings.
2872 Because of the message protocol, there is a transfer limit of
2874 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2875 guestfs(3).
2876 @lines = $g->head_n ($nrlines, $path);
2878 If the parameter "nrlines" is a positive number, this returns the
2879 first "nrlines" lines of the file "path".
2880 If the parameter "nrlines" is a negative number, this returns lines
2882 from the file "path", excluding the last "nrlines" lines.
2883 If the parameter "nrlines" is zero, this returns an empty list.
2885 Because of the message protocol, there is a transfer limit of
2887 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2888 guestfs(3).
2889 $dump = $g->hexdump ($path);
2891 This runs "hexdump -C" on the given "path". The result is the
2892 human-readable, canonical hex dump of the file.
2893 Because of the message protocol, there is a transfer limit of
2895 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2896 guestfs(3).
2897 $g->hivex_close ();
2899 Close the current hivex handle.
2900 This is a wrapper around the hivex(3) call of the same name.
2902 This function depends on the feature "hivex". See also
2904 "$g->feature-available".
2905 $g->hivex_commit ($filename);
2907 Commit (write) changes to the hive.
2908 If the optional filename parameter is null, then the changes are
2910 written back to the same hive that was opened. If this is not null
2911 then they are written to the alternate filename given and the
2912 original hive is left untouched.
2913 This is a wrapper around the hivex(3) call of the same name.
2915 This function depends on the feature "hivex". See also
2917 "$g->feature-available".
2918 $nodeh = $g->hivex_node_add_child ($parent, $name);
2920 Add a child node to "parent" named "name".
2921 This is a wrapper around the hivex(3) call of the same name.
2923 This function depends on the feature "hivex". See also
2925 "$g->feature-available".
2926 @nodehs = $g->hivex_node_children ($nodeh);
2928 Return the list of nodes which are subkeys of "nodeh".
2929 This is a wrapper around the hivex(3) call of the same name.
2931 This function depends on the feature "hivex". See also
2933 "$g->feature-available".
2934 $g->hivex_node_delete_child ($nodeh);
2936 Delete "nodeh", recursively if necessary.
2937 This is a wrapper around the hivex(3) call of the same name.
2939 This function depends on the feature "hivex". See also
2941 "$g->feature-available".
2942 $child = $g->hivex_node_get_child ($nodeh, $name);
2944 Return the child of "nodeh" with the name "name", if it exists.
2945 This can return 0 meaning the name was not found.
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 $valueh = $g->hivex_node_get_value ($nodeh, $key);
2953 Return the value attached to "nodeh" which has the name "key", if
2954 it exists. This can return 0 meaning the key was not found.
2955 This is a wrapper around the hivex(3) call of the same name.
2957 This function depends on the feature "hivex". See also
2959 "$g->feature-available".
2960 $name = $g->hivex_node_name ($nodeh);
2962 Return the name of "nodeh".
2963 This is a wrapper around the hivex(3) call of the same name.
2965 This function depends on the feature "hivex". See also
2967 "$g->feature-available".
2968 $parent = $g->hivex_node_parent ($nodeh);
2970 Return the parent node of "nodeh".
2971 This is a wrapper around the hivex(3) call of the same name.
2973 This function depends on the feature "hivex". See also
2975 "$g->feature-available".
2976 $g->hivex_node_set_value ($nodeh, $key, $t, $val);
2978 Set or replace a single value under the node "nodeh". The "key" is
2979 the name, "t" is the type, and "val" is the data.
2980 This is a wrapper around the hivex(3) call of the same name.
2982 This function depends on the feature "hivex". See also
2984 "$g->feature-available".
2985 @valuehs = $g->hivex_node_values ($nodeh);
2987 Return the array of (key, datatype, data) tuples attached to
2988 "nodeh".
2989 This is a wrapper around the hivex(3) call of the same name.
2991 This function depends on the feature "hivex". See also
2993 "$g->feature-available".
2994 $g->hivex_open ($filename [, verbose => $verbose] [, debug => $debug]
2996 [, write => $write] [, unsafe => $unsafe]);
2997 Open the Windows Registry hive file named filename. If there was
2998 any previous hivex handle associated with this guestfs session,
2999 then it is closed.
3000 This is a wrapper around the hivex(3) call of the same name.
3002 This function depends on the feature "hivex". See also
3004 "$g->feature-available".
3005 $nodeh = $g->hivex_root ();
3007 Return the root node of the hive.
3008 This is a wrapper around the hivex(3) call of the same name.
3010 This function depends on the feature "hivex". See also
3012 "$g->feature-available".
3013 $key = $g->hivex_value_key ($valueh);
3015 Return the key (name) field of a (key, datatype, data) tuple.
3016 This is a wrapper around the hivex(3) call of the same name.
3018 This function depends on the feature "hivex". See also
3020 "$g->feature-available".
3021 $databuf = $g->hivex_value_string ($valueh);
3023 This calls "$g->hivex_value_value" (which returns the data field
3024 from a hivex value tuple). It then assumes that the field is a
3025 UTF-16LE string and converts the result to UTF-8 (or if this is not
3026 possible, it returns an error).
3027 This is useful for reading strings out of the Windows registry.
3029 However it is not foolproof because the registry is not strongly-
3030 typed and fields can contain arbitrary or unexpected data.
3031 This function depends on the feature "hivex". See also
3033 "$g->feature-available".
3034 $datatype = $g->hivex_value_type ($valueh);
3036 Return the data type field from a (key, datatype, data) tuple.
3037 This is a wrapper around the hivex(3) call of the same name.
3039 This function depends on the feature "hivex". See also
3041 "$g->feature-available".
3042 $databuf = $g->hivex_value_utf8 ($valueh);
3044 This calls "$g->hivex_value_value" (which returns the data field
3045 from a hivex value tuple). It then assumes that the field is a
3046 UTF-16LE string and converts the result to UTF-8 (or if this is not
3047 possible, it returns an error).
3048 This is useful for reading strings out of the Windows registry.
3050 However it is not foolproof because the registry is not strongly-
3051 typed and fields can contain arbitrary or unexpected data.
3052 This function depends on the feature "hivex". See also
3054 "$g->feature-available".
3055 This function is deprecated. In new code, use the
3057 "hivex_value_string" call instead.
3058 Deprecated functions will not be removed from the API, but the fact
3060 that they are deprecated indicates that there are problems with
3061 correct use of these functions.
3062 $databuf = $g->hivex_value_value ($valueh);
3064 Return the data field of a (key, datatype, data) tuple.
3065 This is a wrapper around the hivex(3) call of the same name.
3067 See also: "$g->hivex_value_utf8".
3069 This function depends on the feature "hivex". See also
3071 "$g->feature-available".
3072 $content = $g->initrd_cat ($initrdpath, $filename);
3074 This command unpacks the file filename from the initrd file called
3075 initrdpath. The filename must be given without the initial /
3076 character.
3077 For example, in guestfish you could use the following command to
3079 examine the boot script (usually called /init) contained in a Linux
3080 initrd or initramfs image:
3081 initrd-cat /boot/initrd-<version>.img init
3083 See also "$g->initrd_list".
3085 Because of the message protocol, there is a transfer limit of
3087 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
3088 guestfs(3).
3089 @filenames = $g->initrd_list ($path);
3091 This command lists out files contained in an initrd.
3092 The files are listed without any initial / character. The files
3094 are listed in the order they appear (not necessarily alphabetical).
3095 Directory names are listed as separate items.
3096 Old Linux kernels (2.4 and earlier) used a compressed ext2
3098 filesystem as initrd. We only support the newer initramfs format
3099 (compressed cpio files).
3100 $wd = $g->inotify_add_watch ($path, $mask);
3102 Watch "path" for the events listed in "mask".
3103 Note that if "path" is a directory then events within that
3105 directory are watched, but this does not happen recursively (in
3106 subdirectories).
3107 Note for non-C or non-Linux callers: the inotify events are defined
3109 by the Linux kernel ABI and are listed in
3110 /usr/include/sys/inotify.h.
3111 This function depends on the feature "inotify". See also
3113 "$g->feature-available".
3114 $g->inotify_close ();
3116 This closes the inotify handle which was previously opened by
3117 inotify_init. It removes all watches, throws away any pending
3118 events, and deallocates all resources.
3119 This function depends on the feature "inotify". See also
3121 "$g->feature-available".
3122 @paths = $g->inotify_files ();
3124 This function is a helpful wrapper around "$g->inotify_read" which
3125 just returns a list of pathnames of objects that were touched. The
3126 returned pathnames are sorted and deduplicated.
3127 This function depends on the feature "inotify". See also
3129 "$g->feature-available".
3130 $g->inotify_init ($maxevents);
3132 This command creates a new inotify handle. The inotify subsystem
3133 can be used to notify events which happen to objects in the guest
3134 filesystem.
3135 "maxevents" is the maximum number of events which will be queued up
3137 between calls to "$g->inotify_read" or "$g->inotify_files". If
3138 this is passed as 0, then the kernel (or previously set) default is
3139 used. For Linux 2.6.29 the default was 16384 events. Beyond this
3140 limit, the kernel throws away events, but records the fact that it
3141 threw them away by setting a flag "IN_Q_OVERFLOW" in the returned
3142 structure list (see "$g->inotify_read").
3143 Before any events are generated, you have to add some watches to
3145 the internal watch list. See: "$g->inotify_add_watch" and
3146 "$g->inotify_rm_watch".
3147 Queued up events should be read periodically by calling
3149 "$g->inotify_read" (or "$g->inotify_files" which is just a helpful
3150 wrapper around "$g->inotify_read"). If you don't read the events
3151 out often enough then you risk the internal queue overflowing.
3152 The handle should be closed after use by calling
3154 "$g->inotify_close". This also removes any watches automatically.
3155 See also inotify(7) for an overview of the inotify interface as
3157 exposed by the Linux kernel, which is roughly what we expose via
3158 libguestfs. Note that there is one global inotify handle per
3159 libguestfs instance.
3160 This function depends on the feature "inotify". See also
3162 "$g->feature-available".
3163 @events = $g->inotify_read ();
3165 Return the complete queue of events that have happened since the
3166 previous read call.
3167 If no events have happened, this returns an empty list.
3169 Note: In order to make sure that all events have been read, you
3171 must call this function repeatedly until it returns an empty list.
3172 The reason is that the call will read events up to the maximum
3173 appliance-to-host message size and leave remaining events in the
3174 queue.
3175 This function depends on the feature "inotify". See also
3177 "$g->feature-available".
3178 $g->inotify_rm_watch ($wd);
3180 Remove a previously defined inotify watch. See
3181 "$g->inotify_add_watch".
3182 This function depends on the feature "inotify". See also
3184 "$g->feature-available".
3185 $arch = $g->inspect_get_arch ($root);
3187 This returns the architecture of the inspected operating system.
3188 The possible return values are listed under
3189 "$g->file_architecture".
3190 If the architecture could not be determined, then the string
3192 "unknown" is returned.
3193 Please read "INSPECTION" in guestfs(3) for more details.
3195 $distro = $g->inspect_get_distro ($root);
3197 This returns the distro (distribution) of the inspected operating
3198 system.
3199 Currently defined distros are:
3201 "alpinelinux"
3203 Alpine Linux.
3204 "altlinux"
3206 ALT Linux.
3207 "archlinux"
3209 Arch Linux.
3210 "buildroot"
3212 Buildroot-derived distro, but not one we specifically
3213 recognize.
3214 "centos"
3216 CentOS.
3217 "cirros"
3219 Cirros.
3220 "coreos"
3222 CoreOS.
3223 "debian"
3225 Debian.
3226 "fedora"
3228 Fedora.
3229 "freebsd"
3231 FreeBSD.
3232 "freedos"
3234 FreeDOS.
3235 "frugalware"
3237 Frugalware.
3238 "gentoo"
3240 Gentoo.
3241 "kalilinux"
3243 Kali Linux.
3244 "linuxmint"
3246 Linux Mint.
3247 "mageia"
3249 Mageia.
3250 "mandriva"
3252 Mandriva.
3253 "meego"
3255 MeeGo.
3256 "msdos"
3258 Microsoft DOS.
3259 "neokylin"
3261 NeoKylin.
3262 "netbsd"
3264 NetBSD.
3265 "openbsd"
3267 OpenBSD.
3268 "openmandriva"
3270 OpenMandriva Lx.
3271 "opensuse"
3273 OpenSUSE.
3274 "oraclelinux"
3276 Oracle Linux.
3277 "pardus"
3279 Pardus.
3280 "pldlinux"
3282 PLD Linux.
3283 "redhat-based"
3285 Some Red Hat-derived distro.
3286 "rhel"
3288 Red Hat Enterprise Linux.
3289 "scientificlinux"
3291 Scientific Linux.
3292 "slackware"
3294 Slackware.
3295 "sles"
3297 SuSE Linux Enterprise Server or Desktop.
3298 "suse-based"
3300 Some openSuSE-derived distro.
3301 "ttylinux"
3303 ttylinux.
3304 "ubuntu"
3306 Ubuntu.
3307 "unknown"
3309 The distro could not be determined.
3310 "voidlinux"
3312 Void Linux.
3313 "windows"
3315 Windows does not have distributions. This string is returned
3316 if the OS type is Windows.
3317 Future versions of libguestfs may return other strings here. The
3319 caller should be prepared to handle any string.
3320 Please read "INSPECTION" in guestfs(3) for more details.
3322 %drives = $g->inspect_get_drive_mappings ($root);
3324 This call is useful for Windows which uses a primitive system of
3325 assigning drive letters (like C:\) to partitions. This inspection
3326 API examines the Windows Registry to find out how disks/partitions
3327 are mapped to drive letters, and returns a hash table as in the
3328 example below:
3329 C => /dev/vda2
3331 E => /dev/vdb1
3332 F => /dev/vdc1
3333 Note that keys are drive letters. For Windows, the key is case
3335 insensitive and just contains the drive letter, without the
3336 customary colon separator character.
3337 In future we may support other operating systems that also used
3339 drive letters, but the keys for those might not be case insensitive
3340 and might be longer than 1 character. For example in OS-9, hard
3341 drives were named "h0", "h1" etc.
3342 For Windows guests, currently only hard drive mappings are
3344 returned. Removable disks (eg. DVD-ROMs) are ignored.
3345 For guests that do not use drive mappings, or if the drive mappings
3347 could not be determined, this returns an empty hash table.
3348 Please read "INSPECTION" in guestfs(3) for more details. See also
3350 "$g->inspect_get_mountpoints", "$g->inspect_get_filesystems".
3351 @filesystems = $g->inspect_get_filesystems ($root);
3353 This returns a list of all the filesystems that we think are
3354 associated with this operating system. This includes the root
3355 filesystem, other ordinary filesystems, and non-mounted devices
3356 like swap partitions.
3357 In the case of a multi-boot virtual machine, it is possible for a
3359 filesystem to be shared between operating systems.
3360 Please read "INSPECTION" in guestfs(3) for more details. See also
3362 "$g->inspect_get_mountpoints".
3363 $format = $g->inspect_get_format ($root);
3365 Before libguestfs 1.38, there was some unreliable support for
3366 detecting installer CDs. This API would return:
3367 "installed"
3369 This is an installed operating system.
3370 "installer"
3372 The disk image being inspected is not an installed operating
3373 system, but a bootable install disk, live CD, or similar.
3374 "unknown"
3376 The format of this disk image is not known.
3377 In libguestfs X 1.38, this only returns "installed". Use libosinfo
3379 directly to detect installer CDs.
3380 Please read "INSPECTION" in guestfs(3) for more details.
3382 This function is deprecated. There is no replacement. Consult the
3384 API documentation in guestfs(3) for further information.
3385 Deprecated functions will not be removed from the API, but the fact
3387 that they are deprecated indicates that there are problems with
3388 correct use of these functions.
3389 $hostname = $g->inspect_get_hostname ($root);
3391 This function returns the hostname of the operating system as found
3392 by inspection of the guestXs configuration files.
3393 If the hostname could not be determined, then the string "unknown"
3395 is returned.
3396 Please read "INSPECTION" in guestfs(3) for more details.
3398 $icon = $g->inspect_get_icon ($root [, favicon => $favicon] [,
3400 highquality => $highquality]);
3401 This function returns an icon corresponding to the inspected
3402 operating system. The icon is returned as a buffer containing a
3403 PNG image (re-encoded to PNG if necessary).
3404 If it was not possible to get an icon this function returns a zero-
3406 length (non-NULL) buffer. Callers must check for this case.
3407 Libguestfs will start by looking for a file called /etc/favicon.png
3409 or C:\etc\favicon.png and if it has the correct format, the
3410 contents of this file will be returned. You can disable favicons
3411 by passing the optional "favicon" boolean as false (default is
3412 true).
3413 If finding the favicon fails, then we look in other places in the
3415 guest for a suitable icon.
3416 If the optional "highquality" boolean is true then only high
3418 quality icons are returned, which means only icons of high
3419 resolution with an alpha channel. The default (false) is to return
3420 any icon we can, even if it is of substandard quality.
3421 Notes:
3423 • Unlike most other inspection API calls, the guestXs disks must
3425 be mounted up before you call this, since it needs to read
3426 information from the guest filesystem during the call.
3427 • Security: The icon data comes from the untrusted guest, and
3429 should be treated with caution. PNG files have been known to
3430 contain exploits. Ensure that libpng (or other relevant
3431 libraries) are fully up to date before trying to process or
3432 display the icon.
3433 • The PNG image returned can be any size. It might not be
3435 square. Libguestfs tries to return the largest, highest
3436 quality icon available. The application must scale the icon to
3437 the required size.
3438 • Extracting icons from Windows guests requires the external
3440 wrestool(1) program from the "icoutils" package, and several
3441 programs (bmptopnm(1), pnmtopng(1), pamcut(1)) from the
3442 "netpbm" package. These must be installed separately.
3443 • Operating system icons are usually trademarks. Seek legal
3445 advice before using trademarks in applications.
3446 $major = $g->inspect_get_major_version ($root);
3448 This returns the major version number of the inspected operating
3449 system.
3450 Windows uses a consistent versioning scheme which is not reflected
3452 in the popular public names used by the operating system. Notably
3453 the operating system known as "Windows 7" is really version 6.1
3454 (ie. major = 6, minor = 1). You can find out the real versions
3455 corresponding to releases of Windows by consulting Wikipedia or
3456 MSDN.
3457 If the version could not be determined, then 0 is returned.
3459 Please read "INSPECTION" in guestfs(3) for more details.
3461 $minor = $g->inspect_get_minor_version ($root);
3463 This returns the minor version number of the inspected operating
3464 system.
3465 If the version could not be determined, then 0 is returned.
3467 Please read "INSPECTION" in guestfs(3) for more details. See also
3469 "$g->inspect_get_major_version".
3470 %mountpoints = $g->inspect_get_mountpoints ($root);
3472 This returns a hash of where we think the filesystems associated
3473 with this operating system should be mounted. Callers should note
3474 that this is at best an educated guess made by reading
3475 configuration files such as /etc/fstab. In particular note that
3476 this may return filesystems which are non-existent or not mountable
3477 and callers should be prepared to handle or ignore failures if they
3478 try to mount them.
3479 Each element in the returned hashtable has a key which is the path
3481 of the mountpoint (eg. /boot) and a value which is the filesystem
3482 that would be mounted there (eg. /dev/sda1).
3483 Non-mounted devices such as swap devices are not returned in this
3485 list.
3486 For operating systems like Windows which still use drive letters,
3488 this call will only return an entry for the first drive "mounted
3489 on" /. For information about the mapping of drive letters to
3490 partitions, see "$g->inspect_get_drive_mappings".
3491 Please read "INSPECTION" in guestfs(3) for more details. See also
3493 "$g->inspect_get_filesystems".
3494 $id = $g->inspect_get_osinfo ($root);
3496 This function returns a possible short ID for libosinfo
3497 corresponding to the guest.
3498 Note: The returned ID is only a guess by libguestfs, and nothing
3500 ensures that it actually exists in osinfo-db.
3501 If no ID could not be determined, then the string "unknown" is
3503 returned.
3504 $packageformat = $g->inspect_get_package_format ($root);
3506 This function and "$g->inspect_get_package_management" return the
3507 package format and package management tool used by the inspected
3508 operating system. For example for Fedora these functions would
3509 return "rpm" (package format), and "yum" or "dnf" (package
3510 management).
3511 This returns the string "unknown" if we could not determine the
3513 package format or if the operating system does not have a real
3514 packaging system (eg. Windows).
3515 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
3517 "pkgsrc", "apk", "xbps". Future versions of libguestfs may return
3518 other strings.
3519 Please read "INSPECTION" in guestfs(3) for more details.
3521 $packagemanagement = $g->inspect_get_package_management ($root);
3523 "$g->inspect_get_package_format" and this function return the
3524 package format and package management tool used by the inspected
3525 operating system. For example for Fedora these functions would
3526 return "rpm" (package format), and "yum" or "dnf" (package
3527 management).
3528 This returns the string "unknown" if we could not determine the
3530 package management tool or if the operating system does not have a
3531 real packaging system (eg. Windows).
3532 Possible strings include: "yum", "dnf", "up2date", "apt" (for all
3534 Debian derivatives), "portage", "pisi", "pacman", "urpmi",
3535 "zypper", "apk", "xbps". Future versions of libguestfs may return
3536 other strings.
3537 Please read "INSPECTION" in guestfs(3) for more details.
3539 $product = $g->inspect_get_product_name ($root);
3541 This returns the product name of the inspected operating system.
3542 The product name is generally some freeform string which can be
3543 displayed to the user, but should not be parsed by programs.
3544 If the product name could not be determined, then the string
3546 "unknown" is returned.
3547 Please read "INSPECTION" in guestfs(3) for more details.
3549 $variant = $g->inspect_get_product_variant ($root);
3551 This returns the product variant of the inspected operating system.
3552 For Windows guests, this returns the contents of the Registry key
3554 "HKLM\Software\Microsoft\Windows NT\CurrentVersion"
3555 "InstallationType" which is usually a string such as "Client" or
3556 "Server" (other values are possible). This can be used to
3557 distinguish consumer and enterprise versions of Windows that have
3558 the same version number (for example, Windows 7 and Windows 2008
3559 Server are both version 6.1, but the former is "Client" and the
3560 latter is "Server").
3561 For enterprise Linux guests, in future we intend this to return the
3563 product variant such as "Desktop", "Server" and so on. But this is
3564 not implemented at present.
3565 If the product variant could not be determined, then the string
3567 "unknown" is returned.
3568 Please read "INSPECTION" in guestfs(3) for more details. See also
3570 "$g->inspect_get_product_name", "$g->inspect_get_major_version".
3571 @roots = $g->inspect_get_roots ();
3573 This function is a convenient way to get the list of root devices,
3574 as returned from a previous call to "$g->inspect_os", but without
3575 redoing the whole inspection process.
3576 This returns an empty list if either no root devices were found or
3578 the caller has not called "$g->inspect_os".
3579 Please read "INSPECTION" in guestfs(3) for more details.
3581 $name = $g->inspect_get_type ($root);
3583 This returns the type of the inspected operating system. Currently
3584 defined types are:
3585 "linux"
3587 Any Linux-based operating system.
3588 "windows"
3590 Any Microsoft Windows operating system.
3591 "freebsd"
3593 FreeBSD.
3594 "netbsd"
3596 NetBSD.
3597 "openbsd"
3599 OpenBSD.
3600 "hurd"
3602 GNU/Hurd.
3603 "dos"
3605 MS-DOS, FreeDOS and others.
3606 "minix"
3608 MINIX.
3609 "unknown"
3611 The operating system type could not be determined.
3612 Future versions of libguestfs may return other strings here. The
3614 caller should be prepared to handle any string.
3615 Please read "INSPECTION" in guestfs(3) for more details.
3617 $controlset = $g->inspect_get_windows_current_control_set ($root);
3619 This returns the Windows CurrentControlSet of the inspected guest.
3620 The CurrentControlSet is a registry key name such as
3621 "ControlSet001".
3622 This call assumes that the guest is Windows and that the Registry
3624 could be examined by inspection. If this is not the case then an
3625 error is returned.
3626 Please read "INSPECTION" in guestfs(3) for more details.
3628 $path = $g->inspect_get_windows_software_hive ($root);
3630 This returns the path to the hive (binary Windows Registry file)
3631 corresponding to HKLM\SOFTWARE.
3632 This call assumes that the guest is Windows and that the guest has
3634 a software hive file with the right name. If this is not the case
3635 then an error is returned. This call does not check that the hive
3636 is a valid Windows Registry hive.
3637 You can use "$g->hivex_open" to read or write to the hive.
3639 Please read "INSPECTION" in guestfs(3) for more details.
3641 $path = $g->inspect_get_windows_system_hive ($root);
3643 This returns the path to the hive (binary Windows Registry file)
3644 corresponding to HKLM\SYSTEM.
3645 This call assumes that the guest is Windows and that the guest has
3647 a system hive file with the right name. If this is not the case
3648 then an error is returned. This call does not check that the hive
3649 is a valid Windows Registry hive.
3650 You can use "$g->hivex_open" to read or write to the hive.
3652 Please read "INSPECTION" in guestfs(3) for more details.
3654 $systemroot = $g->inspect_get_windows_systemroot ($root);
3656 This returns the Windows systemroot of the inspected guest. The
3657 systemroot is a directory path such as /WINDOWS.
3658 This call assumes that the guest is Windows and that the systemroot
3660 could be determined by inspection. If this is not the case then an
3661 error is returned.
3662 Please read "INSPECTION" in guestfs(3) for more details.
3664 $live = $g->inspect_is_live ($root);
3666 This is deprecated and always returns "false".
3667 Please read "INSPECTION" in guestfs(3) for more details.
3669 This function is deprecated. There is no replacement. Consult the
3671 API documentation in guestfs(3) for further information.
3672 Deprecated functions will not be removed from the API, but the fact
3674 that they are deprecated indicates that there are problems with
3675 correct use of these functions.
3676 $multipart = $g->inspect_is_multipart ($root);
3678 This is deprecated and always returns "false".
3679 Please read "INSPECTION" in guestfs(3) for more details.
3681 This function is deprecated. There is no replacement. Consult the
3683 API documentation in guestfs(3) for further information.
3684 Deprecated functions will not be removed from the API, but the fact
3686 that they are deprecated indicates that there are problems with
3687 correct use of these functions.
3688 $netinst = $g->inspect_is_netinst ($root);
3690 This is deprecated and always returns "false".
3691 Please read "INSPECTION" in guestfs(3) for more details.
3693 This function is deprecated. There is no replacement. Consult the
3695 API documentation in guestfs(3) for further information.
3696 Deprecated functions will not be removed from the API, but the fact
3698 that they are deprecated indicates that there are problems with
3699 correct use of these functions.
3700 @applications = $g->inspect_list_applications ($root);
3702 Return the list of applications installed in the operating system.
3703 Note: This call works differently from other parts of the
3705 inspection API. You have to call "$g->inspect_os", then
3706 "$g->inspect_get_mountpoints", then mount up the disks, before
3707 calling this. Listing applications is a significantly more
3708 difficult operation which requires access to the full filesystem.
3709 Also note that unlike the other "$g->inspect_get_*" calls which are
3710 just returning data cached in the libguestfs handle, this call
3711 actually reads parts of the mounted filesystems during the call.
3712 This returns an empty list if the inspection code was not able to
3714 determine the list of applications.
3715 The application structure contains the following fields:
3717 "app_name"
3719 The name of the application. For Linux guests, this is the
3720 package name.
3721 "app_display_name"
3723 The display name of the application, sometimes localized to the
3724 install language of the guest operating system.
3725 If unavailable this is returned as an empty string "". Callers
3727 needing to display something can use "app_name" instead.
3728 "app_epoch"
3730 For package managers which use epochs, this contains the epoch
3731 of the package (an integer). If unavailable, this is returned
3732 as 0.
3733 "app_version"
3735 The version string of the application or package. If
3736 unavailable this is returned as an empty string "".
3737 "app_release"
3739 The release string of the application or package, for package
3740 managers that use this. If unavailable this is returned as an
3741 empty string "".
3742 "app_install_path"
3744 The installation path of the application (on operating systems
3745 such as Windows which use installation paths). This path is in
3746 the format used by the guest operating system, it is not a
3747 libguestfs path.
3748 If unavailable this is returned as an empty string "".
3750 "app_trans_path"
3752 The install path translated into a libguestfs path. If
3753 unavailable this is returned as an empty string "".
3754 "app_publisher"
3756 The name of the publisher of the application, for package
3757 managers that use this. If unavailable this is returned as an
3758 empty string "".
3759 "app_url"
3761 The URL (eg. upstream URL) of the application. If unavailable
3762 this is returned as an empty string "".
3763 "app_source_package"
3765 For packaging systems which support this, the name of the
3766 source package. If unavailable this is returned as an empty
3767 string "".
3768 "app_summary"
3770 A short (usually one line) description of the application or
3771 package. If unavailable this is returned as an empty string
3772 "".
3773 "app_description"
3775 A longer description of the application or package. If
3776 unavailable this is returned as an empty string "".
3777 Please read "INSPECTION" in guestfs(3) for more details.
3779 This function is deprecated. In new code, use the
3781 "inspect_list_applications2" call instead.
3782 Deprecated functions will not be removed from the API, but the fact
3784 that they are deprecated indicates that there are problems with
3785 correct use of these functions.
3786 @applications2 = $g->inspect_list_applications2 ($root);
3788 Return the list of applications installed in the operating system.
3789 Note: This call works differently from other parts of the
3791 inspection API. You have to call "$g->inspect_os", then
3792 "$g->inspect_get_mountpoints", then mount up the disks, before
3793 calling this. Listing applications is a significantly more
3794 difficult operation which requires access to the full filesystem.
3795 Also note that unlike the other "$g->inspect_get_*" calls which are
3796 just returning data cached in the libguestfs handle, this call
3797 actually reads parts of the mounted filesystems during the call.
3798 This returns an empty list if the inspection code was not able to
3800 determine the list of applications.
3801 The application structure contains the following fields:
3803 "app2_name"
3805 The name of the application. For Linux guests, this is the
3806 package name.
3807 "app2_display_name"
3809 The display name of the application, sometimes localized to the
3810 install language of the guest operating system.
3811 If unavailable this is returned as an empty string "". Callers
3813 needing to display something can use "app2_name" instead.
3814 "app2_epoch"
3816 For package managers which use epochs, this contains the epoch
3817 of the package (an integer). If unavailable, this is returned
3818 as 0.
3819 "app2_version"
3821 The version string of the application or package. If
3822 unavailable this is returned as an empty string "".
3823 "app2_release"
3825 The release string of the application or package, for package
3826 managers that use this. If unavailable this is returned as an
3827 empty string "".
3828 "app2_arch"
3830 The architecture string of the application or package, for
3831 package managers that use this. If unavailable this is
3832 returned as an empty string "".
3833 "app2_install_path"
3835 The installation path of the application (on operating systems
3836 such as Windows which use installation paths). This path is in
3837 the format used by the guest operating system, it is not a
3838 libguestfs path.
3839 If unavailable this is returned as an empty string "".
3841 "app2_trans_path"
3843 The install path translated into a libguestfs path. If
3844 unavailable this is returned as an empty string "".
3845 "app2_publisher"
3847 The name of the publisher of the application, for package
3848 managers that use this. If unavailable this is returned as an
3849 empty string "".
3850 "app2_url"
3852 The URL (eg. upstream URL) of the application. If unavailable
3853 this is returned as an empty string "".
3854 "app2_source_package"
3856 For packaging systems which support this, the name of the
3857 source package. If unavailable this is returned as an empty
3858 string "".
3859 "app2_summary"
3861 A short (usually one line) description of the application or
3862 package. If unavailable this is returned as an empty string
3863 "".
3864 "app2_description"
3866 A longer description of the application or package. If
3867 unavailable this is returned as an empty string "".
3868 Please read "INSPECTION" in guestfs(3) for more details.
3870 @roots = $g->inspect_os ();
3872 This function uses other libguestfs functions and certain
3873 heuristics to inspect the disk(s) (usually disks belonging to a
3874 virtual machine), looking for operating systems.
3875 The list returned is empty if no operating systems were found.
3877 If one operating system was found, then this returns a list with a
3879 single element, which is the name of the root filesystem of this
3880 operating system. It is also possible for this function to return
3881 a list containing more than one element, indicating a dual-boot or
3882 multi-boot virtual machine, with each element being the root
3883 filesystem of one of the operating systems.
3884 You can pass the root string(s) returned to other
3886 "$g->inspect_get_*" functions in order to query further information
3887 about each operating system, such as the name and version.
3888 This function uses other libguestfs features such as "$g->mount_ro"
3890 and "$g->umount_all" in order to mount and unmount filesystems and
3891 look at the contents. This should be called with no disks
3892 currently mounted. The function may also use Augeas, so any
3893 existing Augeas handle will be closed.
3894 This function cannot decrypt encrypted disks. The caller must do
3896 that first (supplying the necessary keys) if the disk is encrypted.
3897 Please read "INSPECTION" in guestfs(3) for more details.
3899 See also "$g->list_filesystems".
3901 $flag = $g->is_blockdev ($path [, followsymlinks => $followsymlinks]);
3903 This returns "true" if and only if there is a block device with the
3904 given "path" name.
3905 If the optional flag "followsymlinks" is true, then a symlink (or
3907 chain of symlinks) that ends with a block device also causes the
3908 function to return true.
3909 This call only looks at files within the guest filesystem.
3911 Libguestfs partitions and block devices (eg. /dev/sda) cannot be
3912 used as the "path" parameter of this call.
3913 See also "$g->stat".
3915 $flag = $g->is_blockdev_opts ($path [, followsymlinks =>
3917 $followsymlinks]);
3918 This is an alias of "is_blockdev".
3919 $busy = $g->is_busy ();
3921 This always returns false. This function is deprecated with no
3922 replacement. Do not use this function.
3923 For more information on states, see guestfs(3).
3925 $flag = $g->is_chardev ($path [, followsymlinks => $followsymlinks]);
3927 This returns "true" if and only if there is a character device with
3928 the given "path" name.
3929 If the optional flag "followsymlinks" is true, then a symlink (or
3931 chain of symlinks) that ends with a chardev also causes the
3932 function to return true.
3933 See also "$g->stat".
3935 $flag = $g->is_chardev_opts ($path [, followsymlinks =>
3937 $followsymlinks]);
3938 This is an alias of "is_chardev".
3939 $config = $g->is_config ();
3941 This returns true iff this handle is being configured (in the
3942 "CONFIG" state).
3943 For more information on states, see guestfs(3).
3945 $dirflag = $g->is_dir ($path [, followsymlinks => $followsymlinks]);
3947 This returns "true" if and only if there is a directory with the
3948 given "path" name. Note that it returns false for other objects
3949 like files.
3950 If the optional flag "followsymlinks" is true, then a symlink (or
3952 chain of symlinks) that ends with a directory also causes the
3953 function to return true.
3954 See also "$g->stat".
3956 $dirflag = $g->is_dir_opts ($path [, followsymlinks =>
3958 $followsymlinks]);
3959 This is an alias of "is_dir".
3960 $flag = $g->is_fifo ($path [, followsymlinks => $followsymlinks]);
3962 This returns "true" if and only if there is a FIFO (named pipe)
3963 with the given "path" name.
3964 If the optional flag "followsymlinks" is true, then a symlink (or
3966 chain of symlinks) that ends with a FIFO also causes the function
3967 to return true.
3968 See also "$g->stat".
3970 $flag = $g->is_fifo_opts ($path [, followsymlinks => $followsymlinks]);
3972 This is an alias of "is_fifo".
3973 $fileflag = $g->is_file ($path [, followsymlinks => $followsymlinks]);
3975 This returns "true" if and only if there is a regular file with the
3976 given "path" name. Note that it returns false for other objects
3977 like directories.
3978 If the optional flag "followsymlinks" is true, then a symlink (or
3980 chain of symlinks) that ends with a file also causes the function
3981 to return true.
3982 See also "$g->stat".
3984 $fileflag = $g->is_file_opts ($path [, followsymlinks =>
3986 $followsymlinks]);
3987 This is an alias of "is_file".
3988 $launching = $g->is_launching ();
3990 This returns true iff this handle is launching the subprocess (in
3991 the "LAUNCHING" state).
3992 For more information on states, see guestfs(3).
3994 $lvflag = $g->is_lv ($mountable);
3996 This command tests whether "mountable" is a logical volume, and
3997 returns true iff this is the case.
3998 $ready = $g->is_ready ();
4000 This returns true iff this handle is ready to accept commands (in
4001 the "READY" state).
4002 For more information on states, see guestfs(3).
4004 $flag = $g->is_socket ($path [, followsymlinks => $followsymlinks]);
4006 This returns "true" if and only if there is a Unix domain socket
4007 with the given "path" name.
4008 If the optional flag "followsymlinks" is true, then a symlink (or
4010 chain of symlinks) that ends with a socket also causes the function
4011 to return true.
4012 See also "$g->stat".
4014 $flag = $g->is_socket_opts ($path [, followsymlinks =>
4016 $followsymlinks]);
4017 This is an alias of "is_socket".
4018 $flag = $g->is_symlink ($path);
4020 This returns "true" if and only if there is a symbolic link with
4021 the given "path" name.
4022 See also "$g->stat".
4024 $flag = $g->is_whole_device ($device);
4026 This returns "true" if and only if "device" refers to a whole block
4027 device. That is, not a partition or a logical device.
4028 $zeroflag = $g->is_zero ($path);
4030 This returns true iff the file exists and the file is empty or it
4031 contains all zero bytes.
4032 $zeroflag = $g->is_zero_device ($device);
4034 This returns true iff the device exists and contains all zero
4035 bytes.
4036 Note that for large devices this can take a long time to run.
4038 %isodata = $g->isoinfo ($isofile);
4040 This is the same as "$g->isoinfo_device" except that it works for
4041 an ISO file located inside some other mounted filesystem. Note
4042 that in the common case where you have added an ISO file as a
4043 libguestfs device, you would not call this. Instead you would call
4044 "$g->isoinfo_device".
4045 %isodata = $g->isoinfo_device ($device);
4047 "device" is an ISO device. This returns a struct of information
4048 read from the primary volume descriptor (the ISO equivalent of the
4049 superblock) of the device.
4050 Usually it is more efficient to use the isoinfo(1) command with the
4052 -d option on the host to analyze ISO files, instead of going
4053 through libguestfs.
4054 For information on the primary volume descriptor fields, see
4056 <https://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor>
4057 $g->journal_close ();
4059 Close the journal handle.
4060 This function depends on the feature "journal". See also
4062 "$g->feature-available".
4063 @fields = $g->journal_get ();
4065 Read the current journal entry. This returns all the fields in the
4066 journal as a set of "(attrname, attrval)" pairs. The "attrname" is
4067 the field name (a string).
4068 The "attrval" is the field value (a binary blob, often but not
4070 always a string). Please note that "attrval" is a byte array, not
4071 a \0-terminated C string.
4072 The length of data may be truncated to the data threshold (see:
4074 "$g->journal_set_data_threshold",
4075 "$g->journal_get_data_threshold").
4076 If you set the data threshold to unlimited (0) then this call can
4078 read a journal entry of any size, ie. it is not limited by the
4079 libguestfs protocol.
4080 This function depends on the feature "journal". See also
4082 "$g->feature-available".
4083 $threshold = $g->journal_get_data_threshold ();
4085 Get the current data threshold for reading journal entries. This
4086 is a hint to the journal that it may truncate data fields to this
4087 size when reading them (note also that it may not truncate them).
4088 If this returns 0, then the threshold is unlimited.
4089 See also "$g->journal_set_data_threshold".
4091 This function depends on the feature "journal". See also
4093 "$g->feature-available".
4094 $usec = $g->journal_get_realtime_usec ();
4096 Get the realtime (wallclock) timestamp of the current journal
4097 entry.
4098 This function depends on the feature "journal". See also
4100 "$g->feature-available".
4101 $more = $g->journal_next ();
4103 Move to the next journal entry. You have to call this at least
4104 once after opening the handle before you are able to read data.
4105 The returned boolean tells you if there are any more journal
4107 records to read. "true" means you can read the next record (eg.
4108 using "$g->journal_get"), and "false" means you have reached the
4109 end of the journal.
4110 This function depends on the feature "journal". See also
4112 "$g->feature-available".
4113 $g->journal_open ($directory);
4115 Open the systemd journal located in directory. Any previously
4116 opened journal handle is closed.
4117 The contents of the journal can be read using "$g->journal_next"
4119 and "$g->journal_get".
4120 After you have finished using the journal, you should close the
4122 handle by calling "$g->journal_close".
4123 This function depends on the feature "journal". See also
4125 "$g->feature-available".
4126 $g->journal_set_data_threshold ($threshold);
4128 Set the data threshold for reading journal entries. This is a hint
4129 to the journal that it may truncate data fields to this size when
4130 reading them (note also that it may not truncate them). If you set
4131 this to 0, then the threshold is unlimited.
4132 See also "$g->journal_get_data_threshold".
4134 This function depends on the feature "journal". See also
4136 "$g->feature-available".
4137 $rskip = $g->journal_skip ($skip);
4139 Skip forwards ("skip X 0") or backwards ("skip < 0") in the
4140 journal.
4141 The number of entries actually skipped is returned (note
4143 "rskip X 0"). If this is not the same as the absolute value of the
4144 skip parameter ("|skip|") you passed in then it means you have
4145 reached the end or the start of the journal.
4146 This function depends on the feature "journal". See also
4148 "$g->feature-available".
4149 $g->kill_subprocess ();
4151 This kills the hypervisor.
4152 Do not call this. See: "$g->shutdown" instead.
4154 This function is deprecated. In new code, use the "shutdown" call
4156 instead.
4157 Deprecated functions will not be removed from the API, but the fact
4159 that they are deprecated indicates that there are problems with
4160 correct use of these functions.
4161 $g->launch ();
4163 You should call this after configuring the handle (eg. adding
4164 drives) but before performing any actions.
4165 Do not call "$g->launch" twice on the same handle. Although it
4167 will not give an error (for historical reasons), the precise
4168 behaviour when you do this is not well defined. Handles are very
4169 cheap to create, so create a new one for each launch.
4170 $g->lchown ($owner, $group, $path);
4172 Change the file owner to "owner" and group to "group". This is
4173 like "$g->chown" but if "path" is a symlink then the link itself is
4174 changed, not the target.
4175 Only numeric uid and gid are supported. If you want to use names,
4177 you will need to locate and parse the password file yourself
4178 (Augeas support makes this relatively easy).
4179 $g->ldmtool_create_all ();
4181 This function scans all block devices looking for Windows dynamic
4182 disk volumes and partitions, and creates devices for any that were
4183 found.
4184 Call "$g->list_ldm_volumes" and "$g->list_ldm_partitions" to return
4186 all devices.
4187 Note that you don't normally need to call this explicitly, since it
4189 is done automatically at "$g->launch" time. However you might want
4190 to call this function if you have hotplugged disks or have just
4191 created a Windows dynamic disk.
4192 This function depends on the feature "ldm". See also
4194 "$g->feature-available".
4195 @disks = $g->ldmtool_diskgroup_disks ($diskgroup);
4197 Return the disks in a Windows dynamic disk group. The "diskgroup"
4198 parameter should be the GUID of a disk group, one element from the
4199 list returned by "$g->ldmtool_scan".
4200 This function depends on the feature "ldm". See also
4202 "$g->feature-available".
4203 $name = $g->ldmtool_diskgroup_name ($diskgroup);
4205 Return the name of a Windows dynamic disk group. The "diskgroup"
4206 parameter should be the GUID of a disk group, one element from the
4207 list returned by "$g->ldmtool_scan".
4208 This function depends on the feature "ldm". See also
4210 "$g->feature-available".
4211 @volumes = $g->ldmtool_diskgroup_volumes ($diskgroup);
4213 Return the volumes in a Windows dynamic disk group. The
4214 "diskgroup" parameter should be the GUID of a disk group, one
4215 element from the list returned by "$g->ldmtool_scan".
4216 This function depends on the feature "ldm". See also
4218 "$g->feature-available".
4219 $g->ldmtool_remove_all ();
4221 This is essentially the opposite of "$g->ldmtool_create_all". It
4222 removes the device mapper mappings for all Windows dynamic disk
4223 volumes
4224 This function depends on the feature "ldm". See also
4226 "$g->feature-available".
4227 @guids = $g->ldmtool_scan ();
4229 This function scans for Windows dynamic disks. It returns a list
4230 of identifiers (GUIDs) for all disk groups that were found. These
4231 identifiers can be passed to other "$g->ldmtool_*" functions.
4232 This function scans all block devices. To scan a subset of block
4234 devices, call "$g->ldmtool_scan_devices" instead.
4235 This function depends on the feature "ldm". See also
4237 "$g->feature-available".
4238 @guids = $g->ldmtool_scan_devices (\@devices);
4240 This function scans for Windows dynamic disks. It returns a list
4241 of identifiers (GUIDs) for all disk groups that were found. These
4242 identifiers can be passed to other "$g->ldmtool_*" functions.
4243 The parameter "devices" is a list of block devices which are
4245 scanned. If this list is empty, all block devices are scanned.
4246 This function depends on the feature "ldm". See also
4248 "$g->feature-available".
4249 $hint = $g->ldmtool_volume_hint ($diskgroup, $volume);
4251 Return the hint field of the volume named "volume" in the disk
4252 group with GUID "diskgroup". This may not be defined, in which
4253 case the empty string is returned. The hint field is often, though
4254 not always, the name of a Windows drive, eg. "E:".
4255 This function depends on the feature "ldm". See also
4257 "$g->feature-available".
4258 @partitions = $g->ldmtool_volume_partitions ($diskgroup, $volume);
4260 Return the list of partitions in the volume named "volume" in the
4261 disk group with GUID "diskgroup".
4262 This function depends on the feature "ldm". See also
4264 "$g->feature-available".
4265 $voltype = $g->ldmtool_volume_type ($diskgroup, $volume);
4267 Return the type of the volume named "volume" in the disk group with
4268 GUID "diskgroup".
4269 Possible volume types that can be returned here include: "simple",
4271 "spanned", "striped", "mirrored", "raid5". Other types may also be
4272 returned.
4273 This function depends on the feature "ldm". See also
4275 "$g->feature-available".
4276 $xattr = $g->lgetxattr ($path, $name);
4278 Get a single extended attribute from file "path" named "name". If
4279 "path" is a symlink, then this call returns an extended attribute
4280 from the symlink.
4281 Normally it is better to get all extended attributes from a file in
4283 one go by calling "$g->getxattrs". However some Linux filesystem
4284 implementations are buggy and do not provide a way to list out
4285 attributes. For these filesystems (notably ntfs-3g) you have to
4286 know the names of the extended attributes you want in advance and
4287 call this function.
4288 Extended attribute values are blobs of binary data. If there is no
4290 extended attribute named "name", this returns an error.
4291 See also: "$g->lgetxattrs", "$g->getxattr", attr(5).
4293 This function depends on the feature "linuxxattrs". See also
4295 "$g->feature-available".
4296 @xattrs = $g->lgetxattrs ($path);
4298 This is the same as "$g->getxattrs", but if "path" is a symbolic
4299 link, then it returns the extended attributes of the link itself.
4300 This function depends on the feature "linuxxattrs". See also
4302 "$g->feature-available".
4303 @mounttags = $g->list_9p ();
4305 List all 9p filesystems attached to the guest. A list of mount
4306 tags is returned.
4307 @devices = $g->list_devices ();
4309 List all the block devices.
4310 The full block device names are returned, eg. /dev/sda.
4312 See also "$g->list_filesystems".
4314 %labels = $g->list_disk_labels ();
4316 If you add drives using the optional "label" parameter of
4317 "$g->add_drive_opts", you can use this call to map between disk
4318 labels, and raw block device and partition names (like /dev/sda and
4319 /dev/sda1).
4320 This returns a hashtable, where keys are the disk labels (without
4322 the /dev/disk/guestfs prefix), and the values are the full raw
4323 block device and partition names (eg. /dev/sda and /dev/sda1).
4324 @devices = $g->list_dm_devices ();
4326 List all device mapper devices.
4327 The returned list contains /dev/mapper/* devices, eg. ones created
4329 by a previous call to "$g->luks_open".
4330 Device mapper devices which correspond to logical volumes are not
4332 returned in this list. Call "$g->lvs" if you want to list logical
4333 volumes.
4334 %fses = $g->list_filesystems ();
4336 This inspection command looks for filesystems on partitions, block
4337 devices and logical volumes, returning a list of "mountables"
4338 containing filesystems and their type.
4339 The return value is a hash, where the keys are the devices
4341 containing filesystems, and the values are the filesystem types.
4342 For example:
4343 "/dev/sda1" => "ntfs"
4345 "/dev/sda2" => "ext2"
4346 "/dev/vg_guest/lv_root" => "ext4"
4347 "/dev/vg_guest/lv_swap" => "swap"
4348 The key is not necessarily a block device. It may also be an opaque
4350 XmountableX string which can be passed to "$g->mount".
4351 The value can have the special value "unknown", meaning the content
4353 of the device is undetermined or empty. "swap" means a Linux swap
4354 partition.
4355 In libguestfs X 1.36 this command ran other libguestfs commands,
4357 which might have included "$g->mount" and "$g->umount", and
4358 therefore you had to use this soon after launch and only when
4359 nothing else was mounted. This restriction is removed in
4360 libguestfs X 1.38.
4361 Not all of the filesystems returned will be mountable. In
4363 particular, swap partitions are returned in the list. Also this
4364 command does not check that each filesystem found is valid and
4365 mountable, and some filesystems might be mountable but require
4366 special options. Filesystems may not all belong to a single
4367 logical operating system (use "$g->inspect_os" to look for OSes).
4368 @devices = $g->list_ldm_partitions ();
4370 This function returns all Windows dynamic disk partitions that were
4371 found at launch time. It returns a list of device names.
4372 This function depends on the feature "ldm". See also
4374 "$g->feature-available".
4375 @devices = $g->list_ldm_volumes ();
4377 This function returns all Windows dynamic disk volumes that were
4378 found at launch time. It returns a list of device names.
4379 This function depends on the feature "ldm". See also
4381 "$g->feature-available".
4382 @devices = $g->list_md_devices ();
4384 List all Linux md devices.
4385 @partitions = $g->list_partitions ();
4387 List all the partitions detected on all block devices.
4388 The full partition device names are returned, eg. /dev/sda1
4390 This does not return logical volumes. For that you will need to
4392 call "$g->lvs".
4393 See also "$g->list_filesystems".
4395 $listing = $g->ll ($directory);
4397 List the files in directory (relative to the root directory, there
4398 is no cwd) in the format of "ls -la".
4399 This command is mostly useful for interactive sessions. It is not
4401 intended that you try to parse the output string.
4402 $listing = $g->llz ($directory);
4404 List the files in directory in the format of "ls -laZ".
4405 This command is mostly useful for interactive sessions. It is not
4407 intended that you try to parse the output string.
4408 This function is deprecated. In new code, use the "lgetxattrs"
4410 call instead.
4411 Deprecated functions will not be removed from the API, but the fact
4413 that they are deprecated indicates that there are problems with
4414 correct use of these functions.
4415 $g->ln ($target, $linkname);
4417 This command creates a hard link.
4418 $g->ln_f ($target, $linkname);
4420 This command creates a hard link, removing the link "linkname" if
4421 it exists already.
4422 $g->ln_s ($target, $linkname);
4424 This command creates a symbolic link using the "ln -s" command.
4425 $g->ln_sf ($target, $linkname);
4427 This command creates a symbolic link using the "ln -sf" command,
4428 The -f option removes the link ("linkname") if it exists already.
4429 $g->lremovexattr ($xattr, $path);
4431 This is the same as "$g->removexattr", but if "path" is a symbolic
4432 link, then it removes an extended attribute of the link itself.
4433 This function depends on the feature "linuxxattrs". See also
4435 "$g->feature-available".
4436 @listing = $g->ls ($directory);
4438 List the files in directory (relative to the root directory, there
4439 is no cwd). The "." and ".." entries are not returned, but hidden
4440 files are shown.
4441 $g->ls0 ($dir, $filenames);
4443 This specialized command is used to get a listing of the filenames
4444 in the directory "dir". The list of filenames is written to the
4445 local file filenames (on the host).
4446 In the output file, the filenames are separated by "\0" characters.
4448 "." and ".." are not returned. The filenames are not sorted.
4450 $g->lsetxattr ($xattr, $val, $vallen, $path);
4452 This is the same as "$g->setxattr", but if "path" is a symbolic
4453 link, then it sets an extended attribute of the link itself.
4454 This function depends on the feature "linuxxattrs". See also
4456 "$g->feature-available".
4457 %statbuf = $g->lstat ($path);
4459 Returns file information for the given "path".
4460 This is the same as "$g->stat" except that if "path" is a symbolic
4462 link, then the link is stat-ed, not the file it refers to.
4463 This is the same as the lstat(2) system call.
4465 This function is deprecated. In new code, use the "lstatns" call
4467 instead.
4468 Deprecated functions will not be removed from the API, but the fact
4470 that they are deprecated indicates that there are problems with
4471 correct use of these functions.
4472 @statbufs = $g->lstatlist ($path, \@names);
4474 This call allows you to perform the "$g->lstat" operation on
4475 multiple files, where all files are in the directory "path".
4476 "names" is the list of files from this directory.
4477 On return you get a list of stat structs, with a one-to-one
4479 correspondence to the "names" list. If any name did not exist or
4480 could not be lstat'd, then the "st_ino" field of that structure is
4481 set to "-1".
4482 This call is intended for programs that want to efficiently list a
4484 directory contents without making many round-trips. See also
4485 "$g->lxattrlist" for a similarly efficient call for getting
4486 extended attributes.
4487 This function is deprecated. In new code, use the "lstatnslist"
4489 call instead.
4490 Deprecated functions will not be removed from the API, but the fact
4492 that they are deprecated indicates that there are problems with
4493 correct use of these functions.
4494 %statbuf = $g->lstatns ($path);
4496 Returns file information for the given "path".
4497 This is the same as "$g->statns" except that if "path" is a
4499 symbolic link, then the link is stat-ed, not the file it refers to.
4500 This is the same as the lstat(2) system call.
4502 @statbufs = $g->lstatnslist ($path, \@names);
4504 This call allows you to perform the "$g->lstatns" operation on
4505 multiple files, where all files are in the directory "path".
4506 "names" is the list of files from this directory.
4507 On return you get a list of stat structs, with a one-to-one
4509 correspondence to the "names" list. If any name did not exist or
4510 could not be lstat'd, then the "st_ino" field of that structure is
4511 set to "-1".
4512 This call is intended for programs that want to efficiently list a
4514 directory contents without making many round-trips. See also
4515 "$g->lxattrlist" for a similarly efficient call for getting
4516 extended attributes.
4517 $g->luks_add_key ($device, $key, $newkey, $keyslot);
4519 This command adds a new key on LUKS device "device". "key" is any
4520 existing key, and is used to access the device. "newkey" is the
4521 new key to add. "keyslot" is the key slot that will be replaced.
4522 Note that if "keyslot" already contains a key, then this command
4524 will fail. You have to use "$g->luks_kill_slot" first to remove
4525 that key.
4526 This function depends on the feature "luks". See also
4528 "$g->feature-available".
4529 $g->luks_close ($device);
4531 This closes a LUKS device that was created earlier by
4532 "$g->luks_open" or "$g->luks_open_ro". The "device" parameter must
4533 be the name of the LUKS mapping device (ie. /dev/mapper/mapname)
4534 and not the name of the underlying block device.
4535 This function depends on the feature "luks". See also
4537 "$g->feature-available".
4538 This function is deprecated. In new code, use the
4540 "cryptsetup_close" call instead.
4541 Deprecated functions will not be removed from the API, but the fact
4543 that they are deprecated indicates that there are problems with
4544 correct use of these functions.
4545 $g->luks_format ($device, $key, $keyslot);
4547 This command erases existing data on "device" and formats the
4548 device as a LUKS encrypted device. "key" is the initial key, which
4549 is added to key slot "keyslot". (LUKS supports 8 key slots,
4550 numbered 0-7).
4551 This function depends on the feature "luks". See also
4553 "$g->feature-available".
4554 $g->luks_format_cipher ($device, $key, $keyslot, $cipher);
4556 This command is the same as "$g->luks_format" but it also allows
4557 you to set the "cipher" used.
4558 This function depends on the feature "luks". See also
4560 "$g->feature-available".
4561 $g->luks_kill_slot ($device, $key, $keyslot);
4563 This command deletes the key in key slot "keyslot" from the
4564 encrypted LUKS device "device". "key" must be one of the other
4565 keys.
4566 This function depends on the feature "luks". See also
4568 "$g->feature-available".
4569 $g->luks_open ($device, $key, $mapname);
4571 This command opens a block device which has been encrypted
4572 according to the Linux Unified Key Setup (LUKS) standard.
4573 "device" is the encrypted block device or partition.
4575 The caller must supply one of the keys associated with the LUKS
4577 block device, in the "key" parameter.
4578 This creates a new block device called /dev/mapper/mapname. Reads
4580 and writes to this block device are decrypted from and encrypted to
4581 the underlying "device" respectively.
4582 If this block device contains LVM volume groups, then calling
4584 "$g->lvm_scan" with the "activate" parameter "true" will make them
4585 visible.
4586 Use "$g->list_dm_devices" to list all device mapper devices.
4588 This function depends on the feature "luks". See also
4590 "$g->feature-available".
4591 This function is deprecated. In new code, use the
4593 "cryptsetup_open" call instead.
4594 Deprecated functions will not be removed from the API, but the fact
4596 that they are deprecated indicates that there are problems with
4597 correct use of these functions.
4598 $g->luks_open_ro ($device, $key, $mapname);
4600 This is the same as "$g->luks_open" except that a read-only mapping
4601 is created.
4602 This function depends on the feature "luks". See also
4604 "$g->feature-available".
4605 This function is deprecated. In new code, use the
4607 "cryptsetup_open" call instead.
4608 Deprecated functions will not be removed from the API, but the fact
4610 that they are deprecated indicates that there are problems with
4611 correct use of these functions.
4612 $uuid = $g->luks_uuid ($device);
4614 This returns the UUID of the LUKS device "device".
4615 This function depends on the feature "luks". See also
4617 "$g->feature-available".
4618 $g->lvcreate ($logvol, $volgroup, $mbytes);
4620 This creates an LVM logical volume called "logvol" on the volume
4621 group "volgroup", with "size" megabytes.
4622 This function depends on the feature "lvm2". See also
4624 "$g->feature-available".
4625 $g->lvcreate_free ($logvol, $volgroup, $percent);
4627 Create an LVM logical volume called /dev/volgroup/logvol, using
4628 approximately "percent" % of the free space remaining in the volume
4629 group. Most usefully, when "percent" is 100 this will create the
4630 largest possible LV.
4631 This function depends on the feature "lvm2". See also
4633 "$g->feature-available".
4634 $lv = $g->lvm_canonical_lv_name ($lvname);
4636 This converts alternative naming schemes for LVs that you might
4637 find to the canonical name. For example, /dev/mapper/VG-LV is
4638 converted to /dev/VG/LV.
4639 This command returns an error if the "lvname" parameter does not
4641 refer to a logical volume. In this case errno will be set to
4642 "EINVAL".
4643 See also "$g->is_lv", "$g->canonical_device_name".
4645 $g->lvm_clear_filter ();
4647 This undoes the effect of "$g->lvm_set_filter". LVM will be able
4648 to see every block device.
4649 This command also clears the LVM cache and performs a volume group
4651 scan.
4652 $g->lvm_remove_all ();
4654 This command removes all LVM logical volumes, volume groups and
4655 physical volumes.
4656 This function depends on the feature "lvm2". See also
4658 "$g->feature-available".
4659 $g->lvm_scan ($activate);
4661 This scans all block devices and rebuilds the list of LVM physical
4662 volumes, volume groups and logical volumes.
4663 If the "activate" parameter is "true" then newly found volume
4665 groups and logical volumes are activated, meaning the LV /dev/VG/LV
4666 devices become visible.
4667 When a libguestfs handle is launched it scans for existing devices,
4669 so you do not normally need to use this API. However it is useful
4670 when you have added a new device or deleted an existing device
4671 (such as when the "$g->luks_open" API is used).
4672 $g->lvm_set_filter (\@devices);
4674 This sets the LVM device filter so that LVM will only be able to
4675 "see" the block devices in the list "devices", and will ignore all
4676 other attached block devices.
4677 Where disk image(s) contain duplicate PVs or VGs, this command is
4679 useful to get LVM to ignore the duplicates, otherwise LVM can get
4680 confused. Note also there are two types of duplication possible:
4681 either cloned PVs/VGs which have identical UUIDs; or VGs that are
4682 not cloned but just happen to have the same name. In normal
4683 operation you cannot create this situation, but you can do it
4684 outside LVM, eg. by cloning disk images or by bit twiddling inside
4685 the LVM metadata.
4686 This command also clears the LVM cache and performs a volume group
4688 scan.
4689 You can filter whole block devices or individual partitions.
4691 You cannot use this if any VG is currently in use (eg. contains a
4693 mounted filesystem), even if you are not filtering out that VG.
4694 This function depends on the feature "lvm2". See also
4696 "$g->feature-available".
4697 $g->lvremove ($device);
4699 Remove an LVM logical volume "device", where "device" is the path
4700 to the LV, such as /dev/VG/LV.
4701 You can also remove all LVs in a volume group by specifying the VG
4703 name, /dev/VG.
4704 This function depends on the feature "lvm2". See also
4706 "$g->feature-available".
4707 $g->lvrename ($logvol, $newlogvol);
4709 Rename a logical volume "logvol" with the new name "newlogvol".
4710 $g->lvresize ($device, $mbytes);
4712 This resizes (expands or shrinks) an existing LVM logical volume to
4713 "mbytes". When reducing, data in the reduced part is lost.
4714 This function depends on the feature "lvm2". See also
4716 "$g->feature-available".
4717 $g->lvresize_free ($lv, $percent);
4719 This expands an existing logical volume "lv" so that it fills "pc"
4720 % of the remaining free space in the volume group. Commonly you
4721 would call this with pc = 100 which expands the logical volume as
4722 much as possible, using all remaining free space in the volume
4723 group.
4724 This function depends on the feature "lvm2". See also
4726 "$g->feature-available".
4727 @logvols = $g->lvs ();
4729 List all the logical volumes detected. This is the equivalent of
4730 the lvs(8) command.
4731 This returns a list of the logical volume device names (eg.
4733 /dev/VolGroup00/LogVol00).
4734 See also "$g->lvs_full", "$g->list_filesystems".
4736 This function depends on the feature "lvm2". See also
4738 "$g->feature-available".
4739 @logvols = $g->lvs_full ();
4741 List all the logical volumes detected. This is the equivalent of
4742 the lvs(8) command. The "full" version includes all fields.
4743 This function depends on the feature "lvm2". See also
4745 "$g->feature-available".
4746 $uuid = $g->lvuuid ($device);
4748 This command returns the UUID of the LVM LV "device".
4749 @xattrs = $g->lxattrlist ($path, \@names);
4751 This call allows you to get the extended attributes of multiple
4752 files, where all files are in the directory "path". "names" is the
4753 list of files from this directory.
4754 On return you get a flat list of xattr structs which must be
4756 interpreted sequentially. The first xattr struct always has a
4757 zero-length "attrname". "attrval" in this struct is zero-length to
4758 indicate there was an error doing "$g->lgetxattr" for this file, or
4759 is a C string which is a decimal number (the number of following
4760 attributes for this file, which could be "0"). Then after the
4761 first xattr struct are the zero or more attributes for the first
4762 named file. This repeats for the second and subsequent files.
4763 This call is intended for programs that want to efficiently list a
4765 directory contents without making many round-trips. See also
4766 "$g->lstatlist" for a similarly efficient call for getting standard
4767 stats.
4768 This function depends on the feature "linuxxattrs". See also
4770 "$g->feature-available".
4771 $disks = $g->max_disks ();
4773 Return the maximum number of disks that may be added to a handle
4774 (eg. by "$g->add_drive_opts" and similar calls).
4775 This function was added in libguestfs 1.19.7. In previous versions
4777 of libguestfs the limit was 25.
4778 See "MAXIMUM NUMBER OF DISKS" in guestfs(3) for additional
4780 information on this topic.
4781 $g->md_create ($name, \@devices [, missingbitmap => $missingbitmap] [,
4783 nrdevices => $nrdevices] [, spare => $spare] [, chunk => $chunk] [,
4784 level => $level]);
4785 Create a Linux md (RAID) device named "name" on the devices in the
4786 list "devices".
4787 The optional parameters are:
4789 "missingbitmap"
4791 A bitmap of missing devices. If a bit is set it means that a
4792 missing device is added to the array. The least significant
4793 bit corresponds to the first device in the array.
4794 As examples:
4796 If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
4798 resulting array would be "[<missing>, "/dev/sda"]".
4799 If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
4801 resulting array would be "["/dev/sda", <missing>]".
4802 This defaults to 0 (no missing devices).
4804 The length of "devices" + the number of bits set in
4806 "missingbitmap" must equal "nrdevices" + "spare".
4807 "nrdevices"
4809 The number of active RAID devices.
4810 If not set, this defaults to the length of "devices" plus the
4812 number of bits set in "missingbitmap".
4813 "spare"
4815 The number of spare devices.
4816 If not set, this defaults to 0.
4818 "chunk"
4820 The chunk size in bytes.
4821 "level"
4823 The RAID level, which can be one of: "linear", "raid0", 0,
4824 "stripe", "raid1", 1, "mirror", "raid4", 4, "raid5", 5,
4825 "raid6", 6, "raid10", 10. Some of these are synonymous, and
4826 more levels may be added in future.
4827 If not set, this defaults to "raid1".
4829 This function depends on the feature "mdadm". See also
4831 "$g->feature-available".
4832 %info = $g->md_detail ($md);
4834 This command exposes the output of "mdadm -DY <md>". The following
4835 fields are usually present in the returned hash. Other fields may
4836 also be present.
4837 "level"
4839 The raid level of the MD device.
4840 "devices"
4842 The number of underlying devices in the MD device.
4843 "metadata"
4845 The metadata version used.
4846 "uuid"
4848 The UUID of the MD device.
4849 "name"
4851 The name of the MD device.
4852 This function depends on the feature "mdadm". See also
4854 "$g->feature-available".
4855 @devices = $g->md_stat ($md);
4857 This call returns a list of the underlying devices which make up
4858 the single software RAID array device "md".
4859 To get a list of software RAID devices, call "$g->list_md_devices".
4861 Each structure returned corresponds to one device along with
4863 additional status information:
4864 "mdstat_device"
4866 The name of the underlying device.
4867 "mdstat_index"
4869 The index of this device within the array.
4870 "mdstat_flags"
4872 Flags associated with this device. This is a string containing
4873 (in no specific order) zero or more of the following flags:
4874 "W" write-mostly
4876 "F" device is faulty
4878 "S" device is a RAID spare
4880 "R" replacement
4882 This function depends on the feature "mdadm". See also
4884 "$g->feature-available".
4885 $g->md_stop ($md);
4887 This command deactivates the MD array named "md". The device is
4888 stopped, but it is not destroyed or zeroed.
4889 This function depends on the feature "mdadm". See also
4891 "$g->feature-available".
4892 $g->mkdir ($path);
4894 Create a directory named "path".
4895 $g->mkdir_mode ($path, $mode);
4897 This command creates a directory, setting the initial permissions
4898 of the directory to "mode".
4899 For common Linux filesystems, the actual mode which is set will be
4901 "mode & ~umask & 01777". Non-native-Linux filesystems may
4902 interpret the mode in other ways.
4903 See also "$g->mkdir", "$g->umask"
4905 $g->mkdir_p ($path);
4907 Create a directory named "path", creating any parent directories as
4908 necessary. This is like the "mkdir -p" shell command.
4909 $dir = $g->mkdtemp ($tmpl);
4911 This command creates a temporary directory. The "tmpl" parameter
4912 should be a full pathname for the temporary directory name with the
4913 final six characters being "XXXXXX".
4914 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the
4916 second one being suitable for Windows filesystems.
4917 The name of the temporary directory that was created is returned.
4919 The temporary directory is created with mode 0700 and is owned by
4921 root.
4922 The caller is responsible for deleting the temporary directory and
4924 its contents after use.
4925 See also: mkdtemp(3)
4927 $g->mke2fs ($device [, blockscount => $blockscount] [, blocksize =>
4929 $blocksize] [, fragsize => $fragsize] [, blockspergroup =>
4930 $blockspergroup] [, numberofgroups => $numberofgroups] [, bytesperinode
4931 => $bytesperinode] [, inodesize => $inodesize] [, journalsize =>
4932 $journalsize] [, numberofinodes => $numberofinodes] [, stridesize =>
4933 $stridesize] [, stripewidth => $stripewidth] [, maxonlineresize =>
4934 $maxonlineresize] [, reservedblockspercentage =>
4935 $reservedblockspercentage] [, mmpupdateinterval => $mmpupdateinterval]
4936 [, journaldevice => $journaldevice] [, label => $label] [,
4937 lastmounteddir => $lastmounteddir] [, creatoros => $creatoros] [,
4938 fstype => $fstype] [, usagetype => $usagetype] [, uuid => $uuid] [,
4939 forcecreate => $forcecreate] [, writesbandgrouponly =>
4940 $writesbandgrouponly] [, lazyitableinit => $lazyitableinit] [,
4941 lazyjournalinit => $lazyjournalinit] [, testfs => $testfs] [, discard
4942 => $discard] [, quotatype => $quotatype] [, extent => $extent] [,
4943 filetype => $filetype] [, flexbg => $flexbg] [, hasjournal =>
4944 $hasjournal] [, journaldev => $journaldev] [, largefile => $largefile]
4945 [, quota => $quota] [, resizeinode => $resizeinode] [, sparsesuper =>
4946 $sparsesuper] [, uninitbg => $uninitbg]);
4947 "mke2fs" is used to create an ext2, ext3, or ext4 filesystem on
4948 "device".
4949 The optional "blockscount" is the size of the filesystem in blocks.
4951 If omitted it defaults to the size of "device". Note if the
4952 filesystem is too small to contain a journal, "mke2fs" will
4953 silently create an ext2 filesystem instead.
4954 $g->mke2fs_J ($fstype, $blocksize, $device, $journal);
4956 This creates an ext2/3/4 filesystem on "device" with an external
4957 journal on "journal". It is equivalent to the command:
4958 mke2fs -t fstype -b blocksize -J device=<journal> <device>
4960 See also "$g->mke2journal".
4962 This function is deprecated. In new code, use the "mke2fs" call
4964 instead.
4965 Deprecated functions will not be removed from the API, but the fact
4967 that they are deprecated indicates that there are problems with
4968 correct use of these functions.
4969 $g->mke2fs_JL ($fstype, $blocksize, $device, $label);
4971 This creates an ext2/3/4 filesystem on "device" with an external
4972 journal on the journal labeled "label".
4973 See also "$g->mke2journal_L".
4975 This function is deprecated. In new code, use the "mke2fs" call
4977 instead.
4978 Deprecated functions will not be removed from the API, but the fact
4980 that they are deprecated indicates that there are problems with
4981 correct use of these functions.
4982 $g->mke2fs_JU ($fstype, $blocksize, $device, $uuid);
4984 This creates an ext2/3/4 filesystem on "device" with an external
4985 journal on the journal with UUID "uuid".
4986 See also "$g->mke2journal_U".
4988 This function depends on the feature "linuxfsuuid". See also
4990 "$g->feature-available".
4991 This function is deprecated. In new code, use the "mke2fs" call
4993 instead.
4994 Deprecated functions will not be removed from the API, but the fact
4996 that they are deprecated indicates that there are problems with
4997 correct use of these functions.
4998 $g->mke2journal ($blocksize, $device);
5000 This creates an ext2 external journal on "device". It is
5001 equivalent to the command:
5002 mke2fs -O journal_dev -b blocksize device
5004 This function is deprecated. In new code, use the "mke2fs" call
5006 instead.
5007 Deprecated functions will not be removed from the API, but the fact
5009 that they are deprecated indicates that there are problems with
5010 correct use of these functions.
5011 $g->mke2journal_L ($blocksize, $label, $device);
5013 This creates an ext2 external journal on "device" with label
5014 "label".
5015 This function is deprecated. In new code, use the "mke2fs" call
5017 instead.
5018 Deprecated functions will not be removed from the API, but the fact
5020 that they are deprecated indicates that there are problems with
5021 correct use of these functions.
5022 $g->mke2journal_U ($blocksize, $uuid, $device);
5024 This creates an ext2 external journal on "device" with UUID "uuid".
5025 This function depends on the feature "linuxfsuuid". See also
5027 "$g->feature-available".
5028 This function is deprecated. In new code, use the "mke2fs" call
5030 instead.
5031 Deprecated functions will not be removed from the API, but the fact
5033 that they are deprecated indicates that there are problems with
5034 correct use of these functions.
5035 $g->mkfifo ($mode, $path);
5037 This call creates a FIFO (named pipe) called "path" with mode
5038 "mode". It is just a convenient wrapper around "$g->mknod".
5039 Unlike with "$g->mknod", "mode" must contain only permissions bits.
5041 The mode actually set is affected by the umask.
5043 This function depends on the feature "mknod". See also
5045 "$g->feature-available".
5046 $g->mkfs ($fstype, $device [, blocksize => $blocksize] [, features =>
5048 $features] [, inode => $inode] [, sectorsize => $sectorsize] [, label
5049 => $label]);
5050 This function creates a filesystem on "device". The filesystem
5051 type is "fstype", for example "ext3".
5052 The optional arguments are:
5054 "blocksize"
5056 The filesystem block size. Supported block sizes depend on the
5057 filesystem type, but typically they are 1024, 2048 or 4096 for
5058 Linux ext2/3 filesystems.
5059 For VFAT and NTFS the "blocksize" parameter is treated as the
5061 requested cluster size.
5062 For UFS block sizes, please see mkfs.ufs(8).
5064 "features"
5066 This passes the -O parameter to the external mkfs program.
5067 For certain filesystem types, this allows extra filesystem
5069 features to be selected. See mke2fs(8) and mkfs.ufs(8) for
5070 more details.
5071 You cannot use this optional parameter with the "gfs" or "gfs2"
5073 filesystem type.
5074 "inode"
5076 This passes the -I parameter to the external mke2fs(8) program
5077 which sets the inode size (only for ext2/3/4 filesystems at
5078 present).
5079 "sectorsize"
5081 This passes the -S parameter to external mkfs.ufs(8) program,
5082 which sets sector size for ufs filesystem.
5083 $g->mkfs_opts ($fstype, $device [, blocksize => $blocksize] [, features
5085 => $features] [, inode => $inode] [, sectorsize => $sectorsize] [,
5086 label => $label]);
5087 This is an alias of "mkfs".
5088 $g->mkfs_b ($fstype, $blocksize, $device);
5090 This call is similar to "$g->mkfs", but it allows you to control
5091 the block size of the resulting filesystem. Supported block sizes
5092 depend on the filesystem type, but typically they are 1024, 2048 or
5093 4096 only.
5094 For VFAT and NTFS the "blocksize" parameter is treated as the
5096 requested cluster size.
5097 This function is deprecated. In new code, use the "mkfs" call
5099 instead.
5100 Deprecated functions will not be removed from the API, but the fact
5102 that they are deprecated indicates that there are problems with
5103 correct use of these functions.
5104 $g->mkfs_btrfs (\@devices [, allocstart => $allocstart] [, bytecount =>
5106 $bytecount] [, datatype => $datatype] [, leafsize => $leafsize] [,
5107 label => $label] [, metadata => $metadata] [, nodesize => $nodesize] [,
5108 sectorsize => $sectorsize]);
5109 Create a btrfs filesystem, allowing all configurables to be set.
5110 For more information on the optional arguments, see mkfs.btrfs(8).
5111 Since btrfs filesystems can span multiple devices, this takes a
5113 non-empty list of devices.
5114 To create general filesystems, use "$g->mkfs".
5116 This function depends on the feature "btrfs". See also
5118 "$g->feature-available".
5119 $g->mklost_and_found ($mountpoint);
5121 Make the "lost+found" directory, normally in the root directory of
5122 an ext2/3/4 filesystem. "mountpoint" is the directory under which
5123 we try to create the "lost+found" directory.
5124 $g->mkmountpoint ($exemptpath);
5126 "$g->mkmountpoint" and "$g->rmmountpoint" are specialized calls
5127 that can be used to create extra mountpoints before mounting the
5128 first filesystem.
5129 These calls are only necessary in some very limited circumstances,
5131 mainly the case where you want to mount a mix of unrelated and/or
5132 read-only filesystems together.
5133 For example, live CDs often contain a "Russian doll" nest of
5135 filesystems, an ISO outer layer, with a squashfs image inside, with
5136 an ext2/3 image inside that. You can unpack this as follows in
5137 guestfish:
5138 add-ro Fedora-11-i686-Live.iso
5140 run
5141 mkmountpoint /cd
5142 mkmountpoint /sqsh
5143 mkmountpoint /ext3fs
5144 mount /dev/sda /cd
5145 mount-loop /cd/LiveOS/squashfs.img /sqsh
5146 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
5147 The inner filesystem is now unpacked under the /ext3fs mountpoint.
5149 "$g->mkmountpoint" is not compatible with "$g->umount_all". You
5151 may get unexpected errors if you try to mix these calls. It is
5152 safest to manually unmount filesystems and remove mountpoints after
5153 use.
5154 "$g->umount_all" unmounts filesystems by sorting the paths longest
5156 first, so for this to work for manual mountpoints, you must ensure
5157 that the innermost mountpoints have the longest pathnames, as in
5158 the example code above.
5159 For more details see
5161 <https://bugzilla.redhat.com/show_bug.cgi?id=599503>
5162 Autosync [see "$g->set_autosync", this is set by default on
5164 handles] can cause "$g->umount_all" to be called when the handle is
5165 closed which can also trigger these issues.
5166 $g->mknod ($mode, $devmajor, $devminor, $path);
5168 This call creates block or character special devices, or named
5169 pipes (FIFOs).
5170 The "mode" parameter should be the mode, using the standard
5172 constants. "devmajor" and "devminor" are the device major and
5173 minor numbers, only used when creating block and character special
5174 devices.
5175 Note that, just like mknod(2), the mode must be bitwise OR'd with
5177 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just
5178 creates a regular file). These constants are available in the
5179 standard Linux header files, or you can use "$g->mknod_b",
5180 "$g->mknod_c" or "$g->mkfifo" which are wrappers around this
5181 command which bitwise OR in the appropriate constant for you.
5182 The mode actually set is affected by the umask.
5184 This function depends on the feature "mknod". See also
5186 "$g->feature-available".
5187 $g->mknod_b ($mode, $devmajor, $devminor, $path);
5189 This call creates a block device node called "path" with mode
5190 "mode" and device major/minor "devmajor" and "devminor". It is
5191 just a convenient wrapper around "$g->mknod".
5192 Unlike with "$g->mknod", "mode" must contain only permissions bits.
5194 The mode actually set is affected by the umask.
5196 This function depends on the feature "mknod". See also
5198 "$g->feature-available".
5199 $g->mknod_c ($mode, $devmajor, $devminor, $path);
5201 This call creates a char device node called "path" with mode "mode"
5202 and device major/minor "devmajor" and "devminor". It is just a
5203 convenient wrapper around "$g->mknod".
5204 Unlike with "$g->mknod", "mode" must contain only permissions bits.
5206 The mode actually set is affected by the umask.
5208 This function depends on the feature "mknod". See also
5210 "$g->feature-available".
5211 $g->mksquashfs ($path, $filename [, compress => $compress] [, excludes
5213 => $excludes]);
5214 Create a squashfs filesystem for the specified "path".
5215 The optional "compress" flag controls compression. If not given,
5217 then the output compressed using "gzip". Otherwise one of the
5218 following strings may be given to select the compression type of
5219 the squashfs: "gzip", "lzma", "lzo", "lz4", "xz".
5220 The other optional arguments are:
5222 "excludes"
5224 A list of wildcards. Files are excluded if they match any of
5225 the wildcards.
5226 Please note that this API may fail when used to compress
5228 directories with large files, such as the resulting squashfs will
5229 be over 3GB big.
5230 This function depends on the feature "squashfs". See also
5232 "$g->feature-available".
5233 $g->mkswap ($device [, label => $label] [, uuid => $uuid]);
5235 Create a Linux swap partition on "device".
5236 The option arguments "label" and "uuid" allow you to set the label
5238 and/or UUID of the new swap partition.
5239 $g->mkswap_opts ($device [, label => $label] [, uuid => $uuid]);
5241 This is an alias of "mkswap".
5242 $g->mkswap_L ($label, $device);
5244 Create a swap partition on "device" with label "label".
5245 Note that you cannot attach a swap label to a block device (eg.
5247 /dev/sda), just to a partition. This appears to be a limitation of
5248 the kernel or swap tools.
5249 This function is deprecated. In new code, use the "mkswap" call
5251 instead.
5252 Deprecated functions will not be removed from the API, but the fact
5254 that they are deprecated indicates that there are problems with
5255 correct use of these functions.
5256 $g->mkswap_U ($uuid, $device);
5258 Create a swap partition on "device" with UUID "uuid".
5259 This function depends on the feature "linuxfsuuid". See also
5261 "$g->feature-available".
5262 This function is deprecated. In new code, use the "mkswap" call
5264 instead.
5265 Deprecated functions will not be removed from the API, but the fact
5267 that they are deprecated indicates that there are problems with
5268 correct use of these functions.
5269 $g->mkswap_file ($path);
5271 Create a swap file.
5272 This command just writes a swap file signature to an existing file.
5274 To create the file itself, use something like "$g->fallocate".
5275 $path = $g->mktemp ($tmpl [, suffix => $suffix]);
5277 This command creates a temporary file. The "tmpl" parameter should
5278 be a full pathname for the temporary directory name with the final
5279 six characters being "XXXXXX".
5280 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the
5282 second one being suitable for Windows filesystems.
5283 The name of the temporary file that was created is returned.
5285 The temporary file is created with mode 0600 and is owned by root.
5287 The caller is responsible for deleting the temporary file after
5289 use.
5290 If the optional "suffix" parameter is given, then the suffix (eg.
5292 ".txt") is appended to the temporary name.
5293 See also: "$g->mkdtemp".
5295 $g->modprobe ($modulename);
5297 This loads a kernel module in the appliance.
5298 This function depends on the feature "linuxmodules". See also
5300 "$g->feature-available".
5301 $g->mount ($mountable, $mountpoint);
5303 Mount a guest disk at a position in the filesystem. Block devices
5304 are named /dev/sda, /dev/sdb and so on, as they were added to the
5305 guest. If those block devices contain partitions, they will have
5306 the usual names (eg. /dev/sda1). Also LVM /dev/VG/LV-style names
5307 can be used, or XmountableX strings returned by
5308 "$g->list_filesystems" or "$g->inspect_get_mountpoints".
5309 The rules are the same as for mount(2): A filesystem must first be
5311 mounted on / before others can be mounted. Other filesystems can
5312 only be mounted on directories which already exist.
5313 The mounted filesystem is writable, if we have sufficient
5315 permissions on the underlying device.
5316 Before libguestfs 1.13.16, this call implicitly added the options
5318 "sync" and "noatime". The "sync" option greatly slowed writes and
5319 caused many problems for users. If your program might need to work
5320 with older versions of libguestfs, use "$g->mount_options" instead
5321 (using an empty string for the first parameter if you don't want
5322 any options).
5323 $g->mount_9p ($mounttag, $mountpoint [, options => $options]);
5325 Mount the virtio-9p filesystem with the tag "mounttag" on the
5326 directory "mountpoint".
5327 If required, "trans=virtio" will be automatically added to the
5329 options. Any other options required can be passed in the optional
5330 "options" parameter.
5331 $g->mount_local ($localmountpoint [, readonly => $readonly] [, options
5333 => $options] [, cachetimeout => $cachetimeout] [, debugcalls =>
5334 $debugcalls]);
5335 This call exports the libguestfs-accessible filesystem to a local
5336 mountpoint (directory) called "localmountpoint". Ordinary reads
5337 and writes to files and directories under "localmountpoint" are
5338 redirected through libguestfs.
5339 If the optional "readonly" flag is set to true, then writes to the
5341 filesystem return error "EROFS".
5342 "options" is a comma-separated list of mount options. See
5344 guestmount(1) for some useful options.
5345 "cachetimeout" sets the timeout (in seconds) for cached directory
5347 entries. The default is 60 seconds. See guestmount(1) for further
5348 information.
5349 If "debugcalls" is set to true, then additional debugging
5351 information is generated for every FUSE call.
5352 When "$g->mount_local" returns, the filesystem is ready, but is not
5354 processing requests (access to it will block). You have to call
5355 "$g->mount_local_run" to run the main loop.
5356 See "MOUNT LOCAL" in guestfs(3) for full documentation.
5358 $g->mount_local_run ();
5360 Run the main loop which translates kernel calls to libguestfs
5361 calls.
5362 This should only be called after "$g->mount_local" returns
5364 successfully. The call will not return until the filesystem is
5365 unmounted.
5366 Note you must not make concurrent libguestfs calls on the same
5368 handle from another thread.
5369 You may call this from a different thread than the one which called
5371 "$g->mount_local", subject to the usual rules for threads and
5372 libguestfs (see "MULTIPLE HANDLES AND MULTIPLE THREADS" in
5373 guestfs(3)).
5374 See "MOUNT LOCAL" in guestfs(3) for full documentation.
5376 $g->mount_loop ($file, $mountpoint);
5378 This command lets you mount file (a filesystem image in a file) on
5379 a mount point. It is entirely equivalent to the command "mount -o
5380 loop file mountpoint".
5381 $g->mount_options ($options, $mountable, $mountpoint);
5383 This is the same as the "$g->mount" command, but it allows you to
5384 set the mount options as for the mount(8) -o flag.
5385 If the "options" parameter is an empty string, then no options are
5387 passed (all options default to whatever the filesystem uses).
5388 $g->mount_ro ($mountable, $mountpoint);
5390 This is the same as the "$g->mount" command, but it mounts the
5391 filesystem with the read-only (-o ro) flag.
5392 $g->mount_vfs ($options, $vfstype, $mountable, $mountpoint);
5394 This is the same as the "$g->mount" command, but it allows you to
5395 set both the mount options and the vfstype as for the mount(8) -o
5396 and -t flags.
5397 $device = $g->mountable_device ($mountable);
5399 Returns the device name of a mountable. In quite a lot of cases,
5400 the mountable is the device name.
5401 However this doesn't apply for btrfs subvolumes, where the
5403 mountable is a combination of both the device name and the
5404 subvolume path (see also "$g->mountable_subvolume" to extract the
5405 subvolume path of the mountable if any).
5406 $subvolume = $g->mountable_subvolume ($mountable);
5408 Returns the subvolume path of a mountable. Btrfs subvolumes
5409 mountables are a combination of both the device name and the
5410 subvolume path (see also "$g->mountable_device" to extract the
5411 device of the mountable).
5412 If the mountable does not represent a btrfs subvolume, then this
5414 function fails and the "errno" is set to "EINVAL".
5415 %mps = $g->mountpoints ();
5417 This call is similar to "$g->mounts". That call returns a list of
5418 devices. This one returns a hash table (map) of device name to
5419 directory where the device is mounted.
5420 @devices = $g->mounts ();
5422 This returns the list of currently mounted filesystems. It returns
5423 the list of devices (eg. /dev/sda1, /dev/VG/LV).
5424 Some internal mounts are not shown.
5426 See also: "$g->mountpoints"
5428 $g->mv ($src, $dest);
5430 This moves a file from "src" to "dest" where "dest" is either a
5431 destination filename or destination directory.
5432 See also: "$g->rename".
5434 $nrdisks = $g->nr_devices ();
5436 This returns the number of whole block devices that were added.
5437 This is the same as the number of devices that would be returned if
5438 you called "$g->list_devices".
5439 To find out the maximum number of devices that could be added, call
5441 "$g->max_disks".
5442 $status = $g->ntfs_3g_probe ($rw, $device);
5444 This command runs the ntfs-3g.probe(8) command which probes an NTFS
5445 "device" for mountability. (Not all NTFS volumes can be mounted
5446 read-write, and some cannot be mounted at all).
5447 "rw" is a boolean flag. Set it to true if you want to test if the
5449 volume can be mounted read-write. Set it to false if you want to
5450 test if the volume can be mounted read-only.
5451 The return value is an integer which 0 if the operation would
5453 succeed, or some non-zero value documented in the ntfs-3g.probe(8)
5454 manual page.
5455 This function depends on the feature "ntfs3g". See also
5457 "$g->feature-available".
5458 $g->ntfscat_i ($device, $inode, $filename);
5460 Download a file given its inode from a NTFS filesystem and save it
5461 as filename on the local machine.
5462 This allows to download some otherwise inaccessible files such as
5464 the ones within the $Extend folder.
5465 The filesystem from which to extract the file must be unmounted,
5467 otherwise the call will fail.
5468 $g->ntfsclone_in ($backupfile, $device);
5470 Restore the "backupfile" (from a previous call to
5471 "$g->ntfsclone_out") to "device", overwriting any existing contents
5472 of this device.
5473 This function depends on the feature "ntfs3g". See also
5475 "$g->feature-available".
5476 $g->ntfsclone_out ($device, $backupfile [, metadataonly =>
5478 $metadataonly] [, rescue => $rescue] [, ignorefscheck =>
5479 $ignorefscheck] [, preservetimestamps => $preservetimestamps] [, force
5480 => $force]);
5481 Stream the NTFS filesystem "device" to the local file "backupfile".
5482 The format used for the backup file is a special format used by the
5483 ntfsclone(8) tool.
5484 If the optional "metadataonly" flag is true, then only the metadata
5486 is saved, losing all the user data (this is useful for diagnosing
5487 some filesystem problems).
5488 The optional "rescue", "ignorefscheck", "preservetimestamps" and
5490 "force" flags have precise meanings detailed in the ntfsclone(8)
5491 man page.
5492 Use "$g->ntfsclone_in" to restore the file back to a libguestfs
5494 device.
5495 This function depends on the feature "ntfs3g". See also
5497 "$g->feature-available".
5498 $g->ntfsfix ($device [, clearbadsectors => $clearbadsectors]);
5500 This command repairs some fundamental NTFS inconsistencies, resets
5501 the NTFS journal file, and schedules an NTFS consistency check for
5502 the first boot into Windows.
5503 This is not an equivalent of Windows "chkdsk". It does not scan
5505 the filesystem for inconsistencies.
5506 The optional "clearbadsectors" flag clears the list of bad sectors.
5508 This is useful after cloning a disk with bad sectors to a new disk.
5509 This function depends on the feature "ntfs3g". See also
5511 "$g->feature-available".
5512 $g->ntfsresize ($device [, size => $size] [, force => $force]);
5514 This command resizes an NTFS filesystem, expanding or shrinking it
5515 to the size of the underlying device.
5516 The optional parameters are:
5518 "size"
5520 The new size (in bytes) of the filesystem. If omitted, the
5521 filesystem is resized to fit the container (eg. partition).
5522 "force"
5524 If this option is true, then force the resize of the filesystem
5525 even if the filesystem is marked as requiring a consistency
5526 check.
5527 After the resize operation, the filesystem is always marked as
5529 requiring a consistency check (for safety). You have to boot
5530 into Windows to perform this check and clear this condition.
5531 If you don't set the "force" option then it is not possible to
5532 call "$g->ntfsresize" multiple times on a single filesystem
5533 without booting into Windows between each resize.
5534 See also ntfsresize(8).
5536 This function depends on the feature "ntfsprogs". See also
5538 "$g->feature-available".
5539 $g->ntfsresize_opts ($device [, size => $size] [, force => $force]);
5541 This is an alias of "ntfsresize".
5542 $g->ntfsresize_size ($device, $size);
5544 This command is the same as "$g->ntfsresize" except that it allows
5545 you to specify the new size (in bytes) explicitly.
5546 This function depends on the feature "ntfsprogs". See also
5548 "$g->feature-available".
5549 This function is deprecated. In new code, use the "ntfsresize"
5551 call instead.
5552 Deprecated functions will not be removed from the API, but the fact
5554 that they are deprecated indicates that there are problems with
5555 correct use of these functions.
5556 $g->parse_environment ();
5558 Parse the programXs environment and set flags in the handle
5559 accordingly. For example if "LIBGUESTFS_DEBUG=1" then the
5560 XverboseX flag is set in the handle.
5561 Most programs do not need to call this. It is done implicitly when
5563 you call "$g->create".
5564 See "ENVIRONMENT VARIABLES" in guestfs(3) for a list of environment
5566 variables that can affect libguestfs handles. See also
5567 "guestfs_create_flags" in guestfs(3), and
5568 "$g->parse_environment_list".
5569 $g->parse_environment_list (\@environment);
5571 Parse the list of strings in the argument "environment" and set
5572 flags in the handle accordingly. For example if
5573 "LIBGUESTFS_DEBUG=1" is a string in the list, then the XverboseX
5574 flag is set in the handle.
5575 This is the same as "$g->parse_environment" except that it parses
5577 an explicit list of strings instead of the program's environment.
5578 $g->part_add ($device, $prlogex, $startsect, $endsect);
5580 This command adds a partition to "device". If there is no
5581 partition table on the device, call "$g->part_init" first.
5582 The "prlogex" parameter is the type of partition. Normally you
5584 should pass "p" or "primary" here, but MBR partition tables also
5585 support "l" (or "logical") and "e" (or "extended") partition types.
5586 "startsect" and "endsect" are the start and end of the partition in
5588 sectors. "endsect" may be negative, which means it counts
5589 backwards from the end of the disk ("-1" is the last sector).
5590 Creating a partition which covers the whole disk is not so easy.
5592 Use "$g->part_disk" to do that.
5593 $g->part_del ($device, $partnum);
5595 This command deletes the partition numbered "partnum" on "device".
5596 Note that in the case of MBR partitioning, deleting an extended
5598 partition also deletes any logical partitions it contains.
5599 $g->part_disk ($device, $parttype);
5601 This command is simply a combination of "$g->part_init" followed by
5602 "$g->part_add" to create a single primary partition covering the
5603 whole disk.
5604 "parttype" is the partition table type, usually "mbr" or "gpt", but
5606 other possible values are described in "$g->part_init".
5607 $g->part_expand_gpt ($device);
5609 Move backup GPT data structures to the end of the disk. This is
5610 useful in case of in-place image expand since disk space after
5611 backup GPT header is not usable. This is equivalent to "sgdisk
5612 -e".
5613 See also sgdisk(8).
5615 This function depends on the feature "gdisk". See also
5617 "$g->feature-available".
5618 $bootable = $g->part_get_bootable ($device, $partnum);
5620 This command returns true if the partition "partnum" on "device"
5621 has the bootable flag set.
5622 See also "$g->part_set_bootable".
5624 $guid = $g->part_get_disk_guid ($device);
5626 Return the disk identifier (GUID) of a GPT-partitioned "device".
5627 Behaviour is undefined for other partition types.
5628 This function depends on the feature "gdisk". See also
5630 "$g->feature-available".
5631 $attributes = $g->part_get_gpt_attributes ($device, $partnum);
5633 Return the attribute flags of numbered GPT partition "partnum". An
5634 error is returned for MBR partitions.
5635 This function depends on the feature "gdisk". See also
5637 "$g->feature-available".
5638 $guid = $g->part_get_gpt_guid ($device, $partnum);
5640 Return the GUID of numbered GPT partition "partnum".
5641 This function depends on the feature "gdisk". See also
5643 "$g->feature-available".
5644 $guid = $g->part_get_gpt_type ($device, $partnum);
5646 Return the type GUID of numbered GPT partition "partnum". For MBR
5647 partitions, return an appropriate GUID corresponding to the MBR
5648 type. Behaviour is undefined for other partition types.
5649 This function depends on the feature "gdisk". See also
5651 "$g->feature-available".
5652 $idbyte = $g->part_get_mbr_id ($device, $partnum);
5654 Returns the MBR type byte (also known as the ID byte) from the
5655 numbered partition "partnum".
5656 Note that only MBR (old DOS-style) partitions have type bytes. You
5658 will get undefined results for other partition table types (see
5659 "$g->part_get_parttype").
5660 $partitiontype = $g->part_get_mbr_part_type ($device, $partnum);
5662 This returns the partition type of an MBR partition numbered
5663 "partnum" on device "device".
5664 It returns "primary", "logical", or "extended".
5666 $name = $g->part_get_name ($device, $partnum);
5668 This gets the partition name on partition numbered "partnum" on
5669 device "device". Note that partitions are numbered from 1.
5670 The partition name can only be read on certain types of partition
5672 table. This works on "gpt" but not on "mbr" partitions.
5673 $parttype = $g->part_get_parttype ($device);
5675 This command examines the partition table on "device" and returns
5676 the partition table type (format) being used.
5677 Common return values include: "msdos" (a DOS/Windows style MBR
5679 partition table), "gpt" (a GPT/EFI-style partition table). Other
5680 values are possible, although unusual. See "$g->part_init" for a
5681 full list.
5682 $g->part_init ($device, $parttype);
5684 This creates an empty partition table on "device" of one of the
5685 partition types listed below. Usually "parttype" should be either
5686 "msdos" or "gpt" (for large disks).
5687 Initially there are no partitions. Following this, you should call
5689 "$g->part_add" for each partition required.
5690 Possible values for "parttype" are:
5692 "efi"
5694 "gpt"
5695 Intel EFI / GPT partition table.
5696 This is recommended for >= 2 TB partitions that will be
5698 accessed from Linux and Intel-based Mac OS X. It also has
5699 limited backwards compatibility with the "mbr" format.
5700 "mbr"
5702 "msdos"
5703 The standard PC "Master Boot Record" (MBR) format used by MS-
5704 DOS and Windows. This partition type will only work for device
5705 sizes up to 2 TB. For large disks we recommend using "gpt".
5706 Other partition table types that may work but are not supported
5708 include:
5709 "aix"
5711 AIX disk labels.
5712 "amiga"
5714 "rdb"
5715 Amiga "Rigid Disk Block" format.
5716 "bsd"
5718 BSD disk labels.
5719 "dasd"
5721 DASD, used on IBM mainframes.
5722 "dvh"
5724 MIPS/SGI volumes.
5725 "mac"
5727 Old Mac partition format. Modern Macs use "gpt".
5728 "pc98"
5730 NEC PC-98 format, common in Japan apparently.
5731 "sun"
5733 Sun disk labels.
5734 @partitions = $g->part_list ($device);
5736 This command parses the partition table on "device" and returns the
5737 list of partitions found.
5738 The fields in the returned structure are:
5740 "part_num"
5742 Partition number, counting from 1.
5743 "part_start"
5745 Start of the partition in bytes. To get sectors you have to
5746 divide by the deviceXs sector size, see "$g->blockdev_getss".
5747 "part_end"
5749 End of the partition in bytes.
5750 "part_size"
5752 Size of the partition in bytes.
5753 $g->part_resize ($device, $partnum, $endsect);
5755 This command resizes the partition numbered "partnum" on "device"
5756 by moving the end position.
5757 Note that this does not modify any filesystem present in the
5759 partition. If you wish to do this, you will need to use filesystem
5760 resizing commands like "$g->resize2fs".
5761 When growing a partition you will want to grow the filesystem
5763 afterwards, but when shrinking, you need to shrink the filesystem
5764 before the partition.
5765 $g->part_set_bootable ($device, $partnum, $bootable);
5767 This sets the bootable flag on partition numbered "partnum" on
5768 device "device". Note that partitions are numbered from 1.
5769 The bootable flag is used by some operating systems (notably
5771 Windows) to determine which partition to boot from. It is by no
5772 means universally recognized.
5773 $g->part_set_disk_guid ($device, $guid);
5775 Set the disk identifier (GUID) of a GPT-partitioned "device" to
5776 "guid". Return an error if the partition table of "device" isn't
5777 GPT, or if "guid" is not a valid GUID.
5778 This function depends on the feature "gdisk". See also
5780 "$g->feature-available".
5781 $g->part_set_disk_guid_random ($device);
5783 Set the disk identifier (GUID) of a GPT-partitioned "device" to a
5784 randomly generated value. Return an error if the partition table
5785 of "device" isn't GPT.
5786 This function depends on the feature "gdisk". See also
5788 "$g->feature-available".
5789 $g->part_set_gpt_attributes ($device, $partnum, $attributes);
5791 Set the attribute flags of numbered GPT partition "partnum" to
5792 "attributes". Return an error if the partition table of "device"
5793 isn't GPT.
5794 See
5796 <https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_entries>
5797 for a useful list of partition attributes.
5798 This function depends on the feature "gdisk". See also
5800 "$g->feature-available".
5801 $g->part_set_gpt_guid ($device, $partnum, $guid);
5803 Set the GUID of numbered GPT partition "partnum" to "guid". Return
5804 an error if the partition table of "device" isn't GPT, or if "guid"
5805 is not a valid GUID.
5806 This function depends on the feature "gdisk". See also
5808 "$g->feature-available".
5809 $g->part_set_gpt_type ($device, $partnum, $guid);
5811 Set the type GUID of numbered GPT partition "partnum" to "guid".
5812 Return an error if the partition table of "device" isn't GPT, or if
5813 "guid" is not a valid GUID.
5814 See
5816 <https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs>
5817 for a useful list of type GUIDs.
5818 This function depends on the feature "gdisk". See also
5820 "$g->feature-available".
5821 $g->part_set_mbr_id ($device, $partnum, $idbyte);
5823 Sets the MBR type byte (also known as the ID byte) of the numbered
5824 partition "partnum" to "idbyte". Note that the type bytes quoted
5825 in most documentation are in fact hexadecimal numbers, but usually
5826 documented without any leading "0x" which might be confusing.
5827 Note that only MBR (old DOS-style) partitions have type bytes. You
5829 will get undefined results for other partition table types (see
5830 "$g->part_get_parttype").
5831 $g->part_set_name ($device, $partnum, $name);
5833 This sets the partition name on partition numbered "partnum" on
5834 device "device". Note that partitions are numbered from 1.
5835 The partition name can only be set on certain types of partition
5837 table. This works on "gpt" but not on "mbr" partitions.
5838 $device = $g->part_to_dev ($partition);
5840 This function takes a partition name (eg. "/dev/sdb1") and removes
5841 the partition number, returning the device name (eg. "/dev/sdb").
5842 The named partition must exist, for example as a string returned
5844 from "$g->list_partitions".
5845 See also "$g->part_to_partnum", "$g->device_index".
5847 $partnum = $g->part_to_partnum ($partition);
5849 This function takes a partition name (eg. "/dev/sdb1") and returns
5850 the partition number (eg. 1).
5851 The named partition must exist, for example as a string returned
5853 from "$g->list_partitions".
5854 See also "$g->part_to_dev".
5856 $g->ping_daemon ();
5858 This is a test probe into the guestfs daemon running inside the
5859 libguestfs appliance. Calling this function checks that the daemon
5860 responds to the ping message, without affecting the daemon or
5861 attached block device(s) in any other way.
5862 $content = $g->pread ($path, $count, $offset);
5864 This command lets you read part of a file. It reads "count" bytes
5865 of the file, starting at "offset", from file "path".
5866 This may read fewer bytes than requested. For further details see
5868 the pread(2) system call.
5869 See also "$g->pwrite", "$g->pread_device".
5871 Because of the message protocol, there is a transfer limit of
5873 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5874 guestfs(3).
5875 $content = $g->pread_device ($device, $count, $offset);
5877 This command lets you read part of a block device. It reads
5878 "count" bytes of "device", starting at "offset".
5879 This may read fewer bytes than requested. For further details see
5881 the pread(2) system call.
5882 See also "$g->pread".
5884 Because of the message protocol, there is a transfer limit of
5886 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5887 guestfs(3).
5888 $g->pvchange_uuid ($device);
5890 Generate a new random UUID for the physical volume "device".
5891 This function depends on the feature "lvm2". See also
5893 "$g->feature-available".
5894 $g->pvchange_uuid_all ();
5896 Generate new random UUIDs for all physical volumes.
5897 This function depends on the feature "lvm2". See also
5899 "$g->feature-available".
5900 $g->pvcreate ($device);
5902 This creates an LVM physical volume on the named "device", where
5903 "device" should usually be a partition name such as /dev/sda1.
5904 This function depends on the feature "lvm2". See also
5906 "$g->feature-available".
5907 $g->pvremove ($device);
5909 This wipes a physical volume "device" so that LVM will no longer
5910 recognise it.
5911 The implementation uses the pvremove(8) command which refuses to
5913 wipe physical volumes that contain any volume groups, so you have
5914 to remove those first.
5915 This function depends on the feature "lvm2". See also
5917 "$g->feature-available".
5918 $g->pvresize ($device);
5920 This resizes (expands or shrinks) an existing LVM physical volume
5921 to match the new size of the underlying device.
5922 This function depends on the feature "lvm2". See also
5924 "$g->feature-available".
5925 $g->pvresize_size ($device, $size);
5927 This command is the same as "$g->pvresize" except that it allows
5928 you to specify the new size (in bytes) explicitly.
5929 This function depends on the feature "lvm2". See also
5931 "$g->feature-available".
5932 @physvols = $g->pvs ();
5934 List all the physical volumes detected. This is the equivalent of
5935 the pvs(8) command.
5936 This returns a list of just the device names that contain PVs (eg.
5938 /dev/sda2).
5939 See also "$g->pvs_full".
5941 This function depends on the feature "lvm2". See also
5943 "$g->feature-available".
5944 @physvols = $g->pvs_full ();
5946 List all the physical volumes detected. This is the equivalent of
5947 the pvs(8) command. The "full" version includes all fields.
5948 This function depends on the feature "lvm2". See also
5950 "$g->feature-available".
5951 $uuid = $g->pvuuid ($device);
5953 This command returns the UUID of the LVM PV "device".
5954 $nbytes = $g->pwrite ($path, $content, $offset);
5956 This command writes to part of a file. It writes the data buffer
5957 "content" to the file "path" starting at offset "offset".
5958 This command implements the pwrite(2) system call, and like that
5960 system call it may not write the full data requested. The return
5961 value is the number of bytes that were actually written to the
5962 file. This could even be 0, although short writes are unlikely for
5963 regular files in ordinary circumstances.
5964 See also "$g->pread", "$g->pwrite_device".
5966 Because of the message protocol, there is a transfer limit of
5968 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5969 guestfs(3).
5970 $nbytes = $g->pwrite_device ($device, $content, $offset);
5972 This command writes to part of a device. It writes the data buffer
5973 "content" to "device" starting at offset "offset".
5974 This command implements the pwrite(2) system call, and like that
5976 system call it may not write the full data requested (although
5977 short writes to disk devices and partitions are probably impossible
5978 with standard Linux kernels).
5979 See also "$g->pwrite".
5981 Because of the message protocol, there is a transfer limit of
5983 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5984 guestfs(3).
5985 $content = $g->read_file ($path);
5987 This calls returns the contents of the file "path" as a buffer.
5988 Unlike "$g->cat", this function can correctly handle files that
5990 contain embedded ASCII NUL characters.
5991 @lines = $g->read_lines ($path);
5993 Return the contents of the file named "path".
5994 The file contents are returned as a list of lines. Trailing "LF"
5996 and "CRLF" character sequences are not returned.
5997 Note that this function cannot correctly handle binary files
5999 (specifically, files containing "\0" character which is treated as
6000 end of string). For those you need to use the "$g->read_file"
6001 function and split the buffer into lines yourself.
6002 @entries = $g->readdir ($dir);
6004 This returns the list of directory entries in directory "dir".
6005 All entries in the directory are returned, including "." and "..".
6007 The entries are not sorted, but returned in the same order as the
6008 underlying filesystem.
6009 Also this call returns basic file type information about each file.
6011 The "ftyp" field will contain one of the following characters:
6012 'b' Block special
6014 'c' Char special
6016 'd' Directory
6018 'f' FIFO (named pipe)
6020 'l' Symbolic link
6022 'r' Regular file
6024 's' Socket
6026 'u' Unknown file type
6028 '?' The readdir(3) call returned a "d_type" field with an
6030 unexpected value
6031 This function is primarily intended for use by programs. To get a
6033 simple list of names, use "$g->ls". To get a printable directory
6034 for human consumption, use "$g->ll".
6035 Because of the message protocol, there is a transfer limit of
6037 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
6038 guestfs(3).
6039 $link = $g->readlink ($path);
6041 This command reads the target of a symbolic link.
6042 @links = $g->readlinklist ($path, \@names);
6044 This call allows you to do a "readlink" operation on multiple
6045 files, where all files are in the directory "path". "names" is the
6046 list of files from this directory.
6047 On return you get a list of strings, with a one-to-one
6049 correspondence to the "names" list. Each string is the value of
6050 the symbolic link.
6051 If the readlink(2) operation fails on any name, then the
6053 corresponding result string is the empty string "". However the
6054 whole operation is completed even if there were readlink(2) errors,
6055 and so you can call this function with names where you don't know
6056 if they are symbolic links already (albeit slightly less
6057 efficient).
6058 This call is intended for programs that want to efficiently list a
6060 directory contents without making many round-trips.
6061 $rpath = $g->realpath ($path);
6063 Return the canonicalized absolute pathname of "path". The returned
6064 path has no ".", ".." or symbolic link path elements.
6065 $g->remount ($mountpoint [, rw => $rw]);
6067 This call allows you to change the "rw" (readonly/read-write) flag
6068 on an already mounted filesystem at "mountpoint", converting a
6069 readonly filesystem to be read-write, or vice-versa.
6070 Note that at the moment you must supply the "optional" "rw"
6072 parameter. In future we may allow other flags to be adjusted.
6073 $g->remove_drive ($label);
6075 This function is conceptually the opposite of "$g->add_drive_opts".
6076 It removes the drive that was previously added with label "label".
6077 Note that in order to remove drives, you have to add them with
6079 labels (see the optional "label" argument to "$g->add_drive_opts").
6080 If you didn't use a label, then they cannot be removed.
6081 You can call this function before or after launching the handle.
6083 If called after launch, if the backend supports it, we try to hot
6084 unplug the drive: see "HOTPLUGGING" in guestfs(3). The disk must
6085 not be in use (eg. mounted) when you do this. We try to detect if
6086 the disk is in use and stop you from doing this.
6087 $g->removexattr ($xattr, $path);
6089 This call removes the extended attribute named "xattr" of the file
6090 "path".
6091 See also: "$g->lremovexattr", attr(5).
6093 This function depends on the feature "linuxxattrs". See also
6095 "$g->feature-available".
6096 $g->rename ($oldpath, $newpath);
6098 Rename a file to a new place on the same filesystem. This is the
6099 same as the Linux rename(2) system call. In most cases you are
6100 better to use "$g->mv" instead.
6101 $g->resize2fs ($device);
6103 This resizes an ext2, ext3 or ext4 filesystem to match the size of
6104 the underlying device.
6105 See also "RESIZE2FS ERRORS" in guestfs(3).
6107 $g->resize2fs_M ($device);
6109 This command is the same as "$g->resize2fs", but the filesystem is
6110 resized to its minimum size. This works like the -M option to the
6111 resize2fs(8) command.
6112 To get the resulting size of the filesystem you should call
6114 "$g->tune2fs_l" and read the "Block size" and "Block count" values.
6115 These two numbers, multiplied together, give the resulting size of
6116 the minimal filesystem in bytes.
6117 See also "RESIZE2FS ERRORS" in guestfs(3).
6119 $g->resize2fs_size ($device, $size);
6121 This command is the same as "$g->resize2fs" except that it allows
6122 you to specify the new size (in bytes) explicitly.
6123 See also "RESIZE2FS ERRORS" in guestfs(3).
6125 $g->rm ($path);
6127 Remove the single file "path".
6128 $g->rm_f ($path);
6130 Remove the file "path".
6131 If the file doesn't exist, that error is ignored. (Other errors,
6133 eg. I/O errors or bad paths, are not ignored)
6134 This call cannot remove directories. Use "$g->rmdir" to remove an
6136 empty directory, or "$g->rm_rf" to remove directories recursively.
6137 $g->rm_rf ($path);
6139 Remove the file or directory "path", recursively removing the
6140 contents if its a directory. This is like the "rm -rf" shell
6141 command.
6142 $g->rmdir ($path);
6144 Remove the single directory "path".
6145 $g->rmmountpoint ($exemptpath);
6147 This call removes a mountpoint that was previously created with
6148 "$g->mkmountpoint". See "$g->mkmountpoint" for full details.
6149 $g->rsync ($src, $dest [, archive => $archive] [, deletedest =>
6151 $deletedest]);
6152 This call may be used to copy or synchronize two directories under
6153 the same libguestfs handle. This uses the rsync(1) program which
6154 uses a fast algorithm that avoids copying files unnecessarily.
6155 "src" and "dest" are the source and destination directories. Files
6157 are copied from "src" to "dest".
6158 The optional arguments are:
6160 "archive"
6162 Turns on archive mode. This is the same as passing the
6163 --archive flag to "rsync".
6164 "deletedest"
6166 Delete files at the destination that do not exist at the
6167 source.
6168 This function depends on the feature "rsync". See also
6170 "$g->feature-available".
6171 $g->rsync_in ($remote, $dest [, archive => $archive] [, deletedest =>
6173 $deletedest]);
6174 This call may be used to copy or synchronize the filesystem on the
6175 host or on a remote computer with the filesystem within libguestfs.
6176 This uses the rsync(1) program which uses a fast algorithm that
6177 avoids copying files unnecessarily.
6178 This call only works if the network is enabled. See
6180 "$g->set_network" or the --network option to various tools like
6181 guestfish(1).
6182 Files are copied from the remote server and directory specified by
6184 "remote" to the destination directory "dest".
6185 The format of the remote server string is defined by rsync(1).
6187 Note that there is no way to supply a password or passphrase so the
6188 target must be set up not to require one.
6189 The optional arguments are the same as those of "$g->rsync".
6191 This function depends on the feature "rsync". See also
6193 "$g->feature-available".
6194 $g->rsync_out ($src, $remote [, archive => $archive] [, deletedest =>
6196 $deletedest]);
6197 This call may be used to copy or synchronize the filesystem within
6198 libguestfs with a filesystem on the host or on a remote computer.
6199 This uses the rsync(1) program which uses a fast algorithm that
6200 avoids copying files unnecessarily.
6201 This call only works if the network is enabled. See
6203 "$g->set_network" or the --network option to various tools like
6204 guestfish(1).
6205 Files are copied from the source directory "src" to the remote
6207 server and directory specified by "remote".
6208 The format of the remote server string is defined by rsync(1).
6210 Note that there is no way to supply a password or passphrase so the
6211 target must be set up not to require one.
6212 The optional arguments are the same as those of "$g->rsync".
6214 Globbing does not happen on the "src" parameter. In programs which
6216 use the API directly you have to expand wildcards yourself (see
6217 "$g->glob_expand"). In guestfish you can use the "glob" command
6218 (see "glob" in guestfish(1)), for example:
6219 ><fs> glob rsync-out /* rsync://remote/
6221 This function depends on the feature "rsync". See also
6223 "$g->feature-available".
6224 $g->scrub_device ($device);
6226 This command writes patterns over "device" to make data retrieval
6227 more difficult.
6228 It is an interface to the scrub(1) program. See that manual page
6230 for more details.
6231 This function depends on the feature "scrub". See also
6233 "$g->feature-available".
6234 $g->scrub_file ($file);
6236 This command writes patterns over a file to make data retrieval
6237 more difficult.
6238 The file is removed after scrubbing.
6240 It is an interface to the scrub(1) program. See that manual page
6242 for more details.
6243 This function depends on the feature "scrub". See also
6245 "$g->feature-available".
6246 $g->scrub_freespace ($dir);
6248 This command creates the directory "dir" and then fills it with
6249 files until the filesystem is full, and scrubs the files as for
6250 "$g->scrub_file", and deletes them. The intention is to scrub any
6251 free space on the partition containing "dir".
6252 It is an interface to the scrub(1) program. See that manual page
6254 for more details.
6255 This function depends on the feature "scrub". See also
6257 "$g->feature-available".
6258 $g->selinux_relabel ($specfile, $path [, force => $force]);
6260 SELinux relabel parts of the filesystem.
6261 The "specfile" parameter controls the policy spec file used. You
6263 have to parse "/etc/selinux/config" to find the correct SELinux
6264 policy and then pass the spec file, usually: "/etc/selinux/" +
6265 selinuxtype + "/contexts/files/file_contexts".
6266 The required "path" parameter is the top level directory where
6268 relabelling starts. Normally you should pass "path" as "/" to
6269 relabel the whole guest filesystem.
6270 The optional "force" boolean controls whether the context is reset
6272 for customizable files, and also whether the user, role and range
6273 parts of the file context is changed.
6274 This function depends on the feature "selinuxrelabel". See also
6276 "$g->feature-available".
6277 $g->set_append ($append);
6279 This function is used to add additional options to the libguestfs
6280 appliance kernel command line.
6281 The default is "NULL" unless overridden by setting
6283 "LIBGUESTFS_APPEND" environment variable.
6284 Setting "append" to "NULL" means no additional options are passed
6286 (libguestfs always adds a few of its own).
6287 $g->set_attach_method ($backend);
6289 Set the method that libguestfs uses to connect to the backend
6290 guestfsd daemon.
6291 See "BACKEND" in guestfs(3).
6293 This function is deprecated. In new code, use the "set_backend"
6295 call instead.
6296 Deprecated functions will not be removed from the API, but the fact
6298 that they are deprecated indicates that there are problems with
6299 correct use of these functions.
6300 $g->set_autosync ($autosync);
6302 If "autosync" is true, this enables autosync. Libguestfs will make
6303 a best effort attempt to make filesystems consistent and
6304 synchronized when the handle is closed (also if the program exits
6305 without closing handles).
6306 This is enabled by default (since libguestfs 1.5.24, previously it
6308 was disabled by default).
6309 $g->set_backend ($backend);
6311 Set the method that libguestfs uses to connect to the backend
6312 guestfsd daemon.
6313 This handle property was previously called the "attach method".
6315 See "BACKEND" in guestfs(3).
6317 $g->set_backend_setting ($name, $val);
6319 Append "name=value" to the backend settings string list. However
6320 if a string already exists matching "name" or beginning with
6321 "name=", then that setting is replaced.
6322 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
6324 $g->set_backend_settings (\@settings);
6326 Set a list of zero or more settings which are passed through to the
6327 current backend. Each setting is a string which is interpreted in
6328 a backend-specific way, or ignored if not understood by the
6329 backend.
6330 The default value is an empty list, unless the environment variable
6332 "LIBGUESTFS_BACKEND_SETTINGS" was set when the handle was created.
6333 This environment variable contains a colon-separated list of
6334 settings.
6335 This call replaces all backend settings. If you want to replace a
6337 single backend setting, see "$g->set_backend_setting". If you want
6338 to clear a single backend setting, see "$g->clear_backend_setting".
6339 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
6341 $g->set_cachedir ($cachedir);
6343 Set the directory used by the handle to store the appliance cache,
6344 when using a supermin appliance. The appliance is cached and
6345 shared between all handles which have the same effective user ID.
6346 The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR"
6348 control the default value: If "LIBGUESTFS_CACHEDIR" is set, then
6349 that is the default. Else if "TMPDIR" is set, then that is the
6350 default. Else /var/tmp is the default.
6351 $g->set_direct ($direct);
6353 If the direct appliance mode flag is enabled, then stdin and stdout
6354 are passed directly through to the appliance once it is launched.
6355 One consequence of this is that log messages aren't caught by the
6357 library and handled by "$g->set_log_message_callback", but go
6358 straight to stdout.
6359 You probably don't want to use this unless you know what you are
6361 doing.
6362 The default is disabled.
6364 This function is deprecated. In new code, use the
6366 "internal_get_console_socket" call instead.
6367 Deprecated functions will not be removed from the API, but the fact
6369 that they are deprecated indicates that there are problems with
6370 correct use of these functions.
6371 $g->set_e2attrs ($file, $attrs [, clear => $clear]);
6373 This sets or clears the file attributes "attrs" associated with the
6374 inode file.
6375 "attrs" is a string of characters representing file attributes.
6377 See "$g->get_e2attrs" for a list of possible attributes. Not all
6378 attributes can be changed.
6379 If optional boolean "clear" is not present or false, then the
6381 "attrs" listed are set in the inode.
6382 If "clear" is true, then the "attrs" listed are cleared in the
6384 inode.
6385 In both cases, other attributes not present in the "attrs" string
6387 are left unchanged.
6388 These attributes are only present when the file is located on an
6390 ext2/3/4 filesystem. Using this call on other filesystem types
6391 will result in an error.
6392 $g->set_e2generation ($file, $generation);
6394 This sets the ext2 file generation of a file.
6395 See "$g->get_e2generation".
6397 $g->set_e2label ($device, $label);
6399 This sets the ext2/3/4 filesystem label of the filesystem on
6400 "device" to "label". Filesystem labels are limited to 16
6401 characters.
6402 You can use either "$g->tune2fs_l" or "$g->get_e2label" to return
6404 the existing label on a filesystem.
6405 This function is deprecated. In new code, use the "set_label" call
6407 instead.
6408 Deprecated functions will not be removed from the API, but the fact
6410 that they are deprecated indicates that there are problems with
6411 correct use of these functions.
6412 $g->set_e2uuid ($device, $uuid);
6414 This sets the ext2/3/4 filesystem UUID of the filesystem on
6415 "device" to "uuid". The format of the UUID and alternatives such
6416 as "clear", "random" and "time" are described in the tune2fs(8)
6417 manpage.
6418 You can use "$g->vfs_uuid" to return the existing UUID of a
6420 filesystem.
6421 This function is deprecated. In new code, use the "set_uuid" call
6423 instead.
6424 Deprecated functions will not be removed from the API, but the fact
6426 that they are deprecated indicates that there are problems with
6427 correct use of these functions.
6428 $g->set_hv ($hv);
6430 Set the hypervisor binary that we will use. The hypervisor depends
6431 on the backend, but is usually the location of the qemu/KVM
6432 hypervisor. For the uml backend, it is the location of the "linux"
6433 or "vmlinux" binary.
6434 The default is chosen when the library was compiled by the
6436 configure script.
6437 You can also override this by setting the "LIBGUESTFS_HV"
6439 environment variable.
6440 Note that you should call this function as early as possible after
6442 creating the handle. This is because some pre-launch operations
6443 depend on testing qemu features (by running "qemu -help"). If the
6444 qemu binary changes, we don't retest features, and so you might see
6445 inconsistent results. Using the environment variable
6446 "LIBGUESTFS_HV" is safest of all since that picks the qemu binary
6447 at the same time as the handle is created.
6448 $g->set_identifier ($identifier);
6450 This is an informative string which the caller may optionally set
6451 in the handle. It is printed in various places, allowing the
6452 current handle to be identified in debugging output.
6453 One important place is when tracing is enabled. If the identifier
6455 string is not an empty string, then trace messages change from
6456 this:
6457 libguestfs: trace: get_tmpdir
6459 libguestfs: trace: get_tmpdir = "/tmp"
6460 to this:
6462 libguestfs: trace: ID: get_tmpdir
6464 libguestfs: trace: ID: get_tmpdir = "/tmp"
6465 where "ID" is the identifier string set by this call.
6467 The identifier must only contain alphanumeric ASCII characters,
6469 underscore and minus sign. The default is the empty string.
6470 See also "$g->set_program", "$g->set_trace", "$g->get_identifier".
6472 $g->set_label ($mountable, $label);
6474 Set the filesystem label on "mountable" to "label".
6475 Only some filesystem types support labels, and libguestfs supports
6477 setting labels on only a subset of these.
6478 ext2, ext3, ext4
6480 Labels are limited to 16 bytes.
6481 NTFS
6483 Labels are limited to 128 unicode characters.
6484 XFS The label is limited to 12 bytes. The filesystem must not be
6486 mounted when trying to set the label.
6487 btrfs
6489 The label is limited to 255 bytes and some characters are not
6490 allowed. Setting the label on a btrfs subvolume will set the
6491 label on its parent filesystem. The filesystem must not be
6492 mounted when trying to set the label.
6493 fat The label is limited to 11 bytes.
6495 swap
6497 The label is limited to 16 bytes.
6498 If there is no support for changing the label for the type of the
6500 specified filesystem, set_label will fail and set errno as ENOTSUP.
6501 To read the label on a filesystem, call "$g->vfs_label".
6503 $g->set_libvirt_requested_credential ($index, $cred);
6505 After requesting the "index"'th credential from the user, call this
6506 function to pass the answer back to libvirt.
6507 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
6509 example code.
6510 $g->set_libvirt_supported_credentials (\@creds);
6512 Call this function before setting an event handler for
6513 "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential
6514 types that the program knows how to process.
6515 The "creds" list must be a non-empty list of strings. Possible
6517 strings are:
6518 "username"
6520 "authname"
6521 "language"
6522 "cnonce"
6523 "passphrase"
6524 "echoprompt"
6525 "noechoprompt"
6526 "realm"
6527 "external"
6528 See libvirt documentation for the meaning of these credential
6530 types.
6531 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
6533 example code.
6534 $g->set_memsize ($memsize);
6536 This sets the memory size in megabytes allocated to the hypervisor.
6537 This only has any effect if called before "$g->launch".
6538 You can also change this by setting the environment variable
6540 "LIBGUESTFS_MEMSIZE" before the handle is created.
6541 For more information on the architecture of libguestfs, see
6543 guestfs(3).
6544 $g->set_network ($network);
6546 If "network" is true, then the network is enabled in the libguestfs
6547 appliance. The default is false.
6548 This affects whether commands are able to access the network (see
6550 "RUNNING COMMANDS" in guestfs(3)).
6551 You must call this before calling "$g->launch", otherwise it has no
6553 effect.
6554 $g->set_path ($searchpath);
6556 Set the path that libguestfs searches for kernel and initrd.img.
6557 The default is "$libdir/guestfs" unless overridden by setting
6559 "LIBGUESTFS_PATH" environment variable.
6560 Setting "path" to "NULL" restores the default path.
6562 $g->set_pgroup ($pgroup);
6564 If "pgroup" is true, child processes are placed into their own
6565 process group.
6566 The practical upshot of this is that signals like "SIGINT" (from
6568 users pressing "^C") won't be received by the child process.
6569 The default for this flag is false, because usually you want "^C"
6571 to kill the subprocess. Guestfish sets this flag to true when used
6572 interactively, so that "^C" can cancel long-running commands
6573 gracefully (see "$g->user_cancel").
6574 $g->set_program ($program);
6576 Set the program name. This is an informative string which the main
6577 program may optionally set in the handle.
6578 When the handle is created, the program name in the handle is set
6580 to the basename from "argv[0]". The program name can never be
6581 "NULL".
6582 $g->set_qemu ($hv);
6584 Set the hypervisor binary (usually qemu) that we will use.
6585 The default is chosen when the library was compiled by the
6587 configure script.
6588 You can also override this by setting the "LIBGUESTFS_HV"
6590 environment variable.
6591 Setting "hv" to "NULL" restores the default qemu binary.
6593 Note that you should call this function as early as possible after
6595 creating the handle. This is because some pre-launch operations
6596 depend on testing qemu features (by running "qemu -help"). If the
6597 qemu binary changes, we don't retest features, and so you might see
6598 inconsistent results. Using the environment variable
6599 "LIBGUESTFS_HV" is safest of all since that picks the qemu binary
6600 at the same time as the handle is created.
6601 This function is deprecated. In new code, use the "set_hv" call
6603 instead.
6604 Deprecated functions will not be removed from the API, but the fact
6606 that they are deprecated indicates that there are problems with
6607 correct use of these functions.
6608 $g->set_recovery_proc ($recoveryproc);
6610 If this is called with the parameter "false" then "$g->launch" does
6611 not create a recovery process. The purpose of the recovery process
6612 is to stop runaway hypervisor processes in the case where the main
6613 program aborts abruptly.
6614 This only has any effect if called before "$g->launch", and the
6616 default is true.
6617 About the only time when you would want to disable this is if the
6619 main process will fork itself into the background ("daemonize"
6620 itself). In this case the recovery process thinks that the main
6621 program has disappeared and so kills the hypervisor, which is not
6622 very helpful.
6623 $g->set_selinux ($selinux);
6625 This sets the selinux flag that is passed to the appliance at boot
6626 time. The default is "selinux=0" (disabled).
6627 Note that if SELinux is enabled, it is always in Permissive mode
6629 ("enforcing=0").
6630 For more information on the architecture of libguestfs, see
6632 guestfs(3).
6633 This function is deprecated. In new code, use the
6635 "selinux_relabel" call instead.
6636 Deprecated functions will not be removed from the API, but the fact
6638 that they are deprecated indicates that there are problems with
6639 correct use of these functions.
6640 $g->set_smp ($smp);
6642 Change the number of virtual CPUs assigned to the appliance. The
6643 default is 1. Increasing this may improve performance, though
6644 often it has no effect.
6645 This function must be called before "$g->launch".
6647 $g->set_tmpdir ($tmpdir);
6649 Set the directory used by the handle to store temporary files.
6650 The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control
6652 the default value: If "LIBGUESTFS_TMPDIR" is set, then that is the
6653 default. Else if "TMPDIR" is set, then that is the default. Else
6654 /tmp is the default.
6655 $g->set_trace ($trace);
6657 If the command trace flag is set to 1, then libguestfs calls,
6658 parameters and return values are traced.
6659 If you want to trace C API calls into libguestfs (and other
6661 libraries) then possibly a better way is to use the external
6662 ltrace(1) command.
6663 Command traces are disabled unless the environment variable
6665 "LIBGUESTFS_TRACE" is defined and set to 1.
6666 Trace messages are normally sent to "stderr", unless you register a
6668 callback to send them somewhere else (see
6669 "$g->set_event_callback").
6670 $g->set_uuid ($device, $uuid);
6672 Set the filesystem UUID on "device" to "uuid". If this fails and
6673 the errno is ENOTSUP, means that there is no support for changing
6674 the UUID for the type of the specified filesystem.
6675 Only some filesystem types support setting UUIDs.
6677 To read the UUID on a filesystem, call "$g->vfs_uuid".
6679 $g->set_uuid_random ($device);
6681 Set the filesystem UUID on "device" to a random UUID. If this
6682 fails and the errno is ENOTSUP, means that there is no support for
6683 changing the UUID for the type of the specified filesystem.
6684 Only some filesystem types support setting UUIDs.
6686 To read the UUID on a filesystem, call "$g->vfs_uuid".
6688 $g->set_verbose ($verbose);
6690 If "verbose" is true, this turns on verbose messages.
6691 Verbose messages are disabled unless the environment variable
6693 "LIBGUESTFS_DEBUG" is defined and set to 1.
6694 Verbose messages are normally sent to "stderr", unless you register
6696 a callback to send them somewhere else (see
6697 "$g->set_event_callback").
6698 $g->setcon ($context);
6700 This sets the SELinux security context of the daemon to the string
6701 "context".
6702 See the documentation about SELINUX in guestfs(3).
6704 This function depends on the feature "selinux". See also
6706 "$g->feature-available".
6707 This function is deprecated. In new code, use the
6709 "selinux_relabel" call instead.
6710 Deprecated functions will not be removed from the API, but the fact
6712 that they are deprecated indicates that there are problems with
6713 correct use of these functions.
6714 $g->setxattr ($xattr, $val, $vallen, $path);
6716 This call sets the extended attribute named "xattr" of the file
6717 "path" to the value "val" (of length "vallen"). The value is
6718 arbitrary 8 bit data.
6719 See also: "$g->lsetxattr", attr(5).
6721 This function depends on the feature "linuxxattrs". See also
6723 "$g->feature-available".
6724 $g->sfdisk ($device, $cyls, $heads, $sectors, \@lines);
6726 This is a direct interface to the sfdisk(8) program for creating
6727 partitions on block devices.
6728 "device" should be a block device, for example /dev/sda.
6730 "cyls", "heads" and "sectors" are the number of cylinders, heads
6732 and sectors on the device, which are passed directly to sfdisk(8)
6733 as the -C, -H and -S parameters. If you pass 0 for any of these,
6734 then the corresponding parameter is omitted. Usually for XlargeX
6735 disks, you can just pass 0 for these, but for small (floppy-sized)
6736 disks, sfdisk(8) (or rather, the kernel) cannot work out the right
6737 geometry and you will need to tell it.
6738 "lines" is a list of lines that we feed to sfdisk(8). For more
6740 information refer to the sfdisk(8) manpage.
6741 To create a single partition occupying the whole disk, you would
6743 pass "lines" as a single element list, when the single element
6744 being the string "," (comma).
6745 See also: "$g->sfdisk_l", "$g->sfdisk_N", "$g->part_init"
6747 This function is deprecated. In new code, use the "part_add" call
6749 instead.
6750 Deprecated functions will not be removed from the API, but the fact
6752 that they are deprecated indicates that there are problems with
6753 correct use of these functions.
6754 $g->sfdiskM ($device, \@lines);
6756 This is a simplified interface to the "$g->sfdisk" command, where
6757 partition sizes are specified in megabytes only (rounded to the
6758 nearest cylinder) and you don't need to specify the cyls, heads and
6759 sectors parameters which were rarely if ever used anyway.
6760 See also: "$g->sfdisk", the sfdisk(8) manpage and "$g->part_disk"
6762 This function is deprecated. In new code, use the "part_add" call
6764 instead.
6765 Deprecated functions will not be removed from the API, but the fact
6767 that they are deprecated indicates that there are problems with
6768 correct use of these functions.
6769 $g->sfdisk_N ($device, $partnum, $cyls, $heads, $sectors, $line);
6771 This runs sfdisk(8) option to modify just the single partition "n"
6772 (note: "n" counts from 1).
6773 For other parameters, see "$g->sfdisk". You should usually pass 0
6775 for the cyls/heads/sectors parameters.
6776 See also: "$g->part_add"
6778 This function is deprecated. In new code, use the "part_add" call
6780 instead.
6781 Deprecated functions will not be removed from the API, but the fact
6783 that they are deprecated indicates that there are problems with
6784 correct use of these functions.
6785 $partitions = $g->sfdisk_disk_geometry ($device);
6787 This displays the disk geometry of "device" read from the partition
6788 table. Especially in the case where the underlying block device
6789 has been resized, this can be different from the kernelXs idea of
6790 the geometry (see "$g->sfdisk_kernel_geometry").
6791 The result is in human-readable format, and not designed to be
6793 parsed.
6794 $partitions = $g->sfdisk_kernel_geometry ($device);
6796 This displays the kernelXs idea of the geometry of "device".
6797 The result is in human-readable format, and not designed to be
6799 parsed.
6800 $partitions = $g->sfdisk_l ($device);
6802 This displays the partition table on "device", in the human-
6803 readable output of the sfdisk(8) command. It is not intended to be
6804 parsed.
6805 See also: "$g->part_list"
6807 This function is deprecated. In new code, use the "part_list" call
6809 instead.
6810 Deprecated functions will not be removed from the API, but the fact
6812 that they are deprecated indicates that there are problems with
6813 correct use of these functions.
6814 $output = $g->sh ($command);
6816 This call runs a command from the guest filesystem via the guestXs
6817 /bin/sh.
6818 This is like "$g->command", but passes the command to:
6820 /bin/sh -c "command"
6822 Depending on the guestXs shell, this usually results in wildcards
6824 being expanded, shell expressions being interpolated and so on.
6825 All the provisos about "$g->command" apply to this call.
6827 @lines = $g->sh_lines ($command);
6829 This is the same as "$g->sh", but splits the result into a list of
6830 lines.
6831 See also: "$g->command_lines"
6833 $g->shutdown ();
6835 This is the opposite of "$g->launch". It performs an orderly
6836 shutdown of the backend process(es). If the autosync flag is set
6837 (which is the default) then the disk image is synchronized.
6838 If the subprocess exits with an error then this function will
6840 return an error, which should not be ignored (it may indicate that
6841 the disk image could not be written out properly).
6842 It is safe to call this multiple times. Extra calls are ignored.
6844 This call does not close or free up the handle. You still need to
6846 call "$g->close" afterwards.
6847 "$g->close" will call this if you don't do it explicitly, but note
6849 that any errors are ignored in that case.
6850 $g->sleep ($secs);
6852 Sleep for "secs" seconds.
6853 %statbuf = $g->stat ($path);
6855 Returns file information for the given "path".
6856 This is the same as the stat(2) system call.
6858 This function is deprecated. In new code, use the "statns" call
6860 instead.
6861 Deprecated functions will not be removed from the API, but the fact
6863 that they are deprecated indicates that there are problems with
6864 correct use of these functions.
6865 %statbuf = $g->statns ($path);
6867 Returns file information for the given "path".
6868 This is the same as the stat(2) system call.
6870 %statbuf = $g->statvfs ($path);
6872 Returns file system statistics for any mounted file system. "path"
6873 should be a file or directory in the mounted file system (typically
6874 it is the mount point itself, but it doesn't need to be).
6875 This is the same as the statvfs(2) system call.
6877 @stringsout = $g->strings ($path);
6879 This runs the strings(1) command on a file and returns the list of
6880 printable strings found.
6881 The "strings" command has, in the past, had problems with parsing
6883 untrusted files. These are mitigated in the current version of
6884 libguestfs, but see "CVE-2014-8484" in guestfs(3).
6885 Because of the message protocol, there is a transfer limit of
6887 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
6888 guestfs(3).
6889 @stringsout = $g->strings_e ($encoding, $path);
6891 This is like the "$g->strings" command, but allows you to specify
6892 the encoding of strings that are looked for in the source file
6893 "path".
6894 Allowed encodings are:
6896 s Single 7-bit-byte characters like ASCII and the ASCII-
6898 compatible parts of ISO-8859-X (this is what "$g->strings"
6899 uses).
6900 S Single 8-bit-byte characters.
6902 b 16-bit big endian strings such as those encoded in UTF-16BE or
6904 UCS-2BE.
6905 l (lower case letter L)
6907 16-bit little endian such as UTF-16LE and UCS-2LE. This is
6908 useful for examining binaries in Windows guests.
6909 B 32-bit big endian such as UCS-4BE.
6911 L 32-bit little endian such as UCS-4LE.
6913 The returned strings are transcoded to UTF-8.
6915 The "strings" command has, in the past, had problems with parsing
6917 untrusted files. These are mitigated in the current version of
6918 libguestfs, but see "CVE-2014-8484" in guestfs(3).
6919 Because of the message protocol, there is a transfer limit of
6921 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
6922 guestfs(3).
6923 $g->swapoff_device ($device);
6925 This command disables the libguestfs appliance swap device or
6926 partition named "device". See "$g->swapon_device".
6927 $g->swapoff_file ($file);
6929 This command disables the libguestfs appliance swap on file.
6930 $g->swapoff_label ($label);
6932 This command disables the libguestfs appliance swap on labeled swap
6933 partition.
6934 $g->swapoff_uuid ($uuid);
6936 This command disables the libguestfs appliance swap partition with
6937 the given UUID.
6938 This function depends on the feature "linuxfsuuid". See also
6940 "$g->feature-available".
6941 $g->swapon_device ($device);
6943 This command enables the libguestfs appliance to use the swap
6944 device or partition named "device". The increased memory is made
6945 available for all commands, for example those run using
6946 "$g->command" or "$g->sh".
6947 Note that you should not swap to existing guest swap partitions
6949 unless you know what you are doing. They may contain hibernation
6950 information, or other information that the guest doesn't want you
6951 to trash. You also risk leaking information about the host to the
6952 guest this way. Instead, attach a new host device to the guest and
6953 swap on that.
6954 $g->swapon_file ($file);
6956 This command enables swap to a file. See "$g->swapon_device" for
6957 other notes.
6958 $g->swapon_label ($label);
6960 This command enables swap to a labeled swap partition. See
6961 "$g->swapon_device" for other notes.
6962 $g->swapon_uuid ($uuid);
6964 This command enables swap to a swap partition with the given UUID.
6965 See "$g->swapon_device" for other notes.
6966 This function depends on the feature "linuxfsuuid". See also
6968 "$g->feature-available".
6969 $g->sync ();
6971 This syncs the disk, so that any writes are flushed through to the
6972 underlying disk image.
6973 You should always call this if you have modified a disk image,
6975 before closing the handle.
6976 $g->syslinux ($device [, directory => $directory]);
6978 Install the SYSLINUX bootloader on "device".
6979 The device parameter must be either a whole disk formatted as a FAT
6981 filesystem, or a partition formatted as a FAT filesystem. In the
6982 latter case, the partition should be marked as "active"
6983 ("$g->part_set_bootable") and a Master Boot Record must be
6984 installed (eg. using "$g->pwrite_device") on the first sector of
6985 the whole disk. The SYSLINUX package comes with some suitable
6986 Master Boot Records. See the syslinux(1) man page for further
6987 information.
6988 The optional arguments are:
6990 directory
6992 Install SYSLINUX in the named subdirectory, instead of in the
6993 root directory of the FAT filesystem.
6994 Additional configuration can be supplied to SYSLINUX by placing a
6996 file called syslinux.cfg on the FAT filesystem, either in the root
6997 directory, or under directory if that optional argument is being
6998 used. For further information about the contents of this file, see
6999 syslinux(1).
7000 See also "$g->extlinux".
7002 This function depends on the feature "syslinux". See also
7004 "$g->feature-available".
7005 @lines = $g->tail ($path);
7007 This command returns up to the last 10 lines of a file as a list of
7008 strings.
7009 Because of the message protocol, there is a transfer limit of
7011 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7012 guestfs(3).
7013 @lines = $g->tail_n ($nrlines, $path);
7015 If the parameter "nrlines" is a positive number, this returns the
7016 last "nrlines" lines of the file "path".
7017 If the parameter "nrlines" is a negative number, this returns lines
7019 from the file "path", starting with the "-nrlines"'th line.
7020 If the parameter "nrlines" is zero, this returns an empty list.
7022 Because of the message protocol, there is a transfer limit of
7024 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7025 guestfs(3).
7026 $g->tar_in ($tarfile, $directory [, compress => $compress] [, xattrs =>
7028 $xattrs] [, selinux => $selinux] [, acls => $acls]);
7029 This command uploads and unpacks local file "tarfile" into
7030 directory.
7031 The optional "compress" flag controls compression. If not given,
7033 then the input should be an uncompressed tar file. Otherwise one
7034 of the following strings may be given to select the compression
7035 type of the input file: "compress", "gzip", "bzip2", "xz", "lzop".
7036 (Note that not all builds of libguestfs will support all of these
7037 compression types).
7038 The other optional arguments are:
7040 "xattrs"
7042 If set to true, extended attributes are restored from the tar
7043 file.
7044 "selinux"
7046 If set to true, SELinux contexts are restored from the tar
7047 file.
7048 "acls"
7050 If set to true, POSIX ACLs are restored from the tar file.
7051 $g->tar_in_opts ($tarfile, $directory [, compress => $compress] [,
7053 xattrs => $xattrs] [, selinux => $selinux] [, acls => $acls]);
7054 This is an alias of "tar_in".
7055 $g->tar_out ($directory, $tarfile [, compress => $compress] [,
7057 numericowner => $numericowner] [, excludes => $excludes] [, xattrs =>
7058 $xattrs] [, selinux => $selinux] [, acls => $acls]);
7059 This command packs the contents of directory and downloads it to
7060 local file "tarfile".
7061 The optional "compress" flag controls compression. If not given,
7063 then the output will be an uncompressed tar file. Otherwise one of
7064 the following strings may be given to select the compression type
7065 of the output file: "compress", "gzip", "bzip2", "xz", "lzop".
7066 (Note that not all builds of libguestfs will support all of these
7067 compression types).
7068 The other optional arguments are:
7070 "excludes"
7072 A list of wildcards. Files are excluded if they match any of
7073 the wildcards.
7074 "numericowner"
7076 If set to true, the output tar file will contain UID/GID
7077 numbers instead of user/group names.
7078 "xattrs"
7080 If set to true, extended attributes are saved in the output
7081 tar.
7082 "selinux"
7084 If set to true, SELinux contexts are saved in the output tar.
7085 "acls"
7087 If set to true, POSIX ACLs are saved in the output tar.
7088 $g->tar_out_opts ($directory, $tarfile [, compress => $compress] [,
7090 numericowner => $numericowner] [, excludes => $excludes] [, xattrs =>
7091 $xattrs] [, selinux => $selinux] [, acls => $acls]);
7092 This is an alias of "tar_out".
7093 $g->tgz_in ($tarball, $directory);
7095 This command uploads and unpacks local file "tarball" (a gzip
7096 compressed tar file) into directory.
7097 This function is deprecated. In new code, use the "tar_in" call
7099 instead.
7100 Deprecated functions will not be removed from the API, but the fact
7102 that they are deprecated indicates that there are problems with
7103 correct use of these functions.
7104 $g->tgz_out ($directory, $tarball);
7106 This command packs the contents of directory and downloads it to
7107 local file "tarball".
7108 This function is deprecated. In new code, use the "tar_out" call
7110 instead.
7111 Deprecated functions will not be removed from the API, but the fact
7113 that they are deprecated indicates that there are problems with
7114 correct use of these functions.
7115 $g->touch ($path);
7117 Touch acts like the touch(1) command. It can be used to update the
7118 timestamps on a file, or, if the file does not exist, to create a
7119 new zero-length file.
7120 This command only works on regular files, and will fail on other
7122 file types such as directories, symbolic links, block special etc.
7123 $g->truncate ($path);
7125 This command truncates "path" to a zero-length file. The file must
7126 exist already.
7127 $g->truncate_size ($path, $size);
7129 This command truncates "path" to size "size" bytes. The file must
7130 exist already.
7131 If the current file size is less than "size" then the file is
7133 extended to the required size with zero bytes. This creates a
7134 sparse file (ie. disk blocks are not allocated for the file until
7135 you write to it). To create a non-sparse file of zeroes, use
7136 "$g->fallocate64" instead.
7137 $g->tune2fs ($device [, force => $force] [, maxmountcount =>
7139 $maxmountcount] [, mountcount => $mountcount] [, errorbehavior =>
7140 $errorbehavior] [, group => $group] [, intervalbetweenchecks =>
7141 $intervalbetweenchecks] [, reservedblockspercentage =>
7142 $reservedblockspercentage] [, lastmounteddirectory =>
7143 $lastmounteddirectory] [, reservedblockscount => $reservedblockscount]
7144 [, user => $user]);
7145 This call allows you to adjust various filesystem parameters of an
7146 ext2/ext3/ext4 filesystem called "device".
7147 The optional parameters are:
7149 "force"
7151 Force tune2fs to complete the operation even in the face of
7152 errors. This is the same as the tune2fs(8) "-f" option.
7153 "maxmountcount"
7155 Set the number of mounts after which the filesystem is checked
7156 by e2fsck(8). If this is 0 then the number of mounts is
7157 disregarded. This is the same as the tune2fs(8) "-c" option.
7158 "mountcount"
7160 Set the number of times the filesystem has been mounted. This
7161 is the same as the tune2fs(8) "-C" option.
7162 "errorbehavior"
7164 Change the behavior of the kernel code when errors are
7165 detected. Possible values currently are: "continue",
7166 "remount-ro", "panic". In practice these options don't really
7167 make any difference, particularly for write errors.
7168 This is the same as the tune2fs(8) "-e" option.
7170 "group"
7172 Set the group which can use reserved filesystem blocks. This
7173 is the same as the tune2fs(8) "-g" option except that it can
7174 only be specified as a number.
7175 "intervalbetweenchecks"
7177 Adjust the maximal time between two filesystem checks (in
7178 seconds). If the option is passed as 0 then time-dependent
7179 checking is disabled.
7180 This is the same as the tune2fs(8) "-i" option.
7182 "reservedblockspercentage"
7184 Set the percentage of the filesystem which may only be
7185 allocated by privileged processes. This is the same as the
7186 tune2fs(8) "-m" option.
7187 "lastmounteddirectory"
7189 Set the last mounted directory. This is the same as the
7190 tune2fs(8) "-M" option.
7191 "reservedblockscount" Set the number of reserved filesystem blocks.
7193 This is the same as the tune2fs(8) "-r" option.
7194 "user"
7195 Set the user who can use the reserved filesystem blocks. This
7196 is the same as the tune2fs(8) "-u" option except that it can
7197 only be specified as a number.
7198 To get the current values of filesystem parameters, see
7200 "$g->tune2fs_l". For precise details of how tune2fs works, see the
7201 tune2fs(8) man page.
7202 %superblock = $g->tune2fs_l ($device);
7204 This returns the contents of the ext2, ext3 or ext4 filesystem
7205 superblock on "device".
7206 It is the same as running "tune2fs -l device". See tune2fs(8)
7208 manpage for more details. The list of fields returned isn't
7209 clearly defined, and depends on both the version of "tune2fs" that
7210 libguestfs was built against, and the filesystem itself.
7211 $g->txz_in ($tarball, $directory);
7213 This command uploads and unpacks local file "tarball" (an xz
7214 compressed tar file) into directory.
7215 This function depends on the feature "xz". See also
7217 "$g->feature-available".
7218 This function is deprecated. In new code, use the "tar_in" call
7220 instead.
7221 Deprecated functions will not be removed from the API, but the fact
7223 that they are deprecated indicates that there are problems with
7224 correct use of these functions.
7225 $g->txz_out ($directory, $tarball);
7227 This command packs the contents of directory and downloads it to
7228 local file "tarball" (as an xz compressed tar archive).
7229 This function depends on the feature "xz". See also
7231 "$g->feature-available".
7232 This function is deprecated. In new code, use the "tar_out" call
7234 instead.
7235 Deprecated functions will not be removed from the API, but the fact
7237 that they are deprecated indicates that there are problems with
7238 correct use of these functions.
7239 $oldmask = $g->umask ($mask);
7241 This function sets the mask used for creating new files and device
7242 nodes to "mask & 0777".
7243 Typical umask values would be 022 which creates new files with
7245 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which
7246 creates new files with permissions like "-rw-rw-r--" or
7247 "-rwxrwxr-x".
7248 The default umask is 022. This is important because it means that
7250 directories and device nodes will be created with 0644 or 0755 mode
7251 even if you specify 0777.
7252 See also "$g->get_umask", umask(2), "$g->mknod", "$g->mkdir".
7254 This call returns the previous umask.
7256 $g->umount ($pathordevice [, force => $force] [, lazyunmount =>
7258 $lazyunmount]);
7259 This unmounts the given filesystem. The filesystem may be
7260 specified either by its mountpoint (path) or the device which
7261 contains the filesystem.
7262 $g->umount_opts ($pathordevice [, force => $force] [, lazyunmount =>
7264 $lazyunmount]);
7265 This is an alias of "umount".
7266 $g->umount_all ();
7268 This unmounts all mounted filesystems.
7269 Some internal mounts are not unmounted by this call.
7271 $g->umount_local ([retry => $retry]);
7273 If libguestfs is exporting the filesystem on a local mountpoint,
7274 then this unmounts it.
7275 See "MOUNT LOCAL" in guestfs(3) for full documentation.
7277 $g->upload ($filename, $remotefilename);
7279 Upload local file filename to remotefilename on the filesystem.
7280 filename can also be a named pipe.
7282 See also "$g->download".
7284 $g->upload_offset ($filename, $remotefilename, $offset);
7286 Upload local file filename to remotefilename on the filesystem.
7287 remotefilename is overwritten starting at the byte "offset"
7289 specified. The intention is to overwrite parts of existing files
7290 or devices, although if a non-existent file is specified then it is
7291 created with a "hole" before "offset". The size of the data
7292 written is implicit in the size of the source filename.
7293 Note that there is no limit on the amount of data that can be
7295 uploaded with this call, unlike with "$g->pwrite", and this call
7296 always writes the full amount unless an error occurs.
7297 See also "$g->upload", "$g->pwrite".
7299 $g->user_cancel ();
7301 This function cancels the current upload or download operation.
7302 Unlike most other libguestfs calls, this function is signal safe
7304 and thread safe. You can call it from a signal handler or from
7305 another thread, without needing to do any locking.
7306 The transfer that was in progress (if there is one) will stop
7308 shortly afterwards, and will return an error. The errno (see
7309 "guestfs_last_errno") is set to "EINTR", so you can test for this
7310 to find out if the operation was cancelled or failed because of
7311 another error.
7312 No cleanup is performed: for example, if a file was being uploaded
7314 then after cancellation there may be a partially uploaded file. It
7315 is the callerXs responsibility to clean up if necessary.
7316 There are two common places that you might call "$g->user_cancel":
7318 In an interactive text-based program, you might call it from a
7320 "SIGINT" signal handler so that pressing "^C" cancels the current
7321 operation. (You also need to call "$g->set_pgroup" so that child
7322 processes don't receive the "^C" signal).
7323 In a graphical program, when the main thread is displaying a
7325 progress bar with a cancel button, wire up the cancel button to
7326 call this function.
7327 $g->utimens ($path, $atsecs, $atnsecs, $mtsecs, $mtnsecs);
7329 This command sets the timestamps of a file with nanosecond
7330 precision.
7331 "atsecs", "atnsecs" are the last access time (atime) in secs and
7333 nanoseconds from the epoch.
7334 "mtsecs", "mtnsecs" are the last modification time (mtime) in secs
7336 and nanoseconds from the epoch.
7337 If the *nsecs field contains the special value "-1" then the
7339 corresponding timestamp is set to the current time. (The *secs
7340 field is ignored in this case).
7341 If the *nsecs field contains the special value "-2" then the
7343 corresponding timestamp is left unchanged. (The *secs field is
7344 ignored in this case).
7345 %uts = $g->utsname ();
7347 This returns the kernel version of the appliance, where this is
7348 available. This information is only useful for debugging. Nothing
7349 in the returned structure is defined by the API.
7350 %version = $g->version ();
7352 Return the libguestfs version number that the program is linked
7353 against.
7354 Note that because of dynamic linking this is not necessarily the
7356 version of libguestfs that you compiled against. You can compile
7357 the program, and then at runtime dynamically link against a
7358 completely different libguestfs.so library.
7359 This call was added in version 1.0.58. In previous versions of
7361 libguestfs there was no way to get the version number. From C code
7362 you can use dynamic linker functions to find out if this symbol
7363 exists (if it doesn't, then itXs an earlier version).
7364 The call returns a structure with four elements. The first three
7366 ("major", "minor" and "release") are numbers and correspond to the
7367 usual version triplet. The fourth element ("extra") is a string
7368 and is normally empty, but may be used for distro-specific
7369 information.
7370 To construct the original version string:
7372 "$major.$minor.$release$extra"
7373 See also: "LIBGUESTFS VERSION NUMBERS" in guestfs(3).
7375 Note: Don't use this call to test for availability of features. In
7377 enterprise distributions we backport features from later versions
7378 into earlier versions, making this an unreliable way to test for
7379 features. Use "$g->available" or "$g->feature_available" instead.
7380 $label = $g->vfs_label ($mountable);
7382 This returns the label of the filesystem on "mountable".
7383 If the filesystem is unlabeled, this returns the empty string.
7385 To find a filesystem from the label, use "$g->findfs_label".
7387 $sizeinbytes = $g->vfs_minimum_size ($mountable);
7389 Get the minimum size of filesystem in bytes. This is the minimum
7390 possible size for filesystem shrinking.
7391 If getting minimum size of specified filesystem is not supported,
7393 this will fail and set errno as ENOTSUP.
7394 See also ntfsresize(8), resize2fs(8), btrfs(8), xfs_info(8).
7396 $fstype = $g->vfs_type ($mountable);
7398 This command gets the filesystem type corresponding to the
7399 filesystem on "mountable".
7400 For most filesystems, the result is the name of the Linux VFS
7402 module which would be used to mount this filesystem if you mounted
7403 it without specifying the filesystem type. For example a string
7404 such as "ext3" or "ntfs".
7405 $uuid = $g->vfs_uuid ($mountable);
7407 This returns the filesystem UUID of the filesystem on "mountable".
7408 If the filesystem does not have a UUID, this returns the empty
7410 string.
7411 To find a filesystem from the UUID, use "$g->findfs_uuid".
7413 $g->vg_activate ($activate, \@volgroups);
7415 This command activates or (if "activate" is false) deactivates all
7416 logical volumes in the listed volume groups "volgroups".
7417 This command is the same as running "vgchange -a y|n volgroups..."
7419 Note that if "volgroups" is an empty list then all volume groups
7421 are activated or deactivated.
7422 This function depends on the feature "lvm2". See also
7424 "$g->feature-available".
7425 $g->vg_activate_all ($activate);
7427 This command activates or (if "activate" is false) deactivates all
7428 logical volumes in all volume groups.
7429 This command is the same as running "vgchange -a y|n"
7431 This function depends on the feature "lvm2". See also
7433 "$g->feature-available".
7434 $g->vgchange_uuid ($vg);
7436 Generate a new random UUID for the volume group "vg".
7437 This function depends on the feature "lvm2". See also
7439 "$g->feature-available".
7440 $g->vgchange_uuid_all ();
7442 Generate new random UUIDs for all volume groups.
7443 This function depends on the feature "lvm2". See also
7445 "$g->feature-available".
7446 $g->vgcreate ($volgroup, \@physvols);
7448 This creates an LVM volume group called "volgroup" from the non-
7449 empty list of physical volumes "physvols".
7450 This function depends on the feature "lvm2". See also
7452 "$g->feature-available".
7453 @uuids = $g->vglvuuids ($vgname);
7455 Given a VG called "vgname", this returns the UUIDs of all the
7456 logical volumes created in this volume group.
7457 You can use this along with "$g->lvs" and "$g->lvuuid" calls to
7459 associate logical volumes and volume groups.
7460 See also "$g->vgpvuuids".
7462 $metadata = $g->vgmeta ($vgname);
7464 "vgname" is an LVM volume group. This command examines the volume
7465 group and returns its metadata.
7466 Note that the metadata is an internal structure used by LVM,
7468 subject to change at any time, and is provided for information
7469 only.
7470 This function depends on the feature "lvm2". See also
7472 "$g->feature-available".
7473 @uuids = $g->vgpvuuids ($vgname);
7475 Given a VG called "vgname", this returns the UUIDs of all the
7476 physical volumes that this volume group resides on.
7477 You can use this along with "$g->pvs" and "$g->pvuuid" calls to
7479 associate physical volumes and volume groups.
7480 See also "$g->vglvuuids".
7482 $g->vgremove ($vgname);
7484 Remove an LVM volume group "vgname", (for example "VG").
7485 This also forcibly removes all logical volumes in the volume group
7487 (if any).
7488 This function depends on the feature "lvm2". See also
7490 "$g->feature-available".
7491 $g->vgrename ($volgroup, $newvolgroup);
7493 Rename a volume group "volgroup" with the new name "newvolgroup".
7494 @volgroups = $g->vgs ();
7496 List all the volumes groups detected. This is the equivalent of
7497 the vgs(8) command.
7498 This returns a list of just the volume group names that were
7500 detected (eg. "VolGroup00").
7501 See also "$g->vgs_full".
7503 This function depends on the feature "lvm2". See also
7505 "$g->feature-available".
7506 @volgroups = $g->vgs_full ();
7508 List all the volumes groups detected. This is the equivalent of
7509 the vgs(8) command. The "full" version includes all fields.
7510 This function depends on the feature "lvm2". See also
7512 "$g->feature-available".
7513 $g->vgscan ();
7515 This rescans all block devices and rebuilds the list of LVM
7516 physical volumes, volume groups and logical volumes.
7517 This function is deprecated. In new code, use the "lvm_scan" call
7519 instead.
7520 Deprecated functions will not be removed from the API, but the fact
7522 that they are deprecated indicates that there are problems with
7523 correct use of these functions.
7524 $uuid = $g->vguuid ($vgname);
7526 This command returns the UUID of the LVM VG named "vgname".
7527 $g->wait_ready ();
7529 This function is a no op.
7530 In versions of the API < 1.0.71 you had to call this function just
7532 after calling "$g->launch" to wait for the launch to complete.
7533 However this is no longer necessary because "$g->launch" now does
7534 the waiting.
7535 If you see any calls to this function in code then you can just
7537 remove them, unless you want to retain compatibility with older
7538 versions of the API.
7539 This function is deprecated. There is no replacement. Consult the
7541 API documentation in guestfs(3) for further information.
7542 Deprecated functions will not be removed from the API, but the fact
7544 that they are deprecated indicates that there are problems with
7545 correct use of these functions.
7546 $chars = $g->wc_c ($path);
7548 This command counts the characters in a file, using the "wc -c"
7549 external command.
7550 $lines = $g->wc_l ($path);
7552 This command counts the lines in a file, using the "wc -l" external
7553 command.
7554 $words = $g->wc_w ($path);
7556 This command counts the words in a file, using the "wc -w" external
7557 command.
7558 $g->wipefs ($device);
7560 This command erases filesystem or RAID signatures from the
7561 specified "device" to make the filesystem invisible to libblkid.
7562 This does not erase the filesystem itself nor any other data from
7564 the "device".
7565 Compare with "$g->zero" which zeroes the first few blocks of a
7567 device.
7568 This function depends on the feature "wipefs". See also
7570 "$g->feature-available".
7571 $g->write ($path, $content);
7573 This call creates a file called "path". The content of the file is
7574 the string "content" (which can contain any 8 bit data).
7575 See also "$g->write_append".
7577 $g->write_append ($path, $content);
7579 This call appends "content" to the end of file "path". If "path"
7580 does not exist, then a new file is created.
7581 See also "$g->write".
7583 $g->write_file ($path, $content, $size);
7585 This call creates a file called "path". The contents of the file
7586 is the string "content" (which can contain any 8 bit data), with
7587 length "size".
7588 As a special case, if "size" is 0 then the length is calculated
7590 using "strlen" (so in this case the content cannot contain embedded
7591 ASCII NULs).
7592 NB. Owing to a bug, writing content containing ASCII NUL characters
7594 does not work, even if the length is specified.
7595 Because of the message protocol, there is a transfer limit of
7597 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7598 guestfs(3).
7599 This function is deprecated. In new code, use the "write" call
7601 instead.
7602 Deprecated functions will not be removed from the API, but the fact
7604 that they are deprecated indicates that there are problems with
7605 correct use of these functions.
7606 $g->xfs_admin ($device [, extunwritten => $extunwritten] [, imgfile =>
7608 $imgfile] [, v2log => $v2log] [, projid32bit => $projid32bit] [,
7609 lazycounter => $lazycounter] [, label => $label] [, uuid => $uuid]);
7610 Change the parameters of the XFS filesystem on "device".
7611 Devices that are mounted cannot be modified. Administrators must
7613 unmount filesystems before this call can modify parameters.
7614 Some of the parameters of a mounted filesystem can be examined and
7616 modified using the "$g->xfs_info" and "$g->xfs_growfs" calls.
7617 This function depends on the feature "xfs". See also
7619 "$g->feature-available".
7620 $g->xfs_growfs ($path [, datasec => $datasec] [, logsec => $logsec] [,
7622 rtsec => $rtsec] [, datasize => $datasize] [, logsize => $logsize] [,
7623 rtsize => $rtsize] [, rtextsize => $rtextsize] [, maxpct => $maxpct]);
7624 Grow the XFS filesystem mounted at "path".
7625 The returned struct contains geometry information. Missing fields
7627 are returned as "-1" (for numeric fields) or empty string.
7628 This function depends on the feature "xfs". See also
7630 "$g->feature-available".
7631 %info = $g->xfs_info ($pathordevice);
7633 "pathordevice" is a mounted XFS filesystem or a device containing
7634 an XFS filesystem. This command returns the geometry of the
7635 filesystem.
7636 The returned struct contains geometry information. Missing fields
7638 are returned as "-1" (for numeric fields) or empty string.
7639 This function depends on the feature "xfs". See also
7641 "$g->feature-available".
7642 $status = $g->xfs_repair ($device [, forcelogzero => $forcelogzero] [,
7644 nomodify => $nomodify] [, noprefetch => $noprefetch] [, forcegeometry
7645 => $forcegeometry] [, maxmem => $maxmem] [, ihashsize => $ihashsize] [,
7646 bhashsize => $bhashsize] [, agstride => $agstride] [, logdev =>
7647 $logdev] [, rtdev => $rtdev]);
7648 Repair corrupt or damaged XFS filesystem on "device".
7649 The filesystem is specified using the "device" argument which
7651 should be the device name of the disk partition or volume
7652 containing the filesystem. If given the name of a block device,
7653 "xfs_repair" will attempt to find the raw device associated with
7654 the specified block device and will use the raw device instead.
7655 Regardless, the filesystem to be repaired must be unmounted,
7657 otherwise, the resulting filesystem may be inconsistent or corrupt.
7658 The returned status indicates whether filesystem corruption was
7660 detected (returns 1) or was not detected (returns 0).
7661 This function depends on the feature "xfs". See also
7663 "$g->feature-available".
7664 $g->yara_destroy ();
7666 Destroy previously loaded Yara rules in order to free libguestfs
7667 resources.
7668 This function depends on the feature "libyara". See also
7670 "$g->feature-available".
7671 $g->yara_load ($filename);
7673 Upload a set of Yara rules from local file filename.
7674 Yara rules allow to categorize files based on textual or binary
7676 patterns within their content. See "$g->yara_scan" to see how to
7677 scan files with the loaded rules.
7678 Rules can be in binary format, as when compiled with yarac command,
7680 or in source code format. In the latter case, the rules will be
7681 first compiled and then loaded.
7682 Rules in source code format cannot include external files. In such
7684 cases, it is recommended to compile them first.
7685 Previously loaded rules will be destroyed.
7687 This function depends on the feature "libyara". See also
7689 "$g->feature-available".
7690 @detections = $g->yara_scan ($path);
7692 Scan a file with the previously loaded Yara rules.
7693 For each matching rule, a "yara_detection" structure is returned.
7695 The "yara_detection" structure contains the following fields.
7697 "yara_name"
7699 Path of the file matching a Yara rule.
7700 "yara_rule"
7702 Identifier of the Yara rule which matched against the given
7703 file.
7704 This function depends on the feature "libyara". See also
7706 "$g->feature-available".
7707 @lines = $g->zegrep ($regex, $path);
7709 This calls the external "zegrep" program and returns the matching
7710 lines.
7711 Because of the message protocol, there is a transfer limit of
7713 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7714 guestfs(3).
7715 This function is deprecated. In new code, use the "grep" call
7717 instead.
7718 Deprecated functions will not be removed from the API, but the fact
7720 that they are deprecated indicates that there are problems with
7721 correct use of these functions.
7722 @lines = $g->zegrepi ($regex, $path);
7724 This calls the external "zegrep -i" program and returns the
7725 matching lines.
7726 Because of the message protocol, there is a transfer limit of
7728 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7729 guestfs(3).
7730 This function is deprecated. In new code, use the "grep" call
7732 instead.
7733 Deprecated functions will not be removed from the API, but the fact
7735 that they are deprecated indicates that there are problems with
7736 correct use of these functions.
7737 $g->zero ($device);
7739 This command writes zeroes over the first few blocks of "device".
7740 How many blocks are zeroed isn't specified (but itXs not enough to
7742 securely wipe the device). It should be sufficient to remove any
7743 partition tables, filesystem superblocks and so on.
7744 If blocks are already zero, then this command avoids writing
7746 zeroes. This prevents the underlying device from becoming non-
7747 sparse or growing unnecessarily.
7748 See also: "$g->zero_device", "$g->scrub_device",
7750 "$g->is_zero_device"
7751 $g->zero_device ($device);
7753 This command writes zeroes over the entire "device". Compare with
7754 "$g->zero" which just zeroes the first few blocks of a device.
7755 If blocks are already zero, then this command avoids writing
7757 zeroes. This prevents the underlying device from becoming non-
7758 sparse or growing unnecessarily.
7759 $g->zero_free_space ($directory);
7761 Zero the free space in the filesystem mounted on directory. The
7762 filesystem must be mounted read-write.
7763 The filesystem contents are not affected, but any free space in the
7765 filesystem is freed.
7766 Free space is not "trimmed". You may want to call "$g->fstrim"
7768 either as an alternative to this, or after calling this, depending
7769 on your requirements.
7770 $g->zerofree ($device);
7772 This runs the zerofree program on "device". This program claims to
7773 zero unused inodes and disk blocks on an ext2/3 filesystem, thus
7774 making it possible to compress the filesystem more effectively.
7775 You should not run this program if the filesystem is mounted.
7777 It is possible that using this program can damage the filesystem or
7779 data on the filesystem.
7780 This function depends on the feature "zerofree". See also
7782 "$g->feature-available".
7783 @lines = $g->zfgrep ($pattern, $path);
7785 This calls the external "zfgrep" program and returns the matching
7786 lines.
7787 Because of the message protocol, there is a transfer limit of
7789 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7790 guestfs(3).
7791 This function is deprecated. In new code, use the "grep" call
7793 instead.
7794 Deprecated functions will not be removed from the API, but the fact
7796 that they are deprecated indicates that there are problems with
7797 correct use of these functions.
7798 @lines = $g->zfgrepi ($pattern, $path);
7800 This calls the external "zfgrep -i" program and returns the
7801 matching lines.
7802 Because of the message protocol, there is a transfer limit of
7804 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7805 guestfs(3).
7806 This function is deprecated. In new code, use the "grep" call
7808 instead.
7809 Deprecated functions will not be removed from the API, but the fact
7811 that they are deprecated indicates that there are problems with
7812 correct use of these functions.
7813 $description = $g->zfile ($meth, $path);
7815 This command runs file(1) after first decompressing "path" using
7816 "meth".
7817 "meth" must be one of "gzip", "compress" or "bzip2".
7819 Since 1.0.63, use "$g->file" instead which can now process
7821 compressed files.
7822 This function is deprecated. In new code, use the "file" call
7824 instead.
7825 Deprecated functions will not be removed from the API, but the fact
7827 that they are deprecated indicates that there are problems with
7828 correct use of these functions.
7829 @lines = $g->zgrep ($regex, $path);
7831 This calls the external zgrep(1) program and returns the matching
7832 lines.
7833 Because of the message protocol, there is a transfer limit of
7835 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7836 guestfs(3).
7837 This function is deprecated. In new code, use the "grep" call
7839 instead.
7840 Deprecated functions will not be removed from the API, but the fact
7842 that they are deprecated indicates that there are problems with
7843 correct use of these functions.
7844 @lines = $g->zgrepi ($regex, $path);
7846 This calls the external "zgrep -i" program and returns the matching
7847 lines.
7848 Because of the message protocol, there is a transfer limit of
7850 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7851 guestfs(3).
7852 This function is deprecated. In new code, use the "grep" call
7854 instead.
7855 Deprecated functions will not be removed from the API, but the fact
7857 that they are deprecated indicates that there are problems with
7858 correct use of these functions.
7859
7861 From time to time we add new libguestfs APIs. Also some libguestfs
7862 APIs won't be available in all builds of libguestfs (the Fedora build
7863 is full-featured, but other builds may disable features). How do you
7864 test whether the APIs that your Perl program needs are available in the
7865 version of "Sys::Guestfs" that you are using?
7866 To test if a particular function is available in the "Sys::Guestfs"
7868 class, use the ordinary Perl UNIVERSAL method "can(METHOD)" (see
7869 perlobj(1)). For example:
7870 use Sys::Guestfs;
7872 if (defined (Sys::Guestfs->can ("set_verbose"))) {
7873 print "\$g->set_verbose is available\n";
7874 }
7875 To test if particular features are supported by the current build, use
7877 the "feature_available" method like the example below. Note that the
7878 appliance must be launched first.
7879 $g->feature_available ( ["augeas"] );
7881 For further discussion on this topic, refer to "AVAILABILITY" in
7883 guestfs(3).
7884
7886 The handle returned from "new" is a hash reference. The hash normally
7887 contains some elements:
7888 {
7890 _g => [private data used by libguestfs],
7891 _flags => [flags provided when creating the handle]
7892 }
7893 Callers can add other elements to this hash to store data for their own
7895 purposes. The data lasts for the lifetime of the handle.
7896 Any fields whose names begin with an underscore are reserved for
7898 private use by libguestfs. We may add more in future.
7899 It is recommended that callers prefix the name of their field(s) with
7901 some unique string, to avoid conflicts with other users.
7902
7904 Copyright (C) 2009-2020 Red Hat Inc.
7905
7907 Please see the file COPYING.LIB for the full license.
7908
7910 guestfs(3), guestfish(1), <http://libguestfs.org>.
7911perl v5.34.0 2021-09-23 Sys::Guestfs(3)