1Sys::Guestfs(3pm) User Contributed Perl Documentation Sys::Guestfs(3pm)
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 is ignored in libguestfs ≥ 1.48.
257 If the "allowuuid" flag is true (default is false) then a UUID may
259 be passed instead of the domain name. The "dom" string is treated
260 as a UUID first and looked up, and if that lookup fails then we
261 treat "dom" as a name as usual.
262 The optional "readonlydisk" parameter controls what we do for disks
264 which are marked <readonly/> in the libvirt XML. Possible values
265 are:
266 readonlydisk = "error"
268 If "readonly" is false:
269 The whole call is aborted with an error if any disk with the
271 <readonly/> flag is found.
272 If "readonly" is true:
274 Disks with the <readonly/> flag are added read-only.
276 readonlydisk = "read"
278 If "readonly" is false:
279 Disks with the <readonly/> flag are added read-only. Other
281 disks are added read/write.
282 If "readonly" is true:
284 Disks with the <readonly/> flag are added read-only.
286 readonlydisk = "write" (default)
288 If "readonly" is false:
289 Disks with the <readonly/> flag are added read/write.
291 If "readonly" is true:
293 Disks with the <readonly/> flag are added read-only.
295 readonlydisk = "ignore"
297 If "readonly" is true or false:
298 Disks with the <readonly/> flag are skipped.
300 If present, the value of "logical_block_size" attribute of
302 <blockio/> tag in libvirt XML will be passed as "blocksize"
303 parameter to "$g->add_drive_opts".
304 The other optional parameters are passed directly through to
306 "$g->add_drive_opts".
307 $g->add_drive ($filename [, readonly => $readonly] [, format =>
309 $format] [, iface => $iface] [, name => $name] [, label => $label] [,
310 protocol => $protocol] [, server => $server] [, username => $username]
311 [, secret => $secret] [, cachemode => $cachemode] [, discard =>
312 $discard] [, copyonread => $copyonread] [, blocksize => $blocksize]);
313 This function adds a disk image called filename to the handle.
314 filename may be a regular host file or a host device.
315 When this function is called before "$g->launch" (the usual case)
317 then the first time you call this function, the disk appears in the
318 API as /dev/sda, the second time as /dev/sdb, and so on.
319 You don't necessarily need to be root when using libguestfs.
321 However you obviously do need sufficient permissions to access the
322 filename for whatever operations you want to perform (ie. read
323 access if you just want to read the image or write access if you
324 want to modify the image).
325 This call checks that filename exists.
327 filename may be the special string "/dev/null". See "NULL DISKS"
329 in guestfs(3).
330 The optional arguments are:
332 "readonly"
334 If true then the image is treated as read-only. Writes are
335 still allowed, but they are stored in a temporary snapshot
336 overlay which is discarded at the end. The disk that you add
337 is not modified.
338 "format"
340 This forces the image format. If you omit this (or use
341 "$g->add_drive" or "$g->add_drive_ro") then the format is
342 automatically detected. Possible formats include "raw" and
343 "qcow2".
344 Automatic detection of the format opens you up to a potential
346 security hole when dealing with untrusted raw-format images.
347 See CVE-2010-3851 and RHBZ#642934. Specifying the format
348 closes this security hole.
349 "iface"
351 This rarely-used option lets you emulate the behaviour of the
352 deprecated "$g->add_drive_with_if" call (q.v.)
353 "name"
355 This field used to be passed as a hint for guest inspection,
356 but it is no longer used.
357 "label"
359 Give the disk a label. The label should be a unique, short
360 string using only ASCII characters "[a-zA-Z]". As well as its
361 usual name in the API (such as /dev/sda), the drive will also
362 be named /dev/disk/guestfs/label.
363 See "DISK LABELS" in guestfs(3).
365 "protocol"
367 The optional protocol argument can be used to select an
368 alternate source protocol.
369 See also: "REMOTE STORAGE" in guestfs(3).
371 "protocol = "file""
373 filename is interpreted as a local file or device. This is
374 the default if the optional protocol parameter is omitted.
375 "protocol = "ftp"|"ftps"|"http"|"https"|"tftp""
377 Connect to a remote FTP, HTTP or TFTP server. The "server"
378 parameter must also be supplied - see below.
379 See also: "FTP, HTTP AND TFTP" in guestfs(3)
381 "protocol = "gluster""
383 Connect to the GlusterFS server. The "server" parameter
384 must also be supplied - see below.
385 See also: "GLUSTER" in guestfs(3)
387 "protocol = "iscsi""
389 Connect to the iSCSI server. The "server" parameter must
390 also be supplied - see below. The "username" parameter may
391 be supplied. See below. The "secret" parameter may be
392 supplied. See below.
393 See also: "ISCSI" in guestfs(3).
395 "protocol = "nbd""
397 Connect to the Network Block Device server. The "server"
398 parameter must also be supplied - see below.
399 See also: "NETWORK BLOCK DEVICE" in guestfs(3).
401 "protocol = "rbd""
403 Connect to the Ceph (librbd/RBD) server. The "server"
404 parameter must also be supplied - see below. The
405 "username" parameter may be supplied. See below. The
406 "secret" parameter may be supplied. See below.
407 See also: "CEPH" in guestfs(3).
409 "protocol = "sheepdog""
411 Connect to the Sheepdog server. The "server" parameter may
412 also be supplied - see below.
413 See also: "SHEEPDOG" in guestfs(3).
415 "protocol = "ssh""
417 Connect to the Secure Shell (ssh) server.
418 The "server" parameter must be supplied. The "username"
420 parameter may be supplied. See below.
421 See also: "SSH" in guestfs(3).
423 "server"
425 For protocols which require access to a remote server, this is
426 a list of server(s).
427 Protocol Number of servers required
429 -------- --------------------------
430 file List must be empty or param not used at all
431 ftp|ftps|http|https|tftp Exactly one
432 gluster Exactly one
433 iscsi Exactly one
434 nbd Exactly one
435 rbd Zero or more
436 sheepdog Zero or more
437 ssh Exactly one
438 Each list element is a string specifying a server. The string
440 must be in one of the following formats:
441 hostname
443 hostname:port
444 tcp:hostname
445 tcp:hostname:port
446 unix:/path/to/socket
447 If the port number is omitted, then the standard port number
449 for the protocol is used (see /etc/services).
450 "username"
452 For the "ftp", "ftps", "http", "https", "iscsi", "rbd", "ssh"
453 and "tftp" protocols, this specifies the remote username.
454 If not given, then the local username is used for "ssh", and no
456 authentication is attempted for ceph. But note this sometimes
457 may give unexpected results, for example if using the libvirt
458 backend and if the libvirt backend is configured to start the
459 qemu appliance as a special user such as "qemu.qemu". If in
460 doubt, specify the remote username you want.
461 "secret"
463 For the "rbd" protocol only, this specifies the ‘secret’ to use
464 when connecting to the remote device. It must be base64
465 encoded.
466 If not given, then a secret matching the given username will be
468 looked up in the default keychain locations, or if no username
469 is given, then no authentication will be used.
470 "cachemode"
472 Choose whether or not libguestfs will obey sync operations
473 (safe but slow) or not (unsafe but fast). The possible values
474 for this string are:
475 "cachemode = "writeback""
477 This is the default.
478 Write operations in the API do not return until a write(2)
480 call has completed in the host [but note this does not
481 imply that anything gets written to disk].
482 Sync operations in the API, including implicit syncs caused
484 by filesystem journalling, will not return until an
485 fdatasync(2) call has completed in the host, indicating
486 that data has been committed to disk.
487 "cachemode = "unsafe""
489 In this mode, there are no guarantees. Libguestfs may
490 cache anything and ignore sync requests. This is suitable
491 only for scratch or temporary disks.
492 "discard"
494 Enable or disable discard (a.k.a. trim or unmap) support on
495 this drive. If enabled, operations such as "$g->fstrim" will
496 be able to discard / make thin / punch holes in the underlying
497 host file or device.
498 Possible discard settings are:
500 "discard = "disable""
502 Disable discard support. This is the default.
503 "discard = "enable""
505 Enable discard support. Fail if discard is not possible.
506 "discard = "besteffort""
508 Enable discard support if possible, but don't fail if it is
509 not supported.
510 Since not all backends and not all underlying systems
512 support discard, this is a good choice if you want to use
513 discard if possible, but don't mind if it doesn't work.
514 "copyonread"
516 The boolean parameter "copyonread" enables copy-on-read
517 support. This only affects disk formats which have backing
518 files, and causes reads to be stored in the overlay layer,
519 speeding up multiple reads of the same area of disk.
520 The default is false.
522 "blocksize"
524 This parameter sets the sector size of the disk. Possible
525 values are 512 (the default if the parameter is omitted) or
526 4096. Use 4096 when handling an "Advanced Format" disk that
527 uses 4K sector size
528 (<https://en.wikipedia.org/wiki/Advanced_Format>).
529 Only a subset of the backends support this parameter (currently
531 only the libvirt and direct backends do).
532 $g->add_drive_opts ($filename [, readonly => $readonly] [, format =>
534 $format] [, iface => $iface] [, name => $name] [, label => $label] [,
535 protocol => $protocol] [, server => $server] [, username => $username]
536 [, secret => $secret] [, cachemode => $cachemode] [, discard =>
537 $discard] [, copyonread => $copyonread] [, blocksize => $blocksize]);
538 This is an alias of "add_drive".
539 $g->add_drive_ro ($filename);
541 This function is the equivalent of calling "$g->add_drive_opts"
542 with the optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set
543 to 1, so the disk is added read-only, with the format being
544 detected automatically.
545 $g->add_drive_ro_with_if ($filename, $iface);
547 This is the same as "$g->add_drive_ro" but it allows you to specify
548 the QEMU interface emulation to use at run time. Both the direct
549 and the libvirt backends ignore "iface".
550 This function is deprecated. In new code, use the "add_drive" call
552 instead.
553 Deprecated functions will not be removed from the API, but the fact
555 that they are deprecated indicates that there are problems with
556 correct use of these functions.
557 $g->add_drive_scratch ($size [, name => $name] [, label => $label] [,
559 blocksize => $blocksize]);
560 This command adds a temporary scratch drive to the handle. The
561 "size" parameter is the virtual size (in bytes). The scratch drive
562 is blank initially (all reads return zeroes until you start writing
563 to it). The drive is deleted when the handle is closed.
564 The optional arguments "name", "label" and "blocksize" are passed
566 through to "$g->add_drive_opts".
567 $g->add_drive_with_if ($filename, $iface);
569 This is the same as "$g->add_drive" but it allows you to specify
570 the QEMU interface emulation to use at run time. Both the direct
571 and the libvirt backends ignore "iface".
572 This function is deprecated. In new code, use the "add_drive" call
574 instead.
575 Deprecated functions will not be removed from the API, but the fact
577 that they are deprecated indicates that there are problems with
578 correct use of these functions.
579 $nrdisks = $g->add_libvirt_dom ($dom [, readonly => $readonly] [, iface
581 => $iface] [, live => $live] [, readonlydisk => $readonlydisk] [,
582 cachemode => $cachemode] [, discard => $discard] [, copyonread =>
583 $copyonread]);
584 This function adds the disk(s) attached to the libvirt domain
585 "dom". It works by requesting the domain XML from libvirt, parsing
586 it for disks, and calling "$g->add_drive_opts" on each one.
587 In the C API we declare "void *dom", but really it has type
589 "virDomainPtr dom". This is so we don't need <libvirt.h>.
590 The number of disks added is returned. This operation is atomic:
592 if an error is returned, then no disks are added.
593 This function does some minimal checks to make sure the libvirt
595 domain is not running (unless "readonly" is true). In a future
596 version we will try to acquire the libvirt lock on each disk.
597 Disks must be accessible locally. This often means that adding
599 disks from a remote libvirt connection (see
600 <https://libvirt.org/remote.html>) will fail unless those disks are
601 accessible via the same device path locally too.
602 The optional "live" flag is ignored in libguestfs ≥ 1.48.
604 The optional "readonlydisk" parameter controls what we do for disks
606 which are marked <readonly/> in the libvirt XML. See
607 "$g->add_domain" for possible values.
608 If present, the value of "logical_block_size" attribute of
610 <blockio/> tag in libvirt XML will be passed as "blocksize"
611 parameter to "$g->add_drive_opts".
612 The other optional parameters are passed directly through to
614 "$g->add_drive_opts".
615 $g->aug_clear ($augpath);
617 Set the value associated with "path" to "NULL". This is the same
618 as the augtool(1) "clear" command.
619 $g->aug_close ();
621 Close the current Augeas handle and free up any resources used by
622 it. After calling this, you have to call "$g->aug_init" again
623 before you can use any other Augeas functions.
624 %nrnodescreated = $g->aug_defnode ($name, $expr, $val);
626 Defines a variable "name" whose value is the result of evaluating
627 "expr".
628 If "expr" evaluates to an empty nodeset, a node is created,
630 equivalent to calling "$g->aug_set" "expr", "val". "name" will be
631 the nodeset containing that single node.
632 On success this returns a pair containing the number of nodes in
634 the nodeset, and a boolean flag if a node was created.
635 $nrnodes = $g->aug_defvar ($name, $expr);
637 Defines an Augeas variable "name" whose value is the result of
638 evaluating "expr". If "expr" is NULL, then "name" is undefined.
639 On success this returns the number of nodes in "expr", or 0 if
641 "expr" evaluates to something which is not a nodeset.
642 $val = $g->aug_get ($augpath);
644 Look up the value associated with "path". If "path" matches
645 exactly one node, the "value" is returned.
646 $g->aug_init ($root, $flags);
648 Create a new Augeas handle for editing configuration files. If
649 there was any previous Augeas handle associated with this guestfs
650 session, then it is closed.
651 You must call this before using any other "$g->aug_*" commands.
653 "root" is the filesystem root. "root" must not be NULL, use /
655 instead.
656 The flags are the same as the flags defined in <augeas.h>, the
658 logical or of the following integers:
659 "AUG_SAVE_BACKUP" = 1
661 Keep the original file with a ".augsave" extension.
662 "AUG_SAVE_NEWFILE" = 2
664 Save changes into a file with extension ".augnew", and do not
665 overwrite original. Overrides "AUG_SAVE_BACKUP".
666 "AUG_TYPE_CHECK" = 4
668 Typecheck lenses.
669 This option is only useful when debugging Augeas lenses. Use
671 of this option may require additional memory for the libguestfs
672 appliance. You may need to set the "LIBGUESTFS_MEMSIZE"
673 environment variable or call "$g->set_memsize".
674 "AUG_NO_STDINC" = 8
676 Do not use standard load path for modules.
677 "AUG_SAVE_NOOP" = 16
679 Make save a no-op, just record what would have been changed.
680 "AUG_NO_LOAD" = 32
682 Do not load the tree in "$g->aug_init".
683 To close the handle, you can call "$g->aug_close".
685 To find out more about Augeas, see <http://augeas.net/>.
687 $g->aug_insert ($augpath, $label, $before);
689 Create a new sibling "label" for "path", inserting it into the tree
690 before or after "path" (depending on the boolean flag "before").
691 "path" must match exactly one existing node in the tree, and
693 "label" must be a label, ie. not contain /, "*" or end with a
694 bracketed index "[N]".
695 $label = $g->aug_label ($augpath);
697 The label (name of the last element) of the Augeas path expression
698 "augpath" is returned. "augpath" must match exactly one node, else
699 this function returns an error.
700 $g->aug_load ();
702 Load files into the tree.
703 See "aug_load" in the Augeas documentation for the full gory
705 details.
706 @matches = $g->aug_ls ($augpath);
708 This is just a shortcut for listing "$g->aug_match" "path/*" and
709 sorting the resulting nodes into alphabetical order.
710 @matches = $g->aug_match ($augpath);
712 Returns a list of paths which match the path expression "path".
713 The returned paths are sufficiently qualified so that they match
714 exactly one node in the current tree.
715 $g->aug_mv ($src, $dest);
717 Move the node "src" to "dest". "src" must match exactly one node.
718 "dest" is overwritten if it exists.
719 $nrnodes = $g->aug_rm ($augpath);
721 Remove "path" and all of its children.
722 On success this returns the number of entries which were removed.
724 $g->aug_save ();
726 This writes all pending changes to disk.
727 The flags which were passed to "$g->aug_init" affect exactly how
729 files are saved.
730 $g->aug_set ($augpath, $val);
732 Set the value associated with "augpath" to "val".
733 In the Augeas API, it is possible to clear a node by setting the
735 value to NULL. Due to an oversight in the libguestfs API you
736 cannot do that with this call. Instead you must use the
737 "$g->aug_clear" call.
738 $nodes = $g->aug_setm ($base, $sub, $val);
740 Change multiple Augeas nodes in a single operation. "base" is an
741 expression matching multiple nodes. "sub" is a path expression
742 relative to "base". All nodes matching "base" are found, and then
743 for each node, "sub" is changed to "val". "sub" may also be "NULL"
744 in which case the "base" nodes are modified.
745 This returns the number of nodes modified.
747 $g->aug_transform ($lens, $file [, remove => $remove]);
749 Add an Augeas transformation for the specified "lens" so it can
750 handle "file".
751 If "remove" is true ("false" by default), then the transformation
753 is removed.
754 $g->available (\@groups);
756 This command is used to check the availability of some groups of
757 functionality in the appliance, which not all builds of the
758 libguestfs appliance will be able to provide.
759 The libguestfs groups, and the functions that those groups
761 correspond to, are listed in "AVAILABILITY" in guestfs(3). You can
762 also fetch this list at runtime by calling
763 "$g->available_all_groups".
764 The argument "groups" is a list of group names, eg: "["inotify",
766 "augeas"]" would check for the availability of the Linux inotify
767 functions and Augeas (configuration file editing) functions.
768 The command returns no error if all requested groups are available.
770 It fails with an error if one or more of the requested groups is
772 unavailable in the appliance.
773 If an unknown group name is included in the list of groups then an
775 error is always returned.
776 Notes:
778 • "$g->feature_available" is the same as this call, but with a
780 slightly simpler to use API: that call returns a boolean
781 true/false instead of throwing an error.
782 • You must call "$g->launch" before calling this function.
784 The reason is because we don't know what groups are supported
786 by the appliance/daemon until it is running and can be queried.
787 • If a group of functions is available, this does not necessarily
789 mean that they will work. You still have to check for errors
790 when calling individual API functions even if they are
791 available.
792 • It is usually the job of distro packagers to build complete
794 functionality into the libguestfs appliance. Upstream
795 libguestfs, if built from source with all requirements
796 satisfied, will support everything.
797 • This call was added in version 1.0.80. In previous versions of
799 libguestfs all you could do would be to speculatively execute a
800 command to find out if the daemon implemented it. See also
801 "$g->version".
802 See also "$g->filesystem_available".
804 @groups = $g->available_all_groups ();
806 This command returns a list of all optional groups that this daemon
807 knows about. Note this returns both supported and unsupported
808 groups. To find out which ones the daemon can actually support you
809 have to call "$g->available" / "$g->feature_available" on each
810 member of the returned list.
811 See also "$g->available", "$g->feature_available" and
813 "AVAILABILITY" in guestfs(3).
814 $g->base64_in ($base64file, $filename);
816 This command uploads base64-encoded data from "base64file" to
817 filename.
818 $g->base64_out ($filename, $base64file);
820 This command downloads the contents of filename, writing it out to
821 local file "base64file" encoded as base64.
822 $g->blkdiscard ($device);
824 This discards all blocks on the block device "device", giving the
825 free space back to the host.
826 This operation requires support in libguestfs, the host filesystem,
828 qemu and the host kernel. If this support isn't present it may
829 give an error or even appear to run but do nothing. You must also
830 set the "discard" attribute on the underlying drive (see
831 "$g->add_drive_opts").
832 This function depends on the feature "blkdiscard". See also
834 "$g->feature-available".
835 $zeroes = $g->blkdiscardzeroes ($device);
837 This call returns true if blocks on "device" that have been
838 discarded by a call to "$g->blkdiscard" are returned as blocks of
839 zero bytes when read the next time.
840 If it returns false, then it may be that discarded blocks are read
842 as stale or random data.
843 This function depends on the feature "blkdiscardzeroes". See also
845 "$g->feature-available".
846 %info = $g->blkid ($device);
848 This command returns block device attributes for "device". The
849 following fields are usually present in the returned hash. Other
850 fields may also be present.
851 "UUID"
853 The uuid of this device.
854 "LABEL"
856 The label of this device.
857 "VERSION"
859 The version of blkid command.
860 "TYPE"
862 The filesystem type or RAID of this device.
863 "USAGE"
865 The usage of this device, for example "filesystem" or "raid".
866 $g->blockdev_flushbufs ($device);
868 This tells the kernel to flush internal buffers associated with
869 "device".
870 This uses the blockdev(8) command.
872 $blocksize = $g->blockdev_getbsz ($device);
874 This returns the block size of a device.
875 Note: this is different from both size in blocks and filesystem
877 block size. Also this setting is not really used by anything. You
878 should probably not use it for anything. Filesystems have their
879 own idea about what block size to choose.
880 This uses the blockdev(8) command.
882 $ro = $g->blockdev_getro ($device);
884 Returns a boolean indicating if the block device is read-only (true
885 if read-only, false if not).
886 This uses the blockdev(8) command.
888 $sizeinbytes = $g->blockdev_getsize64 ($device);
890 This returns the size of the device in bytes.
891 See also "$g->blockdev_getsz".
893 This uses the blockdev(8) command.
895 $sectorsize = $g->blockdev_getss ($device);
897 This returns the size of sectors on a block device. Usually 512,
898 but can be larger for modern devices.
899 (Note, this is not the size in sectors, use "$g->blockdev_getsz"
901 for that).
902 This uses the blockdev(8) command.
904 $sizeinsectors = $g->blockdev_getsz ($device);
906 This returns the size of the device in units of 512-byte sectors
907 (even if the sectorsize isn't 512 bytes ... weird).
908 See also "$g->blockdev_getss" for the real sector size of the
910 device, and "$g->blockdev_getsize64" for the more useful size in
911 bytes.
912 This uses the blockdev(8) command.
914 $g->blockdev_rereadpt ($device);
916 Reread the partition table on "device".
917 This uses the blockdev(8) command.
919 $g->blockdev_setbsz ($device, $blocksize);
921 This call does nothing and has never done anything because of a bug
922 in blockdev. Do not use it.
923 If you need to set the filesystem block size, use the "blocksize"
925 option of "$g->mkfs".
926 This function is deprecated. There is no replacement. Consult the
928 API documentation in guestfs(3) for further information.
929 Deprecated functions will not be removed from the API, but the fact
931 that they are deprecated indicates that there are problems with
932 correct use of these functions.
933 $g->blockdev_setra ($device, $sectors);
935 Set readahead (in 512-byte sectors) for the device.
936 This uses the blockdev(8) command.
938 $g->blockdev_setro ($device);
940 Sets the block device named "device" to read-only.
941 This uses the blockdev(8) command.
943 $g->blockdev_setrw ($device);
945 Sets the block device named "device" to read-write.
946 This uses the blockdev(8) command.
948 $g->btrfs_balance_cancel ($path);
950 Cancel a running balance on a btrfs filesystem.
951 This function depends on the feature "btrfs". See also
953 "$g->feature-available".
954 $g->btrfs_balance_pause ($path);
956 Pause a running balance on a btrfs filesystem.
957 This function depends on the feature "btrfs". See also
959 "$g->feature-available".
960 $g->btrfs_balance_resume ($path);
962 Resume a paused balance on a btrfs filesystem.
963 This function depends on the feature "btrfs". See also
965 "$g->feature-available".
966 %status = $g->btrfs_balance_status ($path);
968 Show the status of a running or paused balance on a btrfs
969 filesystem.
970 This function depends on the feature "btrfs". See also
972 "$g->feature-available".
973 $g->btrfs_device_add (\@devices, $fs);
975 Add the list of device(s) in "devices" to the btrfs filesystem
976 mounted at "fs". If "devices" is an empty list, this does nothing.
977 This function depends on the feature "btrfs". See also
979 "$g->feature-available".
980 $g->btrfs_device_delete (\@devices, $fs);
982 Remove the "devices" from the btrfs filesystem mounted at "fs". If
983 "devices" is an empty list, this does nothing.
984 This function depends on the feature "btrfs". See also
986 "$g->feature-available".
987 $g->btrfs_filesystem_balance ($fs);
989 Balance the chunks in the btrfs filesystem mounted at "fs" across
990 the underlying devices.
991 This function depends on the feature "btrfs". See also
993 "$g->feature-available".
994 $g->btrfs_filesystem_defragment ($path [, flush => $flush] [, compress
996 => $compress]);
997 Defragment a file or directory on a btrfs filesystem. compress is
998 one of zlib or lzo.
999 This function depends on the feature "btrfs". See also
1001 "$g->feature-available".
1002 $g->btrfs_filesystem_resize ($mountpoint [, size => $size]);
1004 This command resizes a btrfs filesystem.
1005 Note that unlike other resize calls, the filesystem has to be
1007 mounted and the parameter is the mountpoint not the device (this is
1008 a requirement of btrfs itself).
1009 The optional parameters are:
1011 "size"
1013 The new size (in bytes) of the filesystem. If omitted, the
1014 filesystem is resized to the maximum size.
1015 See also btrfs(8).
1017 This function depends on the feature "btrfs". See also
1019 "$g->feature-available".
1020 @devices = $g->btrfs_filesystem_show ($device);
1022 Show all the devices where the filesystems in "device" is spanned
1023 over.
1024 If not all the devices for the filesystems are present, then this
1026 function fails and the "errno" is set to "ENODEV".
1027 This function depends on the feature "btrfs". See also
1029 "$g->feature-available".
1030 $g->btrfs_filesystem_sync ($fs);
1032 Force sync on the btrfs filesystem mounted at "fs".
1033 This function depends on the feature "btrfs". See also
1035 "$g->feature-available".
1036 $g->btrfs_fsck ($device [, superblock => $superblock] [, repair =>
1038 $repair]);
1039 Used to check a btrfs filesystem, "device" is the device file where
1040 the filesystem is stored.
1041 This function depends on the feature "btrfs". See also
1043 "$g->feature-available".
1044 $g->btrfs_image (\@source, $image [, compresslevel => $compresslevel]);
1046 This is used to create an image of a btrfs filesystem. All data
1047 will be zeroed, but metadata and the like is preserved.
1048 This function depends on the feature "btrfs". See also
1050 "$g->feature-available".
1051 $g->btrfs_qgroup_assign ($src, $dst, $path);
1053 Add qgroup "src" to parent qgroup "dst". This command can group
1054 several qgroups into a parent qgroup to share common limit.
1055 This function depends on the feature "btrfs". See also
1057 "$g->feature-available".
1058 $g->btrfs_qgroup_create ($qgroupid, $subvolume);
1060 Create a quota group (qgroup) for subvolume at "subvolume".
1061 This function depends on the feature "btrfs". See also
1063 "$g->feature-available".
1064 $g->btrfs_qgroup_destroy ($qgroupid, $subvolume);
1066 Destroy a quota group.
1067 This function depends on the feature "btrfs". See also
1069 "$g->feature-available".
1070 $g->btrfs_qgroup_limit ($subvolume, $size);
1072 Limit the size of the subvolume with path "subvolume".
1073 This function depends on the feature "btrfs". See also
1075 "$g->feature-available".
1076 $g->btrfs_qgroup_remove ($src, $dst, $path);
1078 Remove qgroup "src" from the parent qgroup "dst".
1079 This function depends on the feature "btrfs". See also
1081 "$g->feature-available".
1082 @qgroups = $g->btrfs_qgroup_show ($path);
1084 Show all subvolume quota groups in a btrfs filesystem, including
1085 their usages.
1086 This function depends on the feature "btrfs". See also
1088 "$g->feature-available".
1089 $g->btrfs_quota_enable ($fs, $enable);
1091 Enable or disable subvolume quota support for filesystem which
1092 contains "path".
1093 This function depends on the feature "btrfs". See also
1095 "$g->feature-available".
1096 $g->btrfs_quota_rescan ($fs);
1098 Trash all qgroup numbers and scan the metadata again with the
1099 current config.
1100 This function depends on the feature "btrfs". See also
1102 "$g->feature-available".
1103 $g->btrfs_replace ($srcdev, $targetdev, $mntpoint);
1105 Replace device of a btrfs filesystem. On a live filesystem,
1106 duplicate the data to the target device which is currently stored
1107 on the source device. After completion of the operation, the
1108 source device is wiped out and removed from the filesystem.
1109 The "targetdev" needs to be same size or larger than the "srcdev".
1111 Devices which are currently mounted are never allowed to be used as
1112 the "targetdev".
1113 This function depends on the feature "btrfs". See also
1115 "$g->feature-available".
1116 $g->btrfs_rescue_chunk_recover ($device);
1118 Recover the chunk tree of btrfs filesystem by scanning the devices
1119 one by one.
1120 This function depends on the feature "btrfs". See also
1122 "$g->feature-available".
1123 $g->btrfs_rescue_super_recover ($device);
1125 Recover bad superblocks from good copies.
1126 This function depends on the feature "btrfs". See also
1128 "$g->feature-available".
1129 $g->btrfs_scrub_cancel ($path);
1131 Cancel a running scrub on a btrfs filesystem.
1132 This function depends on the feature "btrfs". See also
1134 "$g->feature-available".
1135 $g->btrfs_scrub_resume ($path);
1137 Resume a previously canceled or interrupted scrub on a btrfs
1138 filesystem.
1139 This function depends on the feature "btrfs". See also
1141 "$g->feature-available".
1142 $g->btrfs_scrub_start ($path);
1144 Reads all the data and metadata on the filesystem, and uses
1145 checksums and the duplicate copies from RAID storage to identify
1146 and repair any corrupt data.
1147 This function depends on the feature "btrfs". See also
1149 "$g->feature-available".
1150 %status = $g->btrfs_scrub_status ($path);
1152 Show status of running or finished scrub on a btrfs filesystem.
1153 This function depends on the feature "btrfs". See also
1155 "$g->feature-available".
1156 $g->btrfs_set_seeding ($device, $seeding);
1158 Enable or disable the seeding feature of a device that contains a
1159 btrfs filesystem.
1160 This function depends on the feature "btrfs". See also
1162 "$g->feature-available".
1163 $g->btrfs_subvolume_create ($dest [, qgroupid => $qgroupid]);
1165 Create a btrfs subvolume. The "dest" argument is the destination
1166 directory and the name of the subvolume, in the form
1167 /path/to/dest/name. The optional parameter "qgroupid" represents
1168 the qgroup which the newly created subvolume will be added to.
1169 This function depends on the feature "btrfs". See also
1171 "$g->feature-available".
1172 $g->btrfs_subvolume_create_opts ($dest [, qgroupid => $qgroupid]);
1174 This is an alias of "btrfs_subvolume_create".
1175 $g->btrfs_subvolume_delete ($subvolume);
1177 Delete the named btrfs subvolume or snapshot.
1178 This function depends on the feature "btrfs". See also
1180 "$g->feature-available".
1181 $id = $g->btrfs_subvolume_get_default ($fs);
1183 Get the default subvolume or snapshot of a filesystem mounted at
1184 "mountpoint".
1185 This function depends on the feature "btrfs". See also
1187 "$g->feature-available".
1188 @subvolumes = $g->btrfs_subvolume_list ($fs);
1190 List the btrfs snapshots and subvolumes of the btrfs filesystem
1191 which is mounted at "fs".
1192 This function depends on the feature "btrfs". See also
1194 "$g->feature-available".
1195 $g->btrfs_subvolume_set_default ($id, $fs);
1197 Set the subvolume of the btrfs filesystem "fs" which will be
1198 mounted by default. See "$g->btrfs_subvolume_list" to get a list
1199 of subvolumes.
1200 This function depends on the feature "btrfs". See also
1202 "$g->feature-available".
1203 %btrfssubvolumeinfo = $g->btrfs_subvolume_show ($subvolume);
1205 Return detailed information of the subvolume.
1206 This function depends on the feature "btrfs". See also
1208 "$g->feature-available".
1209 $g->btrfs_subvolume_snapshot ($source, $dest [, ro => $ro] [, qgroupid
1211 => $qgroupid]);
1212 Create a snapshot of the btrfs subvolume "source". The "dest"
1213 argument is the destination directory and the name of the snapshot,
1214 in the form /path/to/dest/name. By default the newly created
1215 snapshot is writable, if the value of optional parameter "ro" is
1216 true, then a readonly snapshot is created. The optional parameter
1217 "qgroupid" represents the qgroup which the newly created snapshot
1218 will be added to.
1219 This function depends on the feature "btrfs". See also
1221 "$g->feature-available".
1222 $g->btrfs_subvolume_snapshot_opts ($source, $dest [, ro => $ro] [,
1224 qgroupid => $qgroupid]);
1225 This is an alias of "btrfs_subvolume_snapshot".
1226 $g->btrfstune_enable_extended_inode_refs ($device);
1228 This will Enable extended inode refs.
1229 This function depends on the feature "btrfs". See also
1231 "$g->feature-available".
1232 $g->btrfstune_enable_skinny_metadata_extent_refs ($device);
1234 This enable skinny metadata extent refs.
1235 This function depends on the feature "btrfs". See also
1237 "$g->feature-available".
1238 $g->btrfstune_seeding ($device, $seeding);
1240 Enable seeding of a btrfs device, this will force a fs readonly so
1241 that you can use it to build other filesystems.
1242 This function depends on the feature "btrfs". See also
1244 "$g->feature-available".
1245 $ptr = $g->c_pointer ();
1247 In non-C language bindings, this allows you to retrieve the
1248 underlying C pointer to the handle (ie. "$g->h *"). The purpose of
1249 this is to allow other libraries to interwork with libguestfs.
1250 $canonical = $g->canonical_device_name ($device);
1252 This utility function is useful when displaying device names to the
1253 user. It takes a number of irregular device names and returns them
1254 in a consistent format:
1255 /dev/hdX
1257 /dev/vdX
1258 These are returned as /dev/sdX. Note this works for device
1259 names and partition names. This is approximately the reverse
1260 of the algorithm described in "BLOCK DEVICE NAMING" in
1261 guestfs(3).
1262 /dev/mapper/VG-LV
1264 /dev/dm-N
1265 Converted to /dev/VG/LV form using "$g->lvm_canonical_lv_name".
1266 Other strings are returned unmodified.
1268 $cap = $g->cap_get_file ($path);
1270 This function returns the Linux capabilities attached to "path".
1271 The capabilities set is returned in text form (see cap_to_text(3)).
1272 If no capabilities are attached to a file, an empty string is
1274 returned.
1275 This function depends on the feature "linuxcaps". See also
1277 "$g->feature-available".
1278 $g->cap_set_file ($path, $cap);
1280 This function sets the Linux capabilities attached to "path". The
1281 capabilities set "cap" should be passed in text form (see
1282 cap_from_text(3)).
1283 This function depends on the feature "linuxcaps". See also
1285 "$g->feature-available".
1286 $rpath = $g->case_sensitive_path ($path);
1288 This can be used to resolve case insensitive paths on a filesystem
1289 which is case sensitive. The use case is to resolve paths which
1290 you have read from Windows configuration files or the Windows
1291 Registry, to the true path.
1292 The command handles a peculiarity of the Linux ntfs-3g filesystem
1294 driver (and probably others), which is that although the underlying
1295 filesystem is case-insensitive, the driver exports the filesystem
1296 to Linux as case-sensitive.
1297 One consequence of this is that special directories such as
1299 C:\windows may appear as /WINDOWS or /windows (or other things)
1300 depending on the precise details of how they were created. In
1301 Windows itself this would not be a problem.
1302 Bug or feature? You decide:
1304 <https://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1>
1305 "$g->case_sensitive_path" attempts to resolve the true case of each
1307 element in the path. It will return a resolved path if either the
1308 full path or its parent directory exists. If the parent directory
1309 exists but the full path does not, the case of the parent directory
1310 will be correctly resolved, and the remainder appended unmodified.
1311 For example, if the file "/Windows/System32/netkvm.sys" exists:
1312 "$g->case_sensitive_path" ("/windows/system32/netkvm.sys")
1314 "Windows/System32/netkvm.sys"
1315 "$g->case_sensitive_path" ("/windows/system32/NoSuchFile")
1317 "Windows/System32/NoSuchFile"
1318 "$g->case_sensitive_path" ("/windows/system33/netkvm.sys")
1320 ERROR
1321 Note: Because of the above behaviour, "$g->case_sensitive_path"
1323 cannot be used to check for the existence of a file.
1324 Note: This function does not handle drive names, backslashes etc.
1326 See also "$g->realpath".
1328 $content = $g->cat ($path);
1330 Return the contents of the file named "path".
1331 Because, in C, this function returns a "char *", there is no way to
1333 differentiate between a "\0" character in a file and end of string.
1334 To handle binary files, use the "$g->read_file" or "$g->download"
1335 functions.
1336 $checksum = $g->checksum ($csumtype, $path);
1338 This call computes the MD5, SHAx or CRC checksum of the file named
1339 "path".
1340 The type of checksum to compute is given by the "csumtype"
1342 parameter which must have one of the following values:
1343 "crc"
1345 Compute the cyclic redundancy check (CRC) specified by POSIX
1346 for the "cksum" command.
1347 "md5"
1349 Compute the MD5 hash (using the md5sum(1) program).
1350 "sha1"
1352 Compute the SHA1 hash (using the sha1sum(1) program).
1353 "sha224"
1355 Compute the SHA224 hash (using the sha224sum(1) program).
1356 "sha256"
1358 Compute the SHA256 hash (using the sha256sum(1) program).
1359 "sha384"
1361 Compute the SHA384 hash (using the sha384sum(1) program).
1362 "sha512"
1364 Compute the SHA512 hash (using the sha512sum(1) program).
1365 The checksum is returned as a printable string.
1367 To get the checksum for a device, use "$g->checksum_device".
1369 To get the checksums for many files, use "$g->checksums_out".
1371 $checksum = $g->checksum_device ($csumtype, $device);
1373 This call computes the MD5, SHAx or CRC checksum of the contents of
1374 the device named "device". For the types of checksums supported
1375 see the "$g->checksum" command.
1376 $g->checksums_out ($csumtype, $directory, $sumsfile);
1378 This command computes the checksums of all regular files in
1379 directory and then emits a list of those checksums to the local
1380 output file "sumsfile".
1381 This can be used for verifying the integrity of a virtual machine.
1383 However to be properly secure you should pay attention to the
1384 output of the checksum command (it uses the ones from GNU
1385 coreutils). In particular when the filename is not printable,
1386 coreutils uses a special backslash syntax. For more information,
1387 see the GNU coreutils info file.
1388 $g->chmod ($mode, $path);
1390 Change the mode (permissions) of "path" to "mode". Only numeric
1391 modes are supported.
1392 Note: When using this command from guestfish, "mode" by default
1394 would be decimal, unless you prefix it with 0 to get octal, ie. use
1395 0700 not 700.
1396 The mode actually set is affected by the umask.
1398 $g->chown ($owner, $group, $path);
1400 Change the file owner to "owner" and group to "group".
1401 Only numeric uid and gid are supported. If you want to use names,
1403 you will need to locate and parse the password file yourself
1404 (Augeas support makes this relatively easy).
1405 $count = $g->clear_backend_setting ($name);
1407 If there is a backend setting string matching "name" or beginning
1408 with "name=", then that string is removed from the backend
1409 settings.
1410 This call returns the number of strings which were removed (which
1412 may be 0, 1 or greater than 1).
1413 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
1415 $g->clevis_luks_unlock ($device, $mapname);
1417 This command opens a block device that has been encrypted according
1418 to the Linux Unified Key Setup (LUKS) standard, using network-bound
1419 disk encryption (NBDE).
1420 "device" is the encrypted block device.
1422 The appliance will connect to the Tang servers noted in the tree of
1424 Clevis pins that is bound to a keyslot of the LUKS header. The
1425 Clevis pin tree may comprise "sss" (redudancy) pins as internal
1426 nodes (optionally), and "tang" pins as leaves. "tpm2" pins are not
1427 supported. The appliance unlocks the encrypted block device by
1428 combining responses from the Tang servers with metadata from the
1429 LUKS header; there is no "key" parameter.
1430 This command will fail if networking has not been enabled for the
1432 appliance. Refer to "$g->set_network".
1433 The command creates a new block device called /dev/mapper/mapname.
1435 Reads and writes to this block device are decrypted from and
1436 encrypted to the underlying "device" respectively. Close the
1437 decrypted block device with "$g->cryptsetup_close".
1438 "mapname" cannot be "control" because that name is reserved by
1440 device-mapper.
1441 If this block device contains LVM volume groups, then calling
1443 "$g->lvm_scan" with the "activate" parameter "true" will make them
1444 visible.
1445 Use "$g->list_dm_devices" to list all device mapper devices.
1447 This function depends on the feature "clevisluks". See also
1449 "$g->feature-available".
1450 $output = $g->command (\@arguments);
1452 This call runs a command from the guest filesystem. The filesystem
1453 must be mounted, and must contain a compatible operating system
1454 (ie. something Linux, with the same or compatible processor
1455 architecture).
1456 The single parameter is an argv-style list of arguments. The first
1458 element is the name of the program to run. Subsequent elements are
1459 parameters. The list must be non-empty (ie. must contain a program
1460 name). Note that the command runs directly, and is not invoked via
1461 the shell (see "$g->sh").
1462 The return value is anything printed to stdout by the command.
1464 If the command returns a non-zero exit status, then this function
1466 returns an error message. The error message string is the content
1467 of stderr from the command.
1468 The $PATH environment variable will contain at least /usr/bin and
1470 /bin. If you require a program from another location, you should
1471 provide the full path in the first parameter.
1472 Shared libraries and data files required by the program must be
1474 available on filesystems which are mounted in the correct places.
1475 It is the caller’s responsibility to ensure all filesystems that
1476 are needed are mounted at the right locations.
1477 Because of the message protocol, there is a transfer limit of
1479 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1480 guestfs(3).
1481 @lines = $g->command_lines (\@arguments);
1483 This is the same as "$g->command", but splits the result into a
1484 list of lines.
1485 See also: "$g->sh_lines"
1487 Because of the message protocol, there is a transfer limit of
1489 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1490 guestfs(3).
1491 $g->compress_device_out ($ctype, $device, $zdevice [, level =>
1493 $level]);
1494 This command compresses "device" and writes it out to the local
1495 file "zdevice".
1496 The "ctype" and optional "level" parameters have the same meaning
1498 as in "$g->compress_out".
1499 $g->compress_out ($ctype, $file, $zfile [, level => $level]);
1501 This command compresses file and writes it out to the local file
1502 zfile.
1503 The compression program used is controlled by the "ctype"
1505 parameter. Currently this includes: "compress", "gzip", "bzip2",
1506 "xz" or "lzop". Some compression types may not be supported by
1507 particular builds of libguestfs, in which case you will get an
1508 error containing the substring "not supported".
1509 The optional "level" parameter controls compression level. The
1511 meaning and default for this parameter depends on the compression
1512 program being used.
1513 $g->config ($hvparam, $hvvalue);
1515 This can be used to add arbitrary hypervisor parameters of the form
1516 -param value. Actually it’s not quite arbitrary - we prevent you
1517 from setting some parameters which would interfere with parameters
1518 that we use.
1519 The first character of "hvparam" string must be a "-" (dash).
1521 "hvvalue" can be NULL.
1523 $g->copy_attributes ($src, $dest [, all => $all] [, mode => $mode] [,
1525 xattributes => $xattributes] [, ownership => $ownership]);
1526 Copy the attributes of a path (which can be a file or a directory)
1527 to another path.
1528 By default no attribute is copied, so make sure to specify any (or
1530 "all" to copy everything).
1531 The optional arguments specify which attributes can be copied:
1533 "mode"
1535 Copy part of the file mode from "source" to "destination". Only
1536 the UNIX permissions and the sticky/setuid/setgid bits can be
1537 copied.
1538 "xattributes"
1540 Copy the Linux extended attributes (xattrs) from "source" to
1541 "destination". This flag does nothing if the linuxxattrs
1542 feature is not available (see "$g->feature_available").
1543 "ownership"
1545 Copy the owner uid and the group gid of "source" to
1546 "destination".
1547 "all"
1549 Copy all the attributes from "source" to "destination".
1550 Enabling it enables all the other flags, if they are not
1551 specified already.
1552 $g->copy_device_to_device ($src, $dest [, srcoffset => $srcoffset] [,
1554 destoffset => $destoffset] [, size => $size] [, sparse => $sparse] [,
1555 append => $append]);
1556 The four calls "$g->copy_device_to_device",
1557 "$g->copy_device_to_file", "$g->copy_file_to_device", and
1558 "$g->copy_file_to_file" let you copy from a source (device|file) to
1559 a destination (device|file).
1560 Partial copies can be made since you can specify optionally the
1562 source offset, destination offset and size to copy. These values
1563 are all specified in bytes. If not given, the offsets both default
1564 to zero, and the size defaults to copying as much as possible until
1565 we hit the end of the source.
1566 The source and destination may be the same object. However
1568 overlapping regions may not be copied correctly.
1569 If the destination is a file, it is created if required. If the
1571 destination file is not large enough, it is extended.
1572 If the destination is a file and the "append" flag is not set, then
1574 the destination file is truncated. If the "append" flag is set,
1575 then the copy appends to the destination file. The "append" flag
1576 currently cannot be set for devices.
1577 If the "sparse" flag is true then the call avoids writing blocks
1579 that contain only zeroes, which can help in some situations where
1580 the backing disk is thin-provisioned. Note that unless the target
1581 is already zeroed, using this option will result in incorrect
1582 copying.
1583 $g->copy_device_to_file ($src, $dest [, srcoffset => $srcoffset] [,
1585 destoffset => $destoffset] [, size => $size] [, sparse => $sparse] [,
1586 append => $append]);
1587 See "$g->copy_device_to_device" for a general overview of this
1588 call.
1589 $g->copy_file_to_device ($src, $dest [, srcoffset => $srcoffset] [,
1591 destoffset => $destoffset] [, size => $size] [, sparse => $sparse] [,
1592 append => $append]);
1593 See "$g->copy_device_to_device" for a general overview of this
1594 call.
1595 $g->copy_file_to_file ($src, $dest [, srcoffset => $srcoffset] [,
1597 destoffset => $destoffset] [, size => $size] [, sparse => $sparse] [,
1598 append => $append]);
1599 See "$g->copy_device_to_device" for a general overview of this
1600 call.
1601 This is not the function you want for copying files. This is for
1603 copying blocks within existing files. See "$g->cp", "$g->cp_a" and
1604 "$g->mv" for general file copying and moving functions.
1605 $g->copy_in ($localpath, $remotedir);
1607 "$g->copy_in" copies local files or directories recursively into
1608 the disk image, placing them in the directory called "remotedir"
1609 (which must exist).
1610 Wildcards cannot be used.
1612 $g->copy_out ($remotepath, $localdir);
1614 "$g->copy_out" copies remote files or directories recursively out
1615 of the disk image, placing them on the host disk in a local
1616 directory called "localdir" (which must exist).
1617 To download to the current directory, use "." as in:
1619 C<$g-E<gt>copy_out> /home .
1621 Wildcards cannot be used.
1623 $g->copy_size ($src, $dest, $size);
1625 This command copies exactly "size" bytes from one source device or
1626 file "src" to another destination device or file "dest".
1627 Note this will fail if the source is too short or if the
1629 destination is not large enough.
1630 This function is deprecated. In new code, use the
1632 "copy_device_to_device" call instead.
1633 Deprecated functions will not be removed from the API, but the fact
1635 that they are deprecated indicates that there are problems with
1636 correct use of these functions.
1637 $g->cp ($src, $dest);
1639 This copies a file from "src" to "dest" where "dest" is either a
1640 destination filename or destination directory.
1641 $g->cp_a ($src, $dest);
1643 This copies a file or directory from "src" to "dest" recursively
1644 using the "cp -a" command.
1645 $g->cp_r ($src, $dest);
1647 This copies a file or directory from "src" to "dest" recursively
1648 using the "cp -rP" command.
1649 Most users should use "$g->cp_a" instead. This command is useful
1651 when you don't want to preserve permissions, because the target
1652 filesystem does not support it (primarily when writing to DOS FAT
1653 filesystems).
1654 $g->cpio_out ($directory, $cpiofile [, format => $format]);
1656 This command packs the contents of directory and downloads it to
1657 local file "cpiofile".
1658 The optional "format" parameter can be used to select the format.
1660 Only the following formats are currently permitted:
1661 "newc"
1663 New (SVR4) portable format. This format happens to be
1664 compatible with the cpio-like format used by the Linux kernel
1665 for initramfs.
1666 This is the default format.
1668 "crc"
1670 New (SVR4) portable format with a checksum.
1671 $g->cryptsetup_close ($device);
1673 This closes an encrypted device that was created earlier by
1674 "$g->cryptsetup_open". The "device" parameter must be the name of
1675 the mapping device (ie. /dev/mapper/mapname) and not the name of
1676 the underlying block device.
1677 This function depends on the feature "luks". See also
1679 "$g->feature-available".
1680 $g->cryptsetup_open ($device, $key, $mapname [, readonly => $readonly]
1682 [, crypttype => $crypttype]);
1683 This command opens a block device which has been encrypted
1684 according to the Linux Unified Key Setup (LUKS) standard, Windows
1685 BitLocker, or some other types.
1686 "device" is the encrypted block device or partition.
1688 The caller must supply one of the keys associated with the
1690 encrypted block device, in the "key" parameter.
1691 This creates a new block device called /dev/mapper/mapname. Reads
1693 and writes to this block device are decrypted from and encrypted to
1694 the underlying "device" respectively.
1695 "mapname" cannot be "control" because that name is reserved by
1697 device-mapper.
1698 If the optional "crypttype" parameter is not present then
1700 libguestfs tries to guess the correct type (for example LUKS or
1701 BitLocker). However you can override this by specifying one of the
1702 following types:
1703 "luks"
1705 A Linux LUKS device.
1706 "bitlk"
1708 A Windows BitLocker device.
1709 The optional "readonly" flag, if set to true, creates a read-only
1711 mapping.
1712 If this block device contains LVM volume groups, then calling
1714 "$g->lvm_scan" with the "activate" parameter "true" will make them
1715 visible.
1716 Use "$g->list_dm_devices" to list all device mapper devices.
1718 This function depends on the feature "luks". See also
1720 "$g->feature-available".
1721 $g->dd ($src, $dest);
1723 This command copies from one source device or file "src" to another
1724 destination device or file "dest". Normally you would use this to
1725 copy to or from a device or partition, for example to duplicate a
1726 filesystem.
1727 If the destination is a device, it must be as large or larger than
1729 the source file or device, otherwise the copy will fail. This
1730 command cannot do partial copies (see "$g->copy_device_to_device").
1731 This function is deprecated. In new code, use the
1733 "copy_device_to_device" call instead.
1734 Deprecated functions will not be removed from the API, but the fact
1736 that they are deprecated indicates that there are problems with
1737 correct use of these functions.
1738 $index = $g->device_index ($device);
1740 This function takes a device name (eg. "/dev/sdb") and returns the
1741 index of the device in the list of devices.
1742 Index numbers start from 0. The named device must exist, for
1744 example as a string returned from "$g->list_devices".
1745 See also "$g->list_devices", "$g->part_to_dev", "$g->device_name".
1747 $name = $g->device_name ($index);
1749 This function takes a device index and returns the device name.
1750 For example index 0 will return the string "/dev/sda".
1751 The drive index must have been added to the handle.
1753 See also "$g->list_devices", "$g->part_to_dev", "$g->device_index".
1755 $output = $g->df ();
1757 This command runs the df(1) command to report disk space used.
1758 This command is mostly useful for interactive sessions. It is not
1760 intended that you try to parse the output string. Use
1761 "$g->statvfs" from programs.
1762 $output = $g->df_h ();
1764 This command runs the "df -h" command to report disk space used in
1765 human-readable format.
1766 This command is mostly useful for interactive sessions. It is not
1768 intended that you try to parse the output string. Use
1769 "$g->statvfs" from programs.
1770 $g->disk_create ($filename, $format, $size [, backingfile =>
1772 $backingfile] [, backingformat => $backingformat] [, preallocation =>
1773 $preallocation] [, compat => $compat] [, clustersize => $clustersize]);
1774 Create a blank disk image called filename (a host file) with format
1775 "format" (usually "raw" or "qcow2"). The size is "size" bytes.
1776 If used with the optional "backingfile" parameter, then a snapshot
1778 is created on top of the backing file. In this case, "size" must
1779 be passed as -1. The size of the snapshot is the same as the size
1780 of the backing file, which is discovered automatically. You are
1781 encouraged to also pass "backingformat" to describe the format of
1782 "backingfile".
1783 If filename refers to a block device, then the device is formatted.
1785 The "size" is ignored since block devices have an intrinsic size.
1786 The other optional parameters are:
1788 "preallocation"
1790 If format is "raw", then this can be either "off" (or "sparse")
1791 or "full" to create a sparse or fully allocated file
1792 respectively. The default is "off".
1793 If format is "qcow2", then this can be "off" (or "sparse"),
1795 "metadata" or "full". Preallocating metadata can be faster
1796 when doing lots of writes, but uses more space. The default is
1797 "off".
1798 "compat"
1800 "qcow2" only: Pass the string 1.1 to use the advanced qcow2
1801 format supported by qemu ≥ 1.1.
1802 "clustersize"
1804 "qcow2" only: Change the qcow2 cluster size. The default is
1805 65536 (bytes) and this setting may be any power of two between
1806 512 and 2097152.
1807 Note that this call does not add the new disk to the handle. You
1809 may need to call "$g->add_drive_opts" separately.
1810 $format = $g->disk_format ($filename);
1812 Detect and return the format of the disk image called filename.
1813 filename can also be a host device, etc. If the format of the
1814 image could not be detected, then "unknown" is returned.
1815 Note that detecting the disk format can be insecure under some
1817 circumstances. See "CVE-2010-3851" in guestfs(3).
1818 See also: "DISK IMAGE FORMATS" in guestfs(3)
1820 $backingfile = $g->disk_has_backing_file ($filename);
1822 Detect and return whether the disk image filename has a backing
1823 file.
1824 Note that detecting disk features can be insecure under some
1826 circumstances. See "CVE-2010-3851" in guestfs(3).
1827 $size = $g->disk_virtual_size ($filename);
1829 Detect and return the virtual size in bytes of the disk image
1830 called filename.
1831 Note that detecting disk features can be insecure under some
1833 circumstances. See "CVE-2010-3851" in guestfs(3).
1834 $kmsgs = $g->dmesg ();
1836 This returns the kernel messages (dmesg(1) output) from the guest
1837 kernel. This is sometimes useful for extended debugging of
1838 problems.
1839 Another way to get the same information is to enable verbose
1841 messages with "$g->set_verbose" or by setting the environment
1842 variable "LIBGUESTFS_DEBUG=1" before running the program.
1843 $g->download ($remotefilename, $filename);
1845 Download file remotefilename and save it as filename on the local
1846 machine.
1847 filename can also be a named pipe.
1849 See also "$g->upload", "$g->cat".
1851 $g->download_blocks ($device, $start, $stop, $filename [, unallocated
1853 => $unallocated]);
1854 Download the data units from start address to stop from the disk
1855 partition (eg. /dev/sda1) and save them as filename on the local
1856 machine.
1857 The use of this API on sparse disk image formats such as QCOW, may
1859 result in large zero-filled files downloaded on the host.
1860 The size of a data unit varies across filesystem implementations.
1862 On NTFS filesystems data units are referred as clusters while on
1863 ExtX ones they are referred as fragments.
1864 If the optional "unallocated" flag is true (default is false), only
1866 the unallocated blocks will be extracted. This is useful to detect
1867 hidden data or to retrieve deleted files which data units have not
1868 been overwritten yet.
1869 This function depends on the feature "sleuthkit". See also
1871 "$g->feature-available".
1872 $g->download_inode ($device, $inode, $filename);
1874 Download a file given its inode from the disk partition (eg.
1875 /dev/sda1) and save it as filename on the local machine.
1876 It is not required to mount the disk to run this command.
1878 The command is capable of downloading deleted or inaccessible
1880 files.
1881 This function depends on the feature "sleuthkit". See also
1883 "$g->feature-available".
1884 $g->download_offset ($remotefilename, $filename, $offset, $size);
1886 Download file remotefilename and save it as filename on the local
1887 machine.
1888 remotefilename is read for "size" bytes starting at "offset" (this
1890 region must be within the file or device).
1891 Note that there is no limit on the amount of data that can be
1893 downloaded with this call, unlike with "$g->pread", and this call
1894 always reads the full amount unless an error occurs.
1895 See also "$g->download", "$g->pread".
1897 $g->drop_caches ($whattodrop);
1899 This instructs the guest kernel to drop its page cache, and/or
1900 dentries and inode caches. The parameter "whattodrop" tells the
1901 kernel what precisely to drop, see
1902 <https://linux-mm.org/Drop_Caches>
1903 Setting "whattodrop" to 3 should drop everything.
1905 This automatically calls sync(2) before the operation, so that the
1907 maximum guest memory is freed.
1908 $sizekb = $g->du ($path);
1910 This command runs the "du -s" command to estimate file space usage
1911 for "path".
1912 "path" can be a file or a directory. If "path" is a directory then
1914 the estimate includes the contents of the directory and all
1915 subdirectories (recursively).
1916 The result is the estimated size in kilobytes (ie. units of 1024
1918 bytes).
1919 $g->e2fsck ($device [, correct => $correct] [, forceall => $forceall]);
1921 This runs the ext2/ext3 filesystem checker on "device". It can
1922 take the following optional arguments:
1923 "correct"
1925 Automatically repair the file system. This option will cause
1926 e2fsck to automatically fix any filesystem problems that can be
1927 safely fixed without human intervention.
1928 This option may not be specified at the same time as the
1930 "forceall" option.
1931 "forceall"
1933 Assume an answer of ‘yes’ to all questions; allows e2fsck to be
1934 used non-interactively.
1935 This option may not be specified at the same time as the
1937 "correct" option.
1938 $g->e2fsck_f ($device);
1940 This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
1941 checker on "device", noninteractively (-p), even if the filesystem
1942 appears to be clean (-f).
1943 This function is deprecated. In new code, use the "e2fsck" call
1945 instead.
1946 Deprecated functions will not be removed from the API, but the fact
1948 that they are deprecated indicates that there are problems with
1949 correct use of these functions.
1950 $output = $g->echo_daemon (\@words);
1952 This command concatenates the list of "words" passed with single
1953 spaces between them and returns the resulting string.
1954 You can use this command to test the connection through to the
1956 daemon.
1957 See also "$g->ping_daemon".
1959 @lines = $g->egrep ($regex, $path);
1961 This calls the external egrep(1) program and returns the matching
1962 lines.
1963 Because of the message protocol, there is a transfer limit of
1965 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1966 guestfs(3).
1967 This function is deprecated. In new code, use the "grep" call
1969 instead.
1970 Deprecated functions will not be removed from the API, but the fact
1972 that they are deprecated indicates that there are problems with
1973 correct use of these functions.
1974 @lines = $g->egrepi ($regex, $path);
1976 This calls the external "egrep -i" program and returns the matching
1977 lines.
1978 Because of the message protocol, there is a transfer limit of
1980 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1981 guestfs(3).
1982 This function is deprecated. In new code, use the "grep" call
1984 instead.
1985 Deprecated functions will not be removed from the API, but the fact
1987 that they are deprecated indicates that there are problems with
1988 correct use of these functions.
1989 $equality = $g->equal ($file1, $file2);
1991 This compares the two files file1 and file2 and returns true if
1992 their content is exactly equal, or false otherwise.
1993 The external cmp(1) program is used for the comparison.
1995 $existsflag = $g->exists ($path);
1997 This returns "true" if and only if there is a file, directory (or
1998 anything) with the given "path" name.
1999 See also "$g->is_file", "$g->is_dir", "$g->stat".
2001 $g->extlinux ($directory);
2003 Install the SYSLINUX bootloader on the device mounted at directory.
2004 Unlike "$g->syslinux" which requires a FAT filesystem, this can be
2005 used on an ext2/3/4 or btrfs filesystem.
2006 The directory parameter can be either a mountpoint, or a directory
2008 within the mountpoint.
2009 You also have to mark the partition as "active"
2011 ("$g->part_set_bootable") and a Master Boot Record must be
2012 installed (eg. using "$g->pwrite_device") on the first sector of
2013 the whole disk. The SYSLINUX package comes with some suitable
2014 Master Boot Records. See the extlinux(1) man page for further
2015 information.
2016 Additional configuration can be supplied to SYSLINUX by placing a
2018 file called extlinux.conf on the filesystem under directory. For
2019 further information about the contents of this file, see
2020 extlinux(1).
2021 See also "$g->syslinux".
2023 This function depends on the feature "extlinux". See also
2025 "$g->feature-available".
2026 $g->f2fs_expand ($device);
2028 This expands a f2fs filesystem to match the size of the underlying
2029 device.
2030 This function depends on the feature "f2fs". See also
2032 "$g->feature-available".
2033 $g->fallocate ($path, $len);
2035 This command preallocates a file (containing zero bytes) named
2036 "path" of size "len" bytes. If the file exists already, it is
2037 overwritten.
2038 Do not confuse this with the guestfish-specific "alloc" command
2040 which allocates a file in the host and attaches it as a device.
2041 This function is deprecated. In new code, use the "fallocate64"
2043 call instead.
2044 Deprecated functions will not be removed from the API, but the fact
2046 that they are deprecated indicates that there are problems with
2047 correct use of these functions.
2048 $g->fallocate64 ($path, $len);
2050 This command preallocates a file (containing zero bytes) named
2051 "path" of size "len" bytes. If the file exists already, it is
2052 overwritten.
2053 Note that this call allocates disk blocks for the file. To create
2055 a sparse file use "$g->truncate_size" instead.
2056 The deprecated call "$g->fallocate" does the same, but owing to an
2058 oversight it only allowed 30 bit lengths to be specified,
2059 effectively limiting the maximum size of files created through that
2060 call to 1GB.
2061 Do not confuse this with the guestfish-specific "alloc" and
2063 "sparse" commands which create a file in the host and attach it as
2064 a device.
2065 $isavailable = $g->feature_available (\@groups);
2067 This is the same as "$g->available", but unlike that call it
2068 returns a simple true/false boolean result, instead of throwing an
2069 exception if a feature is not found. For other documentation see
2070 "$g->available".
2071 @lines = $g->fgrep ($pattern, $path);
2073 This calls the external fgrep(1) program and returns the matching
2074 lines.
2075 Because of the message protocol, there is a transfer limit of
2077 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2078 guestfs(3).
2079 This function is deprecated. In new code, use the "grep" call
2081 instead.
2082 Deprecated functions will not be removed from the API, but the fact
2084 that they are deprecated indicates that there are problems with
2085 correct use of these functions.
2086 @lines = $g->fgrepi ($pattern, $path);
2088 This calls the external "fgrep -i" program and returns the matching
2089 lines.
2090 Because of the message protocol, there is a transfer limit of
2092 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2093 guestfs(3).
2094 This function is deprecated. In new code, use the "grep" call
2096 instead.
2097 Deprecated functions will not be removed from the API, but the fact
2099 that they are deprecated indicates that there are problems with
2100 correct use of these functions.
2101 $description = $g->file ($path);
2103 This call uses the standard file(1) command to determine the type
2104 or contents of the file.
2105 This call will also transparently look inside various types of
2107 compressed file.
2108 The filename is not prepended to the output (like the file command
2110 -b option).
2111 The output depends on the output of the underlying file(1) command
2113 and it can change in future in ways beyond our control. In other
2114 words, the output is not guaranteed by the ABI.
2115 See also: file(1), "$g->vfs_type", "$g->lstat", "$g->is_file",
2117 "$g->is_blockdev" (etc), "$g->is_zero".
2118 $arch = $g->file_architecture ($filename);
2120 This detects the architecture of the binary filename, and returns
2121 it if known.
2122 Currently defined architectures are:
2124 "aarch64"
2126 64 bit ARM.
2127 "arm"
2129 32 bit ARM.
2130 "i386"
2132 This string is returned for all 32 bit i386, i486, i586, i686
2133 binaries irrespective of the precise processor requirements of
2134 the binary.
2135 "ia64"
2137 Intel Itanium.
2138 "ppc"
2140 32 bit Power PC.
2141 "ppc64"
2143 64 bit Power PC (big endian).
2144 "ppc64le"
2146 64 bit Power PC (little endian).
2147 "riscv32"
2149 "riscv64"
2150 "riscv128"
2151 RISC-V 32-, 64- or 128-bit variants.
2152 "s390"
2154 31 bit IBM S/390.
2155 "s390x"
2157 64 bit IBM S/390.
2158 "sparc"
2160 32 bit SPARC.
2161 "sparc64"
2163 64 bit SPARC V9 and above.
2164 "x86_64"
2166 64 bit x86-64.
2167 Libguestfs may return other architecture strings in future.
2169 The function works on at least the following types of files:
2171 • many types of Un*x and Linux binary
2173 • many types of Un*x and Linux shared library
2175 • Windows Win32 and Win64 binaries
2177 • Windows Win32 and Win64 DLLs
2179 Win32 binaries and DLLs return "i386".
2181 Win64 binaries and DLLs return "x86_64".
2183 • Linux kernel modules
2185 • Linux new-style initrd images
2187 • some non-x86 Linux vmlinuz kernels
2189 What it can't do currently:
2191 • static libraries (libfoo.a)
2193 • Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
2195 • x86 Linux vmlinuz kernels
2197 x86 vmlinuz images (bzImage format) consist of a mix of 16-,
2199 32- and compressed code, and are horribly hard to unpack. If
2200 you want to find the architecture of a kernel, use the
2201 architecture of the associated initrd or kernel module(s)
2202 instead.
2203 $size = $g->filesize ($file);
2205 This command returns the size of file in bytes.
2206 To get other stats about a file, use "$g->stat", "$g->lstat",
2208 "$g->is_dir", "$g->is_file" etc. To get the size of block devices,
2209 use "$g->blockdev_getsize64".
2210 $fsavail = $g->filesystem_available ($filesystem);
2212 Check whether libguestfs supports the named filesystem. The
2213 argument "filesystem" is a filesystem name, such as "ext3".
2214 You must call "$g->launch" before using this command.
2216 This is mainly useful as a negative test. If this returns true, it
2218 doesn't mean that a particular filesystem can be created or
2219 mounted, since filesystems can fail for other reasons such as it
2220 being a later version of the filesystem, or having incompatible
2221 features, or lacking the right mkfs.<fs> tool.
2222 See also "$g->available", "$g->feature_available", "AVAILABILITY"
2224 in guestfs(3).
2225 @dirents = $g->filesystem_walk ($device);
2227 Walk through the internal structures of a disk partition (eg.
2228 /dev/sda1) in order to return a list of all the files and
2229 directories stored within.
2230 It is not necessary to mount the disk partition to run this
2232 command.
2233 All entries in the filesystem are returned. This function can list
2235 deleted or unaccessible files. The entries are not sorted.
2236 The "tsk_dirent" structure contains the following fields.
2238 "tsk_inode"
2240 Filesystem reference number of the node. It might be 0 if the
2241 node has been deleted.
2242 "tsk_type"
2244 Basic file type information. See below for a detailed list of
2245 values.
2246 "tsk_size"
2248 File size in bytes. It might be -1 if the node has been
2249 deleted.
2250 "tsk_name"
2252 The file path relative to its directory.
2253 "tsk_flags"
2255 Bitfield containing extra information regarding the entry. It
2256 contains the logical OR of the following values:
2257 0x0001
2259 If set to 1, the file is allocated and visible within the
2260 filesystem. Otherwise, the file has been deleted. Under
2261 certain circumstances, the function "download_inode" can be
2262 used to recover deleted files.
2263 0x0002
2265 Filesystem such as NTFS and Ext2 or greater, separate the
2266 file name from the metadata structure. The bit is set to 1
2267 when the file name is in an unallocated state and the
2268 metadata structure is in an allocated one. This generally
2269 implies the metadata has been reallocated to a new file.
2270 Therefore, information such as file type, file size,
2271 timestamps, number of links and symlink target might not
2272 correspond with the ones of the original deleted entry.
2273 0x0004
2275 The bit is set to 1 when the file is compressed using
2276 filesystem native compression support (NTFS). The API is
2277 not able to detect application level compression.
2278 "tsk_atime_sec"
2280 "tsk_atime_nsec"
2281 "tsk_mtime_sec"
2282 "tsk_mtime_nsec"
2283 "tsk_ctime_sec"
2284 "tsk_ctime_nsec"
2285 "tsk_crtime_sec"
2286 "tsk_crtime_nsec"
2287 Respectively, access, modification, last status change and
2288 creation time in Unix format in seconds and nanoseconds.
2289 "tsk_nlink"
2291 Number of file names pointing to this entry.
2292 "tsk_link"
2294 If the entry is a symbolic link, this field will contain the
2295 path to the target file.
2296 The "tsk_type" field will contain one of the following characters:
2298 'b' Block special
2300 'c' Char special
2302 'd' Directory
2304 'f' FIFO (named pipe)
2306 'l' Symbolic link
2308 'r' Regular file
2310 's' Socket
2312 'h' Shadow inode (Solaris)
2314 'w' Whiteout inode (BSD)
2316 'u' Unknown file type
2318 This function depends on the feature "libtsk". See also
2320 "$g->feature-available".
2321 $g->fill ($c, $len, $path);
2323 This command creates a new file called "path". The initial content
2324 of the file is "len" octets of "c", where "c" must be a number in
2325 the range "[0..255]".
2326 To fill a file with zero bytes (sparsely), it is much more
2328 efficient to use "$g->truncate_size". To create a file with a
2329 pattern of repeating bytes use "$g->fill_pattern".
2330 $g->fill_dir ($dir, $nr);
2332 This function, useful for testing filesystems, creates "nr" empty
2333 files in the directory "dir" with names 00000000 through "nr-1"
2334 (ie. each file name is 8 digits long padded with zeroes).
2335 $g->fill_pattern ($pattern, $len, $path);
2337 This function is like "$g->fill" except that it creates a new file
2338 of length "len" containing the repeating pattern of bytes in
2339 "pattern". The pattern is truncated if necessary to ensure the
2340 length of the file is exactly "len" bytes.
2341 @names = $g->find ($directory);
2343 This command lists out all files and directories, recursively,
2344 starting at directory. It is essentially equivalent to running the
2345 shell command "find directory -print" but some post-processing
2346 happens on the output, described below.
2347 This returns a list of strings without any prefix. Thus if the
2349 directory structure was:
2350 /tmp/a
2352 /tmp/b
2353 /tmp/c/d
2354 then the returned list from "$g->find" /tmp would be 4 elements:
2356 a
2358 b
2359 c
2360 c/d
2361 If directory is not a directory, then this command returns an
2363 error.
2364 The returned list is sorted.
2366 $g->find0 ($directory, $files);
2368 This command lists out all files and directories, recursively,
2369 starting at directory, placing the resulting list in the external
2370 file called files.
2371 This command works the same way as "$g->find" with the following
2373 exceptions:
2374 • The resulting list is written to an external file.
2376 • Items (filenames) in the result are separated by "\0"
2378 characters. See find(1) option -print0.
2379 • The result list is not sorted.
2381 @dirents = $g->find_inode ($device, $inode);
2383 Searches all the entries associated with the given inode.
2384 For each entry, a "tsk_dirent" structure is returned. See
2386 "filesystem_walk" for more information about "tsk_dirent"
2387 structures.
2388 This function depends on the feature "libtsk". See also
2390 "$g->feature-available".
2391 $device = $g->findfs_label ($label);
2393 This command searches the filesystems and returns the one which has
2394 the given label. An error is returned if no such filesystem can be
2395 found.
2396 To find the label of a filesystem, use "$g->vfs_label".
2398 $device = $g->findfs_uuid ($uuid);
2400 This command searches the filesystems and returns the one which has
2401 the given UUID. An error is returned if no such filesystem can be
2402 found.
2403 To find the UUID of a filesystem, use "$g->vfs_uuid".
2405 $status = $g->fsck ($fstype, $device);
2407 This runs the filesystem checker (fsck) on "device" which should
2408 have filesystem type "fstype".
2409 The returned integer is the status. See fsck(8) for the list of
2411 status codes from "fsck".
2412 Notes:
2414 • Multiple status codes can be summed together.
2416 • A non-zero return code can mean "success", for example if
2418 errors have been corrected on the filesystem.
2419 • Checking or repairing NTFS volumes is not supported (by linux-
2421 ntfs).
2422 This command is entirely equivalent to running "fsck -a -t fstype
2424 device".
2425 $g->fstrim ($mountpoint [, offset => $offset] [, length => $length] [,
2427 minimumfreeextent => $minimumfreeextent]);
2428 Trim the free space in the filesystem mounted on "mountpoint". The
2429 filesystem must be mounted read-write.
2430 The filesystem contents are not affected, but any free space in the
2432 filesystem is "trimmed", that is, given back to the host device,
2433 thus making disk images more sparse, allowing unused space in qcow2
2434 files to be reused, etc.
2435 This operation requires support in libguestfs, the mounted
2437 filesystem, the host filesystem, qemu and the host kernel. If this
2438 support isn't present it may give an error or even appear to run
2439 but do nothing.
2440 In the case where the kernel vfs driver does not support trimming,
2442 this call will fail with errno set to "ENOTSUP". Currently this
2443 happens when trying to trim FAT filesystems.
2444 See also "$g->zero_free_space". That is a slightly different
2446 operation that turns free space in the filesystem into zeroes. It
2447 is valid to call "$g->fstrim" either instead of, or after calling
2448 "$g->zero_free_space".
2449 This function depends on the feature "fstrim". See also
2451 "$g->feature-available".
2452 $append = $g->get_append ();
2454 Return the additional kernel options which are added to the
2455 libguestfs appliance kernel command line.
2456 If "NULL" then no options are added.
2458 $backend = $g->get_attach_method ();
2460 Return the current backend.
2461 See "$g->set_backend" and "BACKEND" in guestfs(3).
2463 This function is deprecated. In new code, use the "get_backend"
2465 call instead.
2466 Deprecated functions will not be removed from the API, but the fact
2468 that they are deprecated indicates that there are problems with
2469 correct use of these functions.
2470 $autosync = $g->get_autosync ();
2472 Get the autosync flag.
2473 $backend = $g->get_backend ();
2475 Return the current backend.
2476 This handle property was previously called the "attach method".
2478 See "$g->set_backend" and "BACKEND" in guestfs(3).
2480 $val = $g->get_backend_setting ($name);
2482 Find a backend setting string which is either "name" or begins with
2483 "name=". If "name", this returns the string "1". If "name=", this
2484 returns the part after the equals sign (which may be an empty
2485 string).
2486 If no such setting is found, this function throws an error. The
2488 errno (see "$g->last_errno") will be "ESRCH" in this case.
2489 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
2491 @settings = $g->get_backend_settings ();
2493 Return the current backend settings.
2494 This call returns all backend settings strings. If you want to
2496 find a single backend setting, see "$g->get_backend_setting".
2497 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
2499 $cachedir = $g->get_cachedir ();
2501 Get the directory used by the handle to store the appliance cache.
2502 $direct = $g->get_direct ();
2504 Return the direct appliance mode flag.
2505 This function is deprecated. In new code, use the
2507 "internal_get_console_socket" call instead.
2508 Deprecated functions will not be removed from the API, but the fact
2510 that they are deprecated indicates that there are problems with
2511 correct use of these functions.
2512 $attrs = $g->get_e2attrs ($file);
2514 This returns the file attributes associated with file.
2515 The attributes are a set of bits associated with each inode which
2517 affect the behaviour of the file. The attributes are returned as a
2518 string of letters (described below). The string may be empty,
2519 indicating that no file attributes are set for this file.
2520 These attributes are only present when the file is located on an
2522 ext2/3/4 filesystem. Using this call on other filesystem types
2523 will result in an error.
2524 The characters (file attributes) in the returned string are
2526 currently:
2527 'A' When the file is accessed, its atime is not modified.
2529 'a' The file is append-only.
2531 'c' The file is compressed on-disk.
2533 'D' (Directories only.) Changes to this directory are written
2535 synchronously to disk.
2536 'd' The file is not a candidate for backup (see dump(8)).
2538 'E' The file has compression errors.
2540 'e' The file is using extents.
2542 'h' The file is storing its blocks in units of the filesystem
2544 blocksize instead of sectors.
2545 'I' (Directories only.) The directory is using hashed trees.
2547 'i' The file is immutable. It cannot be modified, deleted or
2549 renamed. No link can be created to this file.
2550 'j' The file is data-journaled.
2552 's' When the file is deleted, all its blocks will be zeroed.
2554 'S' Changes to this file are written synchronously to disk.
2556 'T' (Directories only.) This is a hint to the block allocator that
2558 subdirectories contained in this directory should be spread
2559 across blocks. If not present, the block allocator will try to
2560 group subdirectories together.
2561 't' For a file, this disables tail-merging. (Not used by upstream
2563 implementations of ext2.)
2564 'u' When the file is deleted, its blocks will be saved, allowing
2566 the file to be undeleted.
2567 'X' The raw contents of the compressed file may be accessed.
2569 'Z' The compressed file is dirty.
2571 More file attributes may be added to this list later. Not all file
2573 attributes may be set for all kinds of files. For detailed
2574 information, consult the chattr(1) man page.
2575 See also "$g->set_e2attrs".
2577 Don't confuse these attributes with extended attributes (see
2579 "$g->getxattr").
2580 $generation = $g->get_e2generation ($file);
2582 This returns the ext2 file generation of a file. The generation
2583 (which used to be called the "version") is a number associated with
2584 an inode. This is most commonly used by NFS servers.
2585 The generation is only present when the file is located on an
2587 ext2/3/4 filesystem. Using this call on other filesystem types
2588 will result in an error.
2589 See "$g->set_e2generation".
2591 $label = $g->get_e2label ($device);
2593 This returns the ext2/3/4 filesystem label of the filesystem on
2594 "device".
2595 This function is deprecated. In new code, use the "vfs_label" call
2597 instead.
2598 Deprecated functions will not be removed from the API, but the fact
2600 that they are deprecated indicates that there are problems with
2601 correct use of these functions.
2602 $uuid = $g->get_e2uuid ($device);
2604 This returns the ext2/3/4 filesystem UUID of the filesystem on
2605 "device".
2606 This function is deprecated. In new code, use the "vfs_uuid" call
2608 instead.
2609 Deprecated functions will not be removed from the API, but the fact
2611 that they are deprecated indicates that there are problems with
2612 correct use of these functions.
2613 $hv = $g->get_hv ();
2615 Return the current hypervisor binary.
2616 This is always non-NULL. If it wasn't set already, then this will
2618 return the default qemu binary name.
2619 $identifier = $g->get_identifier ();
2621 Get the handle identifier. See "$g->set_identifier".
2622 $challenge = $g->get_libvirt_requested_credential_challenge ($index);
2624 Get the challenge (provided by libvirt) for the "index"'th
2625 requested credential. If libvirt did not provide a challenge, this
2626 returns the empty string "".
2627 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2629 example code.
2630 $defresult = $g->get_libvirt_requested_credential_defresult ($index);
2632 Get the default result (provided by libvirt) for the "index"'th
2633 requested credential. If libvirt did not provide a default result,
2634 this returns the empty string "".
2635 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2637 example code.
2638 $prompt = $g->get_libvirt_requested_credential_prompt ($index);
2640 Get the prompt (provided by libvirt) for the "index"'th requested
2641 credential. If libvirt did not provide a prompt, this returns the
2642 empty string "".
2643 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2645 example code.
2646 @creds = $g->get_libvirt_requested_credentials ();
2648 This should only be called during the event callback for events of
2649 type "GUESTFS_EVENT_LIBVIRT_AUTH".
2650 Return the list of credentials requested by libvirt. Possible
2652 values are a subset of the strings provided when you called
2653 "$g->set_libvirt_supported_credentials".
2654 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2656 example code.
2657 $memsize = $g->get_memsize ();
2659 This gets the memory size in megabytes allocated to the hypervisor.
2660 If "$g->set_memsize" was not called on this handle, and if
2662 "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
2663 default value for memsize.
2664 For more information on the architecture of libguestfs, see
2666 guestfs(3).
2667 $network = $g->get_network ();
2669 This returns the enable network flag.
2670 $path = $g->get_path ();
2672 Return the current search path.
2673 This is always non-NULL. If it wasn't set already, then this will
2675 return the default path.
2676 $pgroup = $g->get_pgroup ();
2678 This returns the process group flag.
2679 $pid = $g->get_pid ();
2681 Return the process ID of the hypervisor. If there is no hypervisor
2682 running, then this will return an error.
2683 This is an internal call used for debugging and testing.
2685 $program = $g->get_program ();
2687 Get the program name. See "$g->set_program".
2688 $hv = $g->get_qemu ();
2690 Return the current hypervisor binary (usually qemu).
2691 This is always non-NULL. If it wasn't set already, then this will
2693 return the default qemu binary name.
2694 This function is deprecated. In new code, use the "get_hv" call
2696 instead.
2697 Deprecated functions will not be removed from the API, but the fact
2699 that they are deprecated indicates that there are problems with
2700 correct use of these functions.
2701 $recoveryproc = $g->get_recovery_proc ();
2703 Return the recovery process enabled flag.
2704 $selinux = $g->get_selinux ();
2706 This returns the current setting of the selinux flag which is
2707 passed to the appliance at boot time. See "$g->set_selinux".
2708 For more information on the architecture of libguestfs, see
2710 guestfs(3).
2711 This function is deprecated. In new code, use the
2713 "selinux_relabel" call instead.
2714 Deprecated functions will not be removed from the API, but the fact
2716 that they are deprecated indicates that there are problems with
2717 correct use of these functions.
2718 $smp = $g->get_smp ();
2720 This returns the number of virtual CPUs assigned to the appliance.
2721 $sockdir = $g->get_sockdir ();
2723 Get the directory used by the handle to store temporary socket and
2724 PID files.
2725 This is different from "$g->get_tmpdir", as we need shorter paths
2727 for sockets (due to the limited buffers of filenames for UNIX
2728 sockets), and "$g->get_tmpdir" may be too long for them.
2729 Furthermore, sockets and PID files must be accessible to such
2730 background services started by libguestfs that may not have
2731 permission to access the temporary directory returned by
2732 "$g->get_tmpdir".
2733 The environment variable "XDG_RUNTIME_DIR" controls the default
2735 value: If "XDG_RUNTIME_DIR" is set, then that is the default. Else
2736 /tmp is the default.
2737 $state = $g->get_state ();
2739 This returns the current state as an opaque integer. This is only
2740 useful for printing debug and internal error messages.
2741 For more information on states, see guestfs(3).
2743 $tmpdir = $g->get_tmpdir ();
2745 Get the directory used by the handle to store temporary files.
2746 $trace = $g->get_trace ();
2748 Return the command trace flag.
2749 $mask = $g->get_umask ();
2751 Return the current umask. By default the umask is 022 unless it
2752 has been set by calling "$g->umask".
2753 $verbose = $g->get_verbose ();
2755 This returns the verbose messages flag.
2756 $context = $g->getcon ();
2758 This gets the SELinux security context of the daemon.
2759 See the documentation about SELINUX in guestfs(3), and "$g->setcon"
2761 This function depends on the feature "selinux". See also
2763 "$g->feature-available".
2764 This function is deprecated. In new code, use the
2766 "selinux_relabel" call instead.
2767 Deprecated functions will not be removed from the API, but the fact
2769 that they are deprecated indicates that there are problems with
2770 correct use of these functions.
2771 $xattr = $g->getxattr ($path, $name);
2773 Get a single extended attribute from file "path" named "name".
2774 This call follows symlinks. If you want to lookup an extended
2775 attribute for the symlink itself, use "$g->lgetxattr".
2776 Normally it is better to get all extended attributes from a file in
2778 one go by calling "$g->getxattrs". However some Linux filesystem
2779 implementations are buggy and do not provide a way to list out
2780 attributes. For these filesystems (notably ntfs-3g) you have to
2781 know the names of the extended attributes you want in advance and
2782 call this function.
2783 Extended attribute values are blobs of binary data. If there is no
2785 extended attribute named "name", this returns an error.
2786 See also: "$g->getxattrs", "$g->lgetxattr", attr(5).
2788 This function depends on the feature "linuxxattrs". See also
2790 "$g->feature-available".
2791 @xattrs = $g->getxattrs ($path);
2793 This call lists the extended attributes of the file or directory
2794 "path".
2795 At the system call level, this is a combination of the listxattr(2)
2797 and getxattr(2) calls.
2798 See also: "$g->lgetxattrs", attr(5).
2800 This function depends on the feature "linuxxattrs". See also
2802 "$g->feature-available".
2803 @paths = $g->glob_expand ($pattern [, directoryslash =>
2805 $directoryslash]);
2806 This command searches for all the pathnames matching "pattern"
2807 according to the wildcard expansion rules used by the shell.
2808 If no paths match, then this returns an empty list (note: not an
2810 error).
2811 It is just a wrapper around the C glob(3) function with flags
2813 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
2814 "directoryslash" controls whether use the "GLOB_MARK" flag for
2816 glob(3), and it defaults to true. It can be explicitly set as off
2817 to return no trailing slashes in filenames of directories.
2818 Notice that there is no equivalent command for expanding a device
2820 name (eg. /dev/sd*). Use "$g->list_devices", "$g->list_partitions"
2821 etc functions instead.
2822 @paths = $g->glob_expand_opts ($pattern [, directoryslash =>
2824 $directoryslash]);
2825 This is an alias of "glob_expand".
2826 @lines = $g->grep ($regex, $path [, extended => $extended] [, fixed =>
2828 $fixed] [, insensitive => $insensitive] [, compressed => $compressed]);
2829 This calls the external grep(1) program and returns the matching
2830 lines.
2831 The optional flags are:
2833 "extended"
2835 Use extended regular expressions. This is the same as using
2836 the -E flag.
2837 "fixed"
2839 Match fixed (don't use regular expressions). This is the same
2840 as using the -F flag.
2841 "insensitive"
2843 Match case-insensitive. This is the same as using the -i flag.
2844 "compressed"
2846 Use zgrep(1) instead of grep(1). This allows the input to be
2847 compress- or gzip-compressed.
2848 Because of the message protocol, there is a transfer limit of
2850 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2851 guestfs(3).
2852 @lines = $g->grep_opts ($regex, $path [, extended => $extended] [,
2854 fixed => $fixed] [, insensitive => $insensitive] [, compressed =>
2855 $compressed]);
2856 This is an alias of "grep".
2857 @lines = $g->grepi ($regex, $path);
2859 This calls the external "grep -i" program and returns the matching
2860 lines.
2861 Because of the message protocol, there is a transfer limit of
2863 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2864 guestfs(3).
2865 This function is deprecated. In new code, use the "grep" call
2867 instead.
2868 Deprecated functions will not be removed from the API, but the fact
2870 that they are deprecated indicates that there are problems with
2871 correct use of these functions.
2872 $g->grub_install ($root, $device);
2874 This command installs GRUB 1 (the Grand Unified Bootloader) on
2875 "device", with the root directory being "root".
2876 Notes:
2878 • There is currently no way in the API to install grub2, which is
2880 used by most modern Linux guests. It is possible to run the
2881 grub2 command from the guest, although see the caveats in
2882 "RUNNING COMMANDS" in guestfs(3).
2883 • This uses grub-install(8) from the host. Unfortunately grub is
2885 not always compatible with itself, so this only works in rather
2886 narrow circumstances. Careful testing with each guest version
2887 is advisable.
2888 • If grub-install reports the error "No suitable drive was found
2890 in the generated device map." it may be that you need to
2891 create a /boot/grub/device.map file first that contains the
2892 mapping between grub device names and Linux device names. It
2893 is usually sufficient to create a file containing:
2894 (hd0) /dev/vda
2896 replacing /dev/vda with the name of the installation device.
2898 This function depends on the feature "grub". See also
2900 "$g->feature-available".
2901 @lines = $g->head ($path);
2903 This command returns up to the first 10 lines of a file as a list
2904 of strings.
2905 Because of the message protocol, there is a transfer limit of
2907 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2908 guestfs(3).
2909 @lines = $g->head_n ($nrlines, $path);
2911 If the parameter "nrlines" is a positive number, this returns the
2912 first "nrlines" lines of the file "path".
2913 If the parameter "nrlines" is a negative number, this returns lines
2915 from the file "path", excluding the last "nrlines" lines.
2916 If the parameter "nrlines" is zero, this returns an empty list.
2918 Because of the message protocol, there is a transfer limit of
2920 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2921 guestfs(3).
2922 $dump = $g->hexdump ($path);
2924 This runs "hexdump -C" on the given "path". The result is the
2925 human-readable, canonical hex dump of the file.
2926 Because of the message protocol, there is a transfer limit of
2928 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2929 guestfs(3).
2930 $g->hivex_close ();
2932 Close the current hivex handle.
2933 This is a wrapper around the hivex(3) call of the same name.
2935 This function depends on the feature "hivex". See also
2937 "$g->feature-available".
2938 $g->hivex_commit ($filename);
2940 Commit (write) changes to the hive.
2941 If the optional filename parameter is null, then the changes are
2943 written back to the same hive that was opened. If this is not null
2944 then they are written to the alternate filename given and the
2945 original hive is left untouched.
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 $nodeh = $g->hivex_node_add_child ($parent, $name);
2953 Add a child node to "parent" named "name".
2954 This is a wrapper around the hivex(3) call of the same name.
2956 This function depends on the feature "hivex". See also
2958 "$g->feature-available".
2959 @nodehs = $g->hivex_node_children ($nodeh);
2961 Return the list of nodes which are subkeys of "nodeh".
2962 This is a wrapper around the hivex(3) call of the same name.
2964 This function depends on the feature "hivex". See also
2966 "$g->feature-available".
2967 $g->hivex_node_delete_child ($nodeh);
2969 Delete "nodeh", recursively if necessary.
2970 This is a wrapper around the hivex(3) call of the same name.
2972 This function depends on the feature "hivex". See also
2974 "$g->feature-available".
2975 $child = $g->hivex_node_get_child ($nodeh, $name);
2977 Return the child of "nodeh" with the name "name", if it exists.
2978 This can return 0 meaning the name was not found.
2979 This is a wrapper around the hivex(3) call of the same name.
2981 This function depends on the feature "hivex". See also
2983 "$g->feature-available".
2984 $valueh = $g->hivex_node_get_value ($nodeh, $key);
2986 Return the value attached to "nodeh" which has the name "key", if
2987 it exists. This can return 0 meaning the key was not found.
2988 This is a wrapper around the hivex(3) call of the same name.
2990 This function depends on the feature "hivex". See also
2992 "$g->feature-available".
2993 $name = $g->hivex_node_name ($nodeh);
2995 Return the name of "nodeh".
2996 This is a wrapper around the hivex(3) call of the same name.
2998 This function depends on the feature "hivex". See also
3000 "$g->feature-available".
3001 $parent = $g->hivex_node_parent ($nodeh);
3003 Return the parent node of "nodeh".
3004 This is a wrapper around the hivex(3) call of the same name.
3006 This function depends on the feature "hivex". See also
3008 "$g->feature-available".
3009 $g->hivex_node_set_value ($nodeh, $key, $t, $val);
3011 Set or replace a single value under the node "nodeh". The "key" is
3012 the name, "t" is the type, and "val" is the data.
3013 This is a wrapper around the hivex(3) call of the same name.
3015 This function depends on the feature "hivex". See also
3017 "$g->feature-available".
3018 @valuehs = $g->hivex_node_values ($nodeh);
3020 Return the array of (key, datatype, data) tuples attached to
3021 "nodeh".
3022 This is a wrapper around the hivex(3) call of the same name.
3024 This function depends on the feature "hivex". See also
3026 "$g->feature-available".
3027 $g->hivex_open ($filename [, verbose => $verbose] [, debug => $debug]
3029 [, write => $write] [, unsafe => $unsafe]);
3030 Open the Windows Registry hive file named filename. If there was
3031 any previous hivex handle associated with this guestfs session,
3032 then it is closed.
3033 This is a wrapper around the hivex(3) call of the same name.
3035 This function depends on the feature "hivex". See also
3037 "$g->feature-available".
3038 $nodeh = $g->hivex_root ();
3040 Return the root node of the hive.
3041 This is a wrapper around the hivex(3) call of the same name.
3043 This function depends on the feature "hivex". See also
3045 "$g->feature-available".
3046 $key = $g->hivex_value_key ($valueh);
3048 Return the key (name) field of a (key, datatype, data) tuple.
3049 This is a wrapper around the hivex(3) call of the same name.
3051 This function depends on the feature "hivex". See also
3053 "$g->feature-available".
3054 $databuf = $g->hivex_value_string ($valueh);
3056 This calls "$g->hivex_value_value" (which returns the data field
3057 from a hivex value tuple). It then assumes that the field is a
3058 UTF-16LE string and converts the result to UTF-8 (or if this is not
3059 possible, it returns an error).
3060 This is useful for reading strings out of the Windows registry.
3062 However it is not foolproof because the registry is not strongly-
3063 typed and fields can contain arbitrary or unexpected data.
3064 This function depends on the feature "hivex". See also
3066 "$g->feature-available".
3067 $datatype = $g->hivex_value_type ($valueh);
3069 Return the data type field from a (key, datatype, data) tuple.
3070 This is a wrapper around the hivex(3) call of the same name.
3072 This function depends on the feature "hivex". See also
3074 "$g->feature-available".
3075 $databuf = $g->hivex_value_utf8 ($valueh);
3077 This calls "$g->hivex_value_value" (which returns the data field
3078 from a hivex value tuple). It then assumes that the field is a
3079 UTF-16LE string and converts the result to UTF-8 (or if this is not
3080 possible, it returns an error).
3081 This is useful for reading strings out of the Windows registry.
3083 However it is not foolproof because the registry is not strongly-
3084 typed and fields can contain arbitrary or unexpected data.
3085 This function depends on the feature "hivex". See also
3087 "$g->feature-available".
3088 This function is deprecated. In new code, use the
3090 "hivex_value_string" call instead.
3091 Deprecated functions will not be removed from the API, but the fact
3093 that they are deprecated indicates that there are problems with
3094 correct use of these functions.
3095 $databuf = $g->hivex_value_value ($valueh);
3097 Return the data field of a (key, datatype, data) tuple.
3098 This is a wrapper around the hivex(3) call of the same name.
3100 See also: "$g->hivex_value_utf8".
3102 This function depends on the feature "hivex". See also
3104 "$g->feature-available".
3105 $content = $g->initrd_cat ($initrdpath, $filename);
3107 This command unpacks the file filename from the initrd file called
3108 initrdpath. The filename must be given without the initial /
3109 character.
3110 For example, in guestfish you could use the following command to
3112 examine the boot script (usually called /init) contained in a Linux
3113 initrd or initramfs image:
3114 initrd-cat /boot/initrd-<version>.img init
3116 See also "$g->initrd_list".
3118 Because of the message protocol, there is a transfer limit of
3120 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
3121 guestfs(3).
3122 @filenames = $g->initrd_list ($path);
3124 This command lists out files contained in an initrd.
3125 The files are listed without any initial / character. The files
3127 are listed in the order they appear (not necessarily alphabetical).
3128 Directory names are listed as separate items.
3129 Old Linux kernels (2.4 and earlier) used a compressed ext2
3131 filesystem as initrd. We only support the newer initramfs format
3132 (compressed cpio files).
3133 $wd = $g->inotify_add_watch ($path, $mask);
3135 Watch "path" for the events listed in "mask".
3136 Note that if "path" is a directory then events within that
3138 directory are watched, but this does not happen recursively (in
3139 subdirectories).
3140 Note for non-C or non-Linux callers: the inotify events are defined
3142 by the Linux kernel ABI and are listed in
3143 /usr/include/sys/inotify.h.
3144 This function depends on the feature "inotify". See also
3146 "$g->feature-available".
3147 $g->inotify_close ();
3149 This closes the inotify handle which was previously opened by
3150 inotify_init. It removes all watches, throws away any pending
3151 events, and deallocates all resources.
3152 This function depends on the feature "inotify". See also
3154 "$g->feature-available".
3155 @paths = $g->inotify_files ();
3157 This function is a helpful wrapper around "$g->inotify_read" which
3158 just returns a list of pathnames of objects that were touched. The
3159 returned pathnames are sorted and deduplicated.
3160 This function depends on the feature "inotify". See also
3162 "$g->feature-available".
3163 $g->inotify_init ($maxevents);
3165 This command creates a new inotify handle. The inotify subsystem
3166 can be used to notify events which happen to objects in the guest
3167 filesystem.
3168 "maxevents" is the maximum number of events which will be queued up
3170 between calls to "$g->inotify_read" or "$g->inotify_files". If
3171 this is passed as 0, then the kernel (or previously set) default is
3172 used. For Linux 2.6.29 the default was 16384 events. Beyond this
3173 limit, the kernel throws away events, but records the fact that it
3174 threw them away by setting a flag "IN_Q_OVERFLOW" in the returned
3175 structure list (see "$g->inotify_read").
3176 Before any events are generated, you have to add some watches to
3178 the internal watch list. See: "$g->inotify_add_watch" and
3179 "$g->inotify_rm_watch".
3180 Queued up events should be read periodically by calling
3182 "$g->inotify_read" (or "$g->inotify_files" which is just a helpful
3183 wrapper around "$g->inotify_read"). If you don't read the events
3184 out often enough then you risk the internal queue overflowing.
3185 The handle should be closed after use by calling
3187 "$g->inotify_close". This also removes any watches automatically.
3188 See also inotify(7) for an overview of the inotify interface as
3190 exposed by the Linux kernel, which is roughly what we expose via
3191 libguestfs. Note that there is one global inotify handle per
3192 libguestfs instance.
3193 This function depends on the feature "inotify". See also
3195 "$g->feature-available".
3196 @events = $g->inotify_read ();
3198 Return the complete queue of events that have happened since the
3199 previous read call.
3200 If no events have happened, this returns an empty list.
3202 Note: In order to make sure that all events have been read, you
3204 must call this function repeatedly until it returns an empty list.
3205 The reason is that the call will read events up to the maximum
3206 appliance-to-host message size and leave remaining events in the
3207 queue.
3208 This function depends on the feature "inotify". See also
3210 "$g->feature-available".
3211 $g->inotify_rm_watch ($wd);
3213 Remove a previously defined inotify watch. See
3214 "$g->inotify_add_watch".
3215 This function depends on the feature "inotify". See also
3217 "$g->feature-available".
3218 $arch = $g->inspect_get_arch ($root);
3220 This returns the architecture of the inspected operating system.
3221 The possible return values are listed under
3222 "$g->file_architecture".
3223 If the architecture could not be determined, then the string
3225 "unknown" is returned.
3226 Please read "INSPECTION" in guestfs(3) for more details.
3228 $buildid = $g->inspect_get_build_id ($root);
3230 This returns the build ID of the system, or the string "unknown" if
3231 the system does not have a build ID.
3232 For Windows, this gets the build number. Although it is returned
3234 as a string, it is (so far) always a number. See
3235 <https://en.wikipedia.org/wiki/List_of_Microsoft_Windows_versions>
3236 for some possible values.
3237 For Linux, this returns the "BUILD_ID" string from /etc/os-release,
3239 although this is not often used.
3240 Please read "INSPECTION" in guestfs(3) for more details.
3242 $distro = $g->inspect_get_distro ($root);
3244 This returns the distro (distribution) of the inspected operating
3245 system.
3246 Currently defined distros are:
3248 "alpinelinux"
3250 Alpine Linux.
3251 "altlinux"
3253 ALT Linux.
3254 "archlinux"
3256 Arch Linux.
3257 "buildroot"
3259 Buildroot-derived distro, but not one we specifically
3260 recognize.
3261 "centos"
3263 CentOS.
3264 "cirros"
3266 Cirros.
3267 "coreos"
3269 CoreOS.
3270 "debian"
3272 Debian.
3273 "fedora"
3275 Fedora.
3276 "freebsd"
3278 FreeBSD.
3279 "freedos"
3281 FreeDOS.
3282 "frugalware"
3284 Frugalware.
3285 "gentoo"
3287 Gentoo.
3288 "kalilinux"
3290 Kali Linux.
3291 "kylin"
3293 Kylin.
3294 "linuxmint"
3296 Linux Mint.
3297 "mageia"
3299 Mageia.
3300 "mandriva"
3302 Mandriva.
3303 "meego"
3305 MeeGo.
3306 "msdos"
3308 Microsoft DOS.
3309 "neokylin"
3311 NeoKylin.
3312 "netbsd"
3314 NetBSD.
3315 "openbsd"
3317 OpenBSD.
3318 "openmandriva"
3320 OpenMandriva Lx.
3321 "opensuse"
3323 OpenSUSE.
3324 "oraclelinux"
3326 Oracle Linux.
3327 "pardus"
3329 Pardus.
3330 "pldlinux"
3332 PLD Linux.
3333 "redhat-based"
3335 Some Red Hat-derived distro.
3336 "rhel"
3338 Red Hat Enterprise Linux.
3339 "rocky"
3341 Rocky Linux.
3342 "scientificlinux"
3344 Scientific Linux.
3345 "slackware"
3347 Slackware.
3348 "sles"
3350 SuSE Linux Enterprise Server or Desktop.
3351 "suse-based"
3353 Some openSuSE-derived distro.
3354 "ttylinux"
3356 ttylinux.
3357 "ubuntu"
3359 Ubuntu.
3360 "unknown"
3362 The distro could not be determined.
3363 "voidlinux"
3365 Void Linux.
3366 "windows"
3368 Windows does not have distributions. This string is returned
3369 if the OS type is Windows.
3370 Future versions of libguestfs may return other strings here. The
3372 caller should be prepared to handle any string.
3373 Please read "INSPECTION" in guestfs(3) for more details.
3375 %drives = $g->inspect_get_drive_mappings ($root);
3377 This call is useful for Windows which uses a primitive system of
3378 assigning drive letters (like C:\) to partitions. This inspection
3379 API examines the Windows Registry to find out how disks/partitions
3380 are mapped to drive letters, and returns a hash table as in the
3381 example below:
3382 C => /dev/vda2
3384 E => /dev/vdb1
3385 F => /dev/vdc1
3386 Note that keys are drive letters. For Windows, the key is case
3388 insensitive and just contains the drive letter, without the
3389 customary colon separator character.
3390 In future we may support other operating systems that also used
3392 drive letters, but the keys for those might not be case insensitive
3393 and might be longer than 1 character. For example in OS-9, hard
3394 drives were named "h0", "h1" etc.
3395 For Windows guests, currently only hard drive mappings are
3397 returned. Removable disks (eg. DVD-ROMs) are ignored.
3398 For guests that do not use drive mappings, or if the drive mappings
3400 could not be determined, this returns an empty hash table.
3401 Please read "INSPECTION" in guestfs(3) for more details. See also
3403 "$g->inspect_get_mountpoints", "$g->inspect_get_filesystems".
3404 @filesystems = $g->inspect_get_filesystems ($root);
3406 This returns a list of all the filesystems that we think are
3407 associated with this operating system. This includes the root
3408 filesystem, other ordinary filesystems, and non-mounted devices
3409 like swap partitions.
3410 In the case of a multi-boot virtual machine, it is possible for a
3412 filesystem to be shared between operating systems.
3413 Please read "INSPECTION" in guestfs(3) for more details. See also
3415 "$g->inspect_get_mountpoints".
3416 $format = $g->inspect_get_format ($root);
3418 Before libguestfs 1.38, there was some unreliable support for
3419 detecting installer CDs. This API would return:
3420 "installed"
3422 This is an installed operating system.
3423 "installer"
3425 The disk image being inspected is not an installed operating
3426 system, but a bootable install disk, live CD, or similar.
3427 "unknown"
3429 The format of this disk image is not known.
3430 In libguestfs ≥ 1.38, this only returns "installed". Use libosinfo
3432 directly to detect installer CDs.
3433 Please read "INSPECTION" in guestfs(3) for more details.
3435 This function is deprecated. There is no replacement. Consult the
3437 API documentation in guestfs(3) for further information.
3438 Deprecated functions will not be removed from the API, but the fact
3440 that they are deprecated indicates that there are problems with
3441 correct use of these functions.
3442 $hostname = $g->inspect_get_hostname ($root);
3444 This function returns the hostname of the operating system as found
3445 by inspection of the guest’s configuration files.
3446 If the hostname could not be determined, then the string "unknown"
3448 is returned.
3449 Please read "INSPECTION" in guestfs(3) for more details.
3451 $icon = $g->inspect_get_icon ($root [, favicon => $favicon] [,
3453 highquality => $highquality]);
3454 This function returns an icon corresponding to the inspected
3455 operating system. The icon is returned as a buffer containing a
3456 PNG image (re-encoded to PNG if necessary).
3457 If it was not possible to get an icon this function returns a zero-
3459 length (non-NULL) buffer. Callers must check for this case.
3460 Libguestfs will start by looking for a file called /etc/favicon.png
3462 or C:\etc\favicon.png and if it has the correct format, the
3463 contents of this file will be returned. You can disable favicons
3464 by passing the optional "favicon" boolean as false (default is
3465 true).
3466 If finding the favicon fails, then we look in other places in the
3468 guest for a suitable icon.
3469 If the optional "highquality" boolean is true then only high
3471 quality icons are returned, which means only icons of high
3472 resolution with an alpha channel. The default (false) is to return
3473 any icon we can, even if it is of substandard quality.
3474 Notes:
3476 • Unlike most other inspection API calls, the guest’s disks must
3478 be mounted up before you call this, since it needs to read
3479 information from the guest filesystem during the call.
3480 • Security: The icon data comes from the untrusted guest, and
3482 should be treated with caution. PNG files have been known to
3483 contain exploits. Ensure that libpng (or other relevant
3484 libraries) are fully up to date before trying to process or
3485 display the icon.
3486 • The PNG image returned can be any size. It might not be
3488 square. Libguestfs tries to return the largest, highest
3489 quality icon available. The application must scale the icon to
3490 the required size.
3491 • Extracting icons from Windows guests requires the external
3493 wrestool(1) program from the "icoutils" package, and several
3494 programs (bmptopnm(1), pnmtopng(1), pamcut(1)) from the
3495 "netpbm" package. These must be installed separately.
3496 • Operating system icons are usually trademarks. Seek legal
3498 advice before using trademarks in applications.
3499 $major = $g->inspect_get_major_version ($root);
3501 This returns the major version number of the inspected operating
3502 system.
3503 Windows uses a consistent versioning scheme which is not reflected
3505 in the popular public names used by the operating system. Notably
3506 the operating system known as "Windows 7" is really version 6.1
3507 (ie. major = 6, minor = 1). You can find out the real versions
3508 corresponding to releases of Windows by consulting Wikipedia or
3509 MSDN.
3510 If the version could not be determined, then 0 is returned.
3512 Please read "INSPECTION" in guestfs(3) for more details.
3514 $minor = $g->inspect_get_minor_version ($root);
3516 This returns the minor version number of the inspected operating
3517 system.
3518 If the version could not be determined, then 0 is returned.
3520 Please read "INSPECTION" in guestfs(3) for more details. See also
3522 "$g->inspect_get_major_version".
3523 %mountpoints = $g->inspect_get_mountpoints ($root);
3525 This returns a hash of where we think the filesystems associated
3526 with this operating system should be mounted. Callers should note
3527 that this is at best an educated guess made by reading
3528 configuration files such as /etc/fstab. In particular note that
3529 this may return filesystems which are non-existent or not mountable
3530 and callers should be prepared to handle or ignore failures if they
3531 try to mount them.
3532 Each element in the returned hashtable has a key which is the path
3534 of the mountpoint (eg. /boot) and a value which is the filesystem
3535 that would be mounted there (eg. /dev/sda1).
3536 Non-mounted devices such as swap devices are not returned in this
3538 list.
3539 For operating systems like Windows which still use drive letters,
3541 this call will only return an entry for the first drive "mounted
3542 on" /. For information about the mapping of drive letters to
3543 partitions, see "$g->inspect_get_drive_mappings".
3544 Please read "INSPECTION" in guestfs(3) for more details. See also
3546 "$g->inspect_get_filesystems".
3547 $id = $g->inspect_get_osinfo ($root);
3549 This function returns a possible short ID for libosinfo
3550 corresponding to the guest.
3551 Note: The returned ID is only a guess by libguestfs, and nothing
3553 ensures that it actually exists in osinfo-db.
3554 If no ID could not be determined, then the string "unknown" is
3556 returned.
3557 $packageformat = $g->inspect_get_package_format ($root);
3559 This function and "$g->inspect_get_package_management" return the
3560 package format and package management tool used by the inspected
3561 operating system. For example for Fedora these functions would
3562 return "rpm" (package format), and "yum" or "dnf" (package
3563 management).
3564 This returns the string "unknown" if we could not determine the
3566 package format or if the operating system does not have a real
3567 packaging system (eg. Windows).
3568 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
3570 "pkgsrc", "apk", "xbps". Future versions of libguestfs may return
3571 other strings.
3572 Please read "INSPECTION" in guestfs(3) for more details.
3574 $packagemanagement = $g->inspect_get_package_management ($root);
3576 "$g->inspect_get_package_format" and this function return the
3577 package format and package management tool used by the inspected
3578 operating system. For example for Fedora these functions would
3579 return "rpm" (package format), and "yum" or "dnf" (package
3580 management).
3581 This returns the string "unknown" if we could not determine the
3583 package management tool or if the operating system does not have a
3584 real packaging system (eg. Windows).
3585 Possible strings include: "yum", "dnf", "up2date", "apt" (for all
3587 Debian derivatives), "portage", "pisi", "pacman", "urpmi",
3588 "zypper", "apk", "xbps". Future versions of libguestfs may return
3589 other strings.
3590 Please read "INSPECTION" in guestfs(3) for more details.
3592 $product = $g->inspect_get_product_name ($root);
3594 This returns the product name of the inspected operating system.
3595 The product name is generally some freeform string which can be
3596 displayed to the user, but should not be parsed by programs.
3597 If the product name could not be determined, then the string
3599 "unknown" is returned.
3600 Please read "INSPECTION" in guestfs(3) for more details.
3602 $variant = $g->inspect_get_product_variant ($root);
3604 This returns the product variant of the inspected operating system.
3605 For Windows guests, this returns the contents of the Registry key
3607 "HKLM\Software\Microsoft\Windows NT\CurrentVersion"
3608 "InstallationType" which is usually a string such as "Client" or
3609 "Server" (other values are possible). This can be used to
3610 distinguish consumer and enterprise versions of Windows that have
3611 the same version number (for example, Windows 7 and Windows 2008
3612 Server are both version 6.1, but the former is "Client" and the
3613 latter is "Server").
3614 For enterprise Linux guests, in future we intend this to return the
3616 product variant such as "Desktop", "Server" and so on. But this is
3617 not implemented at present.
3618 If the product variant could not be determined, then the string
3620 "unknown" is returned.
3621 Please read "INSPECTION" in guestfs(3) for more details. See also
3623 "$g->inspect_get_product_name", "$g->inspect_get_major_version".
3624 @roots = $g->inspect_get_roots ();
3626 This function is a convenient way to get the list of root devices,
3627 as returned from a previous call to "$g->inspect_os", but without
3628 redoing the whole inspection process.
3629 This returns an empty list if either no root devices were found or
3631 the caller has not called "$g->inspect_os".
3632 Please read "INSPECTION" in guestfs(3) for more details.
3634 $name = $g->inspect_get_type ($root);
3636 This returns the type of the inspected operating system. Currently
3637 defined types are:
3638 "linux"
3640 Any Linux-based operating system.
3641 "windows"
3643 Any Microsoft Windows operating system.
3644 "freebsd"
3646 FreeBSD.
3647 "netbsd"
3649 NetBSD.
3650 "openbsd"
3652 OpenBSD.
3653 "hurd"
3655 GNU/Hurd.
3656 "dos"
3658 MS-DOS, FreeDOS and others.
3659 "minix"
3661 MINIX.
3662 "unknown"
3664 The operating system type could not be determined.
3665 Future versions of libguestfs may return other strings here. The
3667 caller should be prepared to handle any string.
3668 Please read "INSPECTION" in guestfs(3) for more details.
3670 $controlset = $g->inspect_get_windows_current_control_set ($root);
3672 This returns the Windows CurrentControlSet of the inspected guest.
3673 The CurrentControlSet is a registry key name such as
3674 "ControlSet001".
3675 This call assumes that the guest is Windows and that the Registry
3677 could be examined by inspection. If this is not the case then an
3678 error is returned.
3679 Please read "INSPECTION" in guestfs(3) for more details.
3681 $path = $g->inspect_get_windows_software_hive ($root);
3683 This returns the path to the hive (binary Windows Registry file)
3684 corresponding to HKLM\SOFTWARE.
3685 This call assumes that the guest is Windows and that the guest has
3687 a software hive file with the right name. If this is not the case
3688 then an error is returned. This call does not check that the hive
3689 is a valid Windows Registry hive.
3690 You can use "$g->hivex_open" to read or write to the hive.
3692 Please read "INSPECTION" in guestfs(3) for more details.
3694 $path = $g->inspect_get_windows_system_hive ($root);
3696 This returns the path to the hive (binary Windows Registry file)
3697 corresponding to HKLM\SYSTEM.
3698 This call assumes that the guest is Windows and that the guest has
3700 a system hive file with the right name. If this is not the case
3701 then an error is returned. This call does not check that the hive
3702 is a valid Windows Registry hive.
3703 You can use "$g->hivex_open" to read or write to the hive.
3705 Please read "INSPECTION" in guestfs(3) for more details.
3707 $systemroot = $g->inspect_get_windows_systemroot ($root);
3709 This returns the Windows systemroot of the inspected guest. The
3710 systemroot is a directory path such as /WINDOWS.
3711 This call assumes that the guest is Windows and that the systemroot
3713 could be determined by inspection. If this is not the case then an
3714 error is returned.
3715 Please read "INSPECTION" in guestfs(3) for more details.
3717 $live = $g->inspect_is_live ($root);
3719 This is deprecated and always returns "false".
3720 Please read "INSPECTION" in guestfs(3) for more details.
3722 This function is deprecated. There is no replacement. Consult the
3724 API documentation in guestfs(3) for further information.
3725 Deprecated functions will not be removed from the API, but the fact
3727 that they are deprecated indicates that there are problems with
3728 correct use of these functions.
3729 $multipart = $g->inspect_is_multipart ($root);
3731 This is deprecated and always returns "false".
3732 Please read "INSPECTION" in guestfs(3) for more details.
3734 This function is deprecated. There is no replacement. Consult the
3736 API documentation in guestfs(3) for further information.
3737 Deprecated functions will not be removed from the API, but the fact
3739 that they are deprecated indicates that there are problems with
3740 correct use of these functions.
3741 $netinst = $g->inspect_is_netinst ($root);
3743 This is deprecated and always returns "false".
3744 Please read "INSPECTION" in guestfs(3) for more details.
3746 This function is deprecated. There is no replacement. Consult the
3748 API documentation in guestfs(3) for further information.
3749 Deprecated functions will not be removed from the API, but the fact
3751 that they are deprecated indicates that there are problems with
3752 correct use of these functions.
3753 @applications = $g->inspect_list_applications ($root);
3755 Return the list of applications installed in the operating system.
3756 Note: This call works differently from other parts of the
3758 inspection API. You have to call "$g->inspect_os", then
3759 "$g->inspect_get_mountpoints", then mount up the disks, before
3760 calling this. Listing applications is a significantly more
3761 difficult operation which requires access to the full filesystem.
3762 Also note that unlike the other "$g->inspect_get_*" calls which are
3763 just returning data cached in the libguestfs handle, this call
3764 actually reads parts of the mounted filesystems during the call.
3765 This returns an empty list if the inspection code was not able to
3767 determine the list of applications.
3768 The application structure contains the following fields:
3770 "app_name"
3772 The name of the application. For Linux guests, this is the
3773 package name.
3774 "app_display_name"
3776 The display name of the application, sometimes localized to the
3777 install language of the guest operating system.
3778 If unavailable this is returned as an empty string "". Callers
3780 needing to display something can use "app_name" instead.
3781 "app_epoch"
3783 For package managers which use epochs, this contains the epoch
3784 of the package (an integer). If unavailable, this is returned
3785 as 0.
3786 "app_version"
3788 The version string of the application or package. If
3789 unavailable this is returned as an empty string "".
3790 "app_release"
3792 The release string of the application or package, for package
3793 managers that use this. If unavailable this is returned as an
3794 empty string "".
3795 "app_install_path"
3797 The installation path of the application (on operating systems
3798 such as Windows which use installation paths). This path is in
3799 the format used by the guest operating system, it is not a
3800 libguestfs path.
3801 If unavailable this is returned as an empty string "".
3803 "app_trans_path"
3805 The install path translated into a libguestfs path. If
3806 unavailable this is returned as an empty string "".
3807 "app_publisher"
3809 The name of the publisher of the application, for package
3810 managers that use this. If unavailable this is returned as an
3811 empty string "".
3812 "app_url"
3814 The URL (eg. upstream URL) of the application. If unavailable
3815 this is returned as an empty string "".
3816 "app_source_package"
3818 For packaging systems which support this, the name of the
3819 source package. If unavailable this is returned as an empty
3820 string "".
3821 "app_summary"
3823 A short (usually one line) description of the application or
3824 package. If unavailable this is returned as an empty string
3825 "".
3826 "app_description"
3828 A longer description of the application or package. If
3829 unavailable this is returned as an empty string "".
3830 Please read "INSPECTION" in guestfs(3) for more details.
3832 This function is deprecated. In new code, use the
3834 "inspect_list_applications2" call instead.
3835 Deprecated functions will not be removed from the API, but the fact
3837 that they are deprecated indicates that there are problems with
3838 correct use of these functions.
3839 @applications2 = $g->inspect_list_applications2 ($root);
3841 Return the list of applications installed in the operating system.
3842 Note: This call works differently from other parts of the
3844 inspection API. You have to call "$g->inspect_os", then
3845 "$g->inspect_get_mountpoints", then mount up the disks, before
3846 calling this. Listing applications is a significantly more
3847 difficult operation which requires access to the full filesystem.
3848 Also note that unlike the other "$g->inspect_get_*" calls which are
3849 just returning data cached in the libguestfs handle, this call
3850 actually reads parts of the mounted filesystems during the call.
3851 This returns an empty list if the inspection code was not able to
3853 determine the list of applications.
3854 The application structure contains the following fields:
3856 "app2_name"
3858 The name of the application. For Linux guests, this is the
3859 package name.
3860 "app2_display_name"
3862 The display name of the application, sometimes localized to the
3863 install language of the guest operating system.
3864 If unavailable this is returned as an empty string "". Callers
3866 needing to display something can use "app2_name" instead.
3867 "app2_epoch"
3869 For package managers which use epochs, this contains the epoch
3870 of the package (an integer). If unavailable, this is returned
3871 as 0.
3872 "app2_version"
3874 The version string of the application or package. If
3875 unavailable this is returned as an empty string "".
3876 "app2_release"
3878 The release string of the application or package, for package
3879 managers that use this. If unavailable this is returned as an
3880 empty string "".
3881 "app2_arch"
3883 The architecture string of the application or package, for
3884 package managers that use this. If unavailable this is
3885 returned as an empty string "".
3886 "app2_install_path"
3888 The installation path of the application (on operating systems
3889 such as Windows which use installation paths). This path is in
3890 the format used by the guest operating system, it is not a
3891 libguestfs path.
3892 If unavailable this is returned as an empty string "".
3894 "app2_trans_path"
3896 The install path translated into a libguestfs path. If
3897 unavailable this is returned as an empty string "".
3898 "app2_publisher"
3900 The name of the publisher of the application, for package
3901 managers that use this. If unavailable this is returned as an
3902 empty string "".
3903 "app2_url"
3905 The URL (eg. upstream URL) of the application. If unavailable
3906 this is returned as an empty string "".
3907 "app2_source_package"
3909 For packaging systems which support this, the name of the
3910 source package. If unavailable this is returned as an empty
3911 string "".
3912 "app2_summary"
3914 A short (usually one line) description of the application or
3915 package. If unavailable this is returned as an empty string
3916 "".
3917 "app2_description"
3919 A longer description of the application or package. If
3920 unavailable this is returned as an empty string "".
3921 Please read "INSPECTION" in guestfs(3) for more details.
3923 @roots = $g->inspect_os ();
3925 This function uses other libguestfs functions and certain
3926 heuristics to inspect the disk(s) (usually disks belonging to a
3927 virtual machine), looking for operating systems.
3928 The list returned is empty if no operating systems were found.
3930 If one operating system was found, then this returns a list with a
3932 single element, which is the name of the root filesystem of this
3933 operating system. It is also possible for this function to return
3934 a list containing more than one element, indicating a dual-boot or
3935 multi-boot virtual machine, with each element being the root
3936 filesystem of one of the operating systems.
3937 You can pass the root string(s) returned to other
3939 "$g->inspect_get_*" functions in order to query further information
3940 about each operating system, such as the name and version.
3941 This function uses other libguestfs features such as "$g->mount_ro"
3943 and "$g->umount_all" in order to mount and unmount filesystems and
3944 look at the contents. This should be called with no disks
3945 currently mounted. The function may also use Augeas, so any
3946 existing Augeas handle will be closed.
3947 This function cannot decrypt encrypted disks. The caller must do
3949 that first (supplying the necessary keys) if the disk is encrypted.
3950 Please read "INSPECTION" in guestfs(3) for more details.
3952 See also "$g->list_filesystems".
3954 $flag = $g->is_blockdev ($path [, followsymlinks => $followsymlinks]);
3956 This returns "true" if and only if there is a block device with the
3957 given "path" name.
3958 If the optional flag "followsymlinks" is true, then a symlink (or
3960 chain of symlinks) that ends with a block device also causes the
3961 function to return true.
3962 This call only looks at files within the guest filesystem.
3964 Libguestfs partitions and block devices (eg. /dev/sda) cannot be
3965 used as the "path" parameter of this call.
3966 See also "$g->stat".
3968 $flag = $g->is_blockdev_opts ($path [, followsymlinks =>
3970 $followsymlinks]);
3971 This is an alias of "is_blockdev".
3972 $busy = $g->is_busy ();
3974 This always returns false. This function is deprecated with no
3975 replacement. Do not use this function.
3976 For more information on states, see guestfs(3).
3978 $flag = $g->is_chardev ($path [, followsymlinks => $followsymlinks]);
3980 This returns "true" if and only if there is a character device with
3981 the given "path" name.
3982 If the optional flag "followsymlinks" is true, then a symlink (or
3984 chain of symlinks) that ends with a chardev also causes the
3985 function to return true.
3986 See also "$g->stat".
3988 $flag = $g->is_chardev_opts ($path [, followsymlinks =>
3990 $followsymlinks]);
3991 This is an alias of "is_chardev".
3992 $config = $g->is_config ();
3994 This returns true iff this handle is being configured (in the
3995 "CONFIG" state).
3996 For more information on states, see guestfs(3).
3998 $dirflag = $g->is_dir ($path [, followsymlinks => $followsymlinks]);
4000 This returns "true" if and only if there is a directory with the
4001 given "path" name. Note that it returns false for other objects
4002 like files.
4003 If the optional flag "followsymlinks" is true, then a symlink (or
4005 chain of symlinks) that ends with a directory also causes the
4006 function to return true.
4007 See also "$g->stat".
4009 $dirflag = $g->is_dir_opts ($path [, followsymlinks =>
4011 $followsymlinks]);
4012 This is an alias of "is_dir".
4013 $flag = $g->is_fifo ($path [, followsymlinks => $followsymlinks]);
4015 This returns "true" if and only if there is a FIFO (named pipe)
4016 with the given "path" name.
4017 If the optional flag "followsymlinks" is true, then a symlink (or
4019 chain of symlinks) that ends with a FIFO also causes the function
4020 to return true.
4021 See also "$g->stat".
4023 $flag = $g->is_fifo_opts ($path [, followsymlinks => $followsymlinks]);
4025 This is an alias of "is_fifo".
4026 $fileflag = $g->is_file ($path [, followsymlinks => $followsymlinks]);
4028 This returns "true" if and only if there is a regular file with the
4029 given "path" name. Note that it returns false for other objects
4030 like directories.
4031 If the optional flag "followsymlinks" is true, then a symlink (or
4033 chain of symlinks) that ends with a file also causes the function
4034 to return true.
4035 See also "$g->stat".
4037 $fileflag = $g->is_file_opts ($path [, followsymlinks =>
4039 $followsymlinks]);
4040 This is an alias of "is_file".
4041 $launching = $g->is_launching ();
4043 This returns true iff this handle is launching the subprocess (in
4044 the "LAUNCHING" state).
4045 For more information on states, see guestfs(3).
4047 $lvflag = $g->is_lv ($mountable);
4049 This command tests whether "mountable" is a logical volume, and
4050 returns true iff this is the case.
4051 $ready = $g->is_ready ();
4053 This returns true iff this handle is ready to accept commands (in
4054 the "READY" state).
4055 For more information on states, see guestfs(3).
4057 $flag = $g->is_socket ($path [, followsymlinks => $followsymlinks]);
4059 This returns "true" if and only if there is a Unix domain socket
4060 with the given "path" name.
4061 If the optional flag "followsymlinks" is true, then a symlink (or
4063 chain of symlinks) that ends with a socket also causes the function
4064 to return true.
4065 See also "$g->stat".
4067 $flag = $g->is_socket_opts ($path [, followsymlinks =>
4069 $followsymlinks]);
4070 This is an alias of "is_socket".
4071 $flag = $g->is_symlink ($path);
4073 This returns "true" if and only if there is a symbolic link with
4074 the given "path" name.
4075 See also "$g->stat".
4077 $flag = $g->is_whole_device ($device);
4079 This returns "true" if and only if "device" refers to a whole block
4080 device. That is, not a partition or a logical device.
4081 $zeroflag = $g->is_zero ($path);
4083 This returns true iff the file exists and the file is empty or it
4084 contains all zero bytes.
4085 $zeroflag = $g->is_zero_device ($device);
4087 This returns true iff the device exists and contains all zero
4088 bytes.
4089 Note that for large devices this can take a long time to run.
4091 %isodata = $g->isoinfo ($isofile);
4093 This is the same as "$g->isoinfo_device" except that it works for
4094 an ISO file located inside some other mounted filesystem. Note
4095 that in the common case where you have added an ISO file as a
4096 libguestfs device, you would not call this. Instead you would call
4097 "$g->isoinfo_device".
4098 %isodata = $g->isoinfo_device ($device);
4100 "device" is an ISO device. This returns a struct of information
4101 read from the primary volume descriptor (the ISO equivalent of the
4102 superblock) of the device.
4103 Usually it is more efficient to use the isoinfo(1) command with the
4105 -d option on the host to analyze ISO files, instead of going
4106 through libguestfs.
4107 For information on the primary volume descriptor fields, see
4109 <https://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor>
4110 $g->journal_close ();
4112 Close the journal handle.
4113 This function depends on the feature "journal". See also
4115 "$g->feature-available".
4116 @fields = $g->journal_get ();
4118 Read the current journal entry. This returns all the fields in the
4119 journal as a set of "(attrname, attrval)" pairs. The "attrname" is
4120 the field name (a string).
4121 The "attrval" is the field value (a binary blob, often but not
4123 always a string). Please note that "attrval" is a byte array, not
4124 a \0-terminated C string.
4125 The length of data may be truncated to the data threshold (see:
4127 "$g->journal_set_data_threshold",
4128 "$g->journal_get_data_threshold").
4129 If you set the data threshold to unlimited (0) then this call can
4131 read a journal entry of any size, ie. it is not limited by the
4132 libguestfs protocol.
4133 This function depends on the feature "journal". See also
4135 "$g->feature-available".
4136 $threshold = $g->journal_get_data_threshold ();
4138 Get the current data threshold for reading journal entries. This
4139 is a hint to the journal that it may truncate data fields to this
4140 size when reading them (note also that it may not truncate them).
4141 If this returns 0, then the threshold is unlimited.
4142 See also "$g->journal_set_data_threshold".
4144 This function depends on the feature "journal". See also
4146 "$g->feature-available".
4147 $usec = $g->journal_get_realtime_usec ();
4149 Get the realtime (wallclock) timestamp of the current journal
4150 entry.
4151 This function depends on the feature "journal". See also
4153 "$g->feature-available".
4154 $more = $g->journal_next ();
4156 Move to the next journal entry. You have to call this at least
4157 once after opening the handle before you are able to read data.
4158 The returned boolean tells you if there are any more journal
4160 records to read. "true" means you can read the next record (eg.
4161 using "$g->journal_get"), and "false" means you have reached the
4162 end of the journal.
4163 This function depends on the feature "journal". See also
4165 "$g->feature-available".
4166 $g->journal_open ($directory);
4168 Open the systemd journal located in directory. Any previously
4169 opened journal handle is closed.
4170 The contents of the journal can be read using "$g->journal_next"
4172 and "$g->journal_get".
4173 After you have finished using the journal, you should close the
4175 handle by calling "$g->journal_close".
4176 This function depends on the feature "journal". See also
4178 "$g->feature-available".
4179 $g->journal_set_data_threshold ($threshold);
4181 Set the data threshold for reading journal entries. This is a hint
4182 to the journal that it may truncate data fields to this size when
4183 reading them (note also that it may not truncate them). If you set
4184 this to 0, then the threshold is unlimited.
4185 See also "$g->journal_get_data_threshold".
4187 This function depends on the feature "journal". See also
4189 "$g->feature-available".
4190 $rskip = $g->journal_skip ($skip);
4192 Skip forwards ("skip ≥ 0") or backwards ("skip < 0") in the
4193 journal.
4194 The number of entries actually skipped is returned (note
4196 "rskip ≥ 0"). If this is not the same as the absolute value of the
4197 skip parameter ("|skip|") you passed in then it means you have
4198 reached the end or the start of the journal.
4199 This function depends on the feature "journal". See also
4201 "$g->feature-available".
4202 $g->kill_subprocess ();
4204 This kills the hypervisor.
4205 Do not call this. See: "$g->shutdown" instead.
4207 This function is deprecated. In new code, use the "shutdown" call
4209 instead.
4210 Deprecated functions will not be removed from the API, but the fact
4212 that they are deprecated indicates that there are problems with
4213 correct use of these functions.
4214 $g->launch ();
4216 You should call this after configuring the handle (eg. adding
4217 drives) but before performing any actions.
4218 Do not call "$g->launch" twice on the same handle. Although it
4220 will not give an error (for historical reasons), the precise
4221 behaviour when you do this is not well defined. Handles are very
4222 cheap to create, so create a new one for each launch.
4223 $g->lchown ($owner, $group, $path);
4225 Change the file owner to "owner" and group to "group". This is
4226 like "$g->chown" but if "path" is a symlink then the link itself is
4227 changed, not the target.
4228 Only numeric uid and gid are supported. If you want to use names,
4230 you will need to locate and parse the password file yourself
4231 (Augeas support makes this relatively easy).
4232 $g->ldmtool_create_all ();
4234 This function scans all block devices looking for Windows dynamic
4235 disk volumes and partitions, and creates devices for any that were
4236 found.
4237 Call "$g->list_ldm_volumes" and "$g->list_ldm_partitions" to return
4239 all devices.
4240 Note that you don't normally need to call this explicitly, since it
4242 is done automatically at "$g->launch" time.
4243 This function depends on the feature "ldm". See also
4245 "$g->feature-available".
4246 @disks = $g->ldmtool_diskgroup_disks ($diskgroup);
4248 Return the disks in a Windows dynamic disk group. The "diskgroup"
4249 parameter should be the GUID of a disk group, one element from the
4250 list returned by "$g->ldmtool_scan".
4251 This function depends on the feature "ldm". See also
4253 "$g->feature-available".
4254 $name = $g->ldmtool_diskgroup_name ($diskgroup);
4256 Return the name of a Windows dynamic disk group. The "diskgroup"
4257 parameter should be the GUID of a disk group, one element from the
4258 list returned by "$g->ldmtool_scan".
4259 This function depends on the feature "ldm". See also
4261 "$g->feature-available".
4262 @volumes = $g->ldmtool_diskgroup_volumes ($diskgroup);
4264 Return the volumes in a Windows dynamic disk group. The
4265 "diskgroup" parameter should be the GUID of a disk group, one
4266 element from the list returned by "$g->ldmtool_scan".
4267 This function depends on the feature "ldm". See also
4269 "$g->feature-available".
4270 $g->ldmtool_remove_all ();
4272 This is essentially the opposite of "$g->ldmtool_create_all". It
4273 removes the device mapper mappings for all Windows dynamic disk
4274 volumes
4275 This function depends on the feature "ldm". See also
4277 "$g->feature-available".
4278 @guids = $g->ldmtool_scan ();
4280 This function scans for Windows dynamic disks. It returns a list
4281 of identifiers (GUIDs) for all disk groups that were found. These
4282 identifiers can be passed to other "$g->ldmtool_*" functions.
4283 This function scans all block devices. To scan a subset of block
4285 devices, call "$g->ldmtool_scan_devices" instead.
4286 This function depends on the feature "ldm". See also
4288 "$g->feature-available".
4289 @guids = $g->ldmtool_scan_devices (\@devices);
4291 This function scans for Windows dynamic disks. It returns a list
4292 of identifiers (GUIDs) for all disk groups that were found. These
4293 identifiers can be passed to other "$g->ldmtool_*" functions.
4294 The parameter "devices" is a list of block devices which are
4296 scanned. If this list is empty, all block devices are scanned.
4297 This function depends on the feature "ldm". See also
4299 "$g->feature-available".
4300 $hint = $g->ldmtool_volume_hint ($diskgroup, $volume);
4302 Return the hint field of the volume named "volume" in the disk
4303 group with GUID "diskgroup". This may not be defined, in which
4304 case the empty string is returned. The hint field is often, though
4305 not always, the name of a Windows drive, eg. "E:".
4306 This function depends on the feature "ldm". See also
4308 "$g->feature-available".
4309 @partitions = $g->ldmtool_volume_partitions ($diskgroup, $volume);
4311 Return the list of partitions in the volume named "volume" in the
4312 disk group with GUID "diskgroup".
4313 This function depends on the feature "ldm". See also
4315 "$g->feature-available".
4316 $voltype = $g->ldmtool_volume_type ($diskgroup, $volume);
4318 Return the type of the volume named "volume" in the disk group with
4319 GUID "diskgroup".
4320 Possible volume types that can be returned here include: "simple",
4322 "spanned", "striped", "mirrored", "raid5". Other types may also be
4323 returned.
4324 This function depends on the feature "ldm". See also
4326 "$g->feature-available".
4327 $xattr = $g->lgetxattr ($path, $name);
4329 Get a single extended attribute from file "path" named "name". If
4330 "path" is a symlink, then this call returns an extended attribute
4331 from the symlink.
4332 Normally it is better to get all extended attributes from a file in
4334 one go by calling "$g->getxattrs". However some Linux filesystem
4335 implementations are buggy and do not provide a way to list out
4336 attributes. For these filesystems (notably ntfs-3g) you have to
4337 know the names of the extended attributes you want in advance and
4338 call this function.
4339 Extended attribute values are blobs of binary data. If there is no
4341 extended attribute named "name", this returns an error.
4342 See also: "$g->lgetxattrs", "$g->getxattr", attr(5).
4344 This function depends on the feature "linuxxattrs". See also
4346 "$g->feature-available".
4347 @xattrs = $g->lgetxattrs ($path);
4349 This is the same as "$g->getxattrs", but if "path" is a symbolic
4350 link, then it returns the extended attributes of the link itself.
4351 This function depends on the feature "linuxxattrs". See also
4353 "$g->feature-available".
4354 @mounttags = $g->list_9p ();
4356 This call does nothing and returns an error.
4357 This function is deprecated. There is no replacement. Consult the
4359 API documentation in guestfs(3) for further information.
4360 Deprecated functions will not be removed from the API, but the fact
4362 that they are deprecated indicates that there are problems with
4363 correct use of these functions.
4364 @devices = $g->list_devices ();
4366 List all the block devices.
4367 The full block device names are returned, eg. /dev/sda.
4369 See also "$g->list_filesystems".
4371 %labels = $g->list_disk_labels ();
4373 If you add drives using the optional "label" parameter of
4374 "$g->add_drive_opts", you can use this call to map between disk
4375 labels, and raw block device and partition names (like /dev/sda and
4376 /dev/sda1).
4377 This returns a hashtable, where keys are the disk labels (without
4379 the /dev/disk/guestfs prefix), and the values are the full raw
4380 block device and partition names (eg. /dev/sda and /dev/sda1).
4381 @devices = $g->list_dm_devices ();
4383 List all device mapper devices.
4384 The returned list contains /dev/mapper/* devices, eg. ones created
4386 by a previous call to "$g->luks_open".
4387 Device mapper devices which correspond to logical volumes are not
4389 returned in this list. Call "$g->lvs" if you want to list logical
4390 volumes.
4391 %fses = $g->list_filesystems ();
4393 This inspection command looks for filesystems on partitions, block
4394 devices and logical volumes, returning a list of "mountables"
4395 containing filesystems and their type.
4396 The return value is a hash, where the keys are the devices
4398 containing filesystems, and the values are the filesystem types.
4399 For example:
4400 "/dev/sda1" => "ntfs"
4402 "/dev/sda2" => "ext2"
4403 "/dev/vg_guest/lv_root" => "ext4"
4404 "/dev/vg_guest/lv_swap" => "swap"
4405 The key is not necessarily a block device. It may also be an opaque
4407 ‘mountable’ string which can be passed to "$g->mount".
4408 The value can have the special value "unknown", meaning the content
4410 of the device is undetermined or empty. "swap" means a Linux swap
4411 partition.
4412 In libguestfs ≤ 1.36 this command ran other libguestfs commands,
4414 which might have included "$g->mount" and "$g->umount", and
4415 therefore you had to use this soon after launch and only when
4416 nothing else was mounted. This restriction is removed in
4417 libguestfs ≥ 1.38.
4418 Not all of the filesystems returned will be mountable. In
4420 particular, swap partitions are returned in the list. Also this
4421 command does not check that each filesystem found is valid and
4422 mountable, and some filesystems might be mountable but require
4423 special options. Filesystems may not all belong to a single
4424 logical operating system (use "$g->inspect_os" to look for OSes).
4425 @devices = $g->list_ldm_partitions ();
4427 This function returns all Windows dynamic disk partitions that were
4428 found at launch time. It returns a list of device names.
4429 This function depends on the feature "ldm". See also
4431 "$g->feature-available".
4432 @devices = $g->list_ldm_volumes ();
4434 This function returns all Windows dynamic disk volumes that were
4435 found at launch time. It returns a list of device names.
4436 This function depends on the feature "ldm". See also
4438 "$g->feature-available".
4439 @devices = $g->list_md_devices ();
4441 List all Linux md devices.
4442 @partitions = $g->list_partitions ();
4444 List all the partitions detected on all block devices.
4445 The full partition device names are returned, eg. /dev/sda1
4447 This does not return logical volumes. For that you will need to
4449 call "$g->lvs".
4450 See also "$g->list_filesystems".
4452 $listing = $g->ll ($directory);
4454 List the files in directory (relative to the root directory, there
4455 is no cwd) in the format of "ls -la".
4456 This command is mostly useful for interactive sessions. It is not
4458 intended that you try to parse the output string.
4459 $listing = $g->llz ($directory);
4461 List the files in directory in the format of "ls -laZ".
4462 This command is mostly useful for interactive sessions. It is not
4464 intended that you try to parse the output string.
4465 This function is deprecated. In new code, use the "lgetxattrs"
4467 call 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 $g->ln ($target, $linkname);
4474 This command creates a hard link.
4475 $g->ln_f ($target, $linkname);
4477 This command creates a hard link, removing the link "linkname" if
4478 it exists already.
4479 $g->ln_s ($target, $linkname);
4481 This command creates a symbolic link using the "ln -s" command.
4482 $g->ln_sf ($target, $linkname);
4484 This command creates a symbolic link using the "ln -sf" command,
4485 The -f option removes the link ("linkname") if it exists already.
4486 $g->lremovexattr ($xattr, $path);
4488 This is the same as "$g->removexattr", but if "path" is a symbolic
4489 link, then it removes an extended attribute of the link itself.
4490 This function depends on the feature "linuxxattrs". See also
4492 "$g->feature-available".
4493 @listing = $g->ls ($directory);
4495 List the files in directory (relative to the root directory, there
4496 is no cwd). The "." and ".." entries are not returned, but hidden
4497 files are shown.
4498 $g->ls0 ($dir, $filenames);
4500 This specialized command is used to get a listing of the filenames
4501 in the directory "dir". The list of filenames is written to the
4502 local file filenames (on the host).
4503 In the output file, the filenames are separated by "\0" characters.
4505 "." and ".." are not returned. The filenames are not sorted.
4507 $g->lsetxattr ($xattr, $val, $vallen, $path);
4509 This is the same as "$g->setxattr", but if "path" is a symbolic
4510 link, then it sets an extended attribute of the link itself.
4511 This function depends on the feature "linuxxattrs". See also
4513 "$g->feature-available".
4514 %statbuf = $g->lstat ($path);
4516 Returns file information for the given "path".
4517 This is the same as "$g->stat" except that if "path" is a symbolic
4519 link, then the link is stat-ed, not the file it refers to.
4520 This is the same as the lstat(2) system call.
4522 This function is deprecated. In new code, use the "lstatns" call
4524 instead.
4525 Deprecated functions will not be removed from the API, but the fact
4527 that they are deprecated indicates that there are problems with
4528 correct use of these functions.
4529 @statbufs = $g->lstatlist ($path, \@names);
4531 This call allows you to perform the "$g->lstat" operation on
4532 multiple files, where all files are in the directory "path".
4533 "names" is the list of files from this directory.
4534 On return you get a list of stat structs, with a one-to-one
4536 correspondence to the "names" list. If any name did not exist or
4537 could not be lstat'd, then the "st_ino" field of that structure is
4538 set to -1.
4539 This call is intended for programs that want to efficiently list a
4541 directory contents without making many round-trips. See also
4542 "$g->lxattrlist" for a similarly efficient call for getting
4543 extended attributes.
4544 This function is deprecated. In new code, use the "lstatnslist"
4546 call instead.
4547 Deprecated functions will not be removed from the API, but the fact
4549 that they are deprecated indicates that there are problems with
4550 correct use of these functions.
4551 %statbuf = $g->lstatns ($path);
4553 Returns file information for the given "path".
4554 This is the same as "$g->statns" except that if "path" is a
4556 symbolic link, then the link is stat-ed, not the file it refers to.
4557 This is the same as the lstat(2) system call.
4559 @statbufs = $g->lstatnslist ($path, \@names);
4561 This call allows you to perform the "$g->lstatns" operation on
4562 multiple files, where all files are in the directory "path".
4563 "names" is the list of files from this directory.
4564 On return you get a list of stat structs, with a one-to-one
4566 correspondence to the "names" list. If any name did not exist or
4567 could not be lstat'd, then the "st_ino" field of that structure is
4568 set to -1.
4569 This call is intended for programs that want to efficiently list a
4571 directory contents without making many round-trips. See also
4572 "$g->lxattrlist" for a similarly efficient call for getting
4573 extended attributes.
4574 $g->luks_add_key ($device, $key, $newkey, $keyslot);
4576 This command adds a new key on LUKS device "device". "key" is any
4577 existing key, and is used to access the device. "newkey" is the
4578 new key to add. "keyslot" is the key slot that will be replaced.
4579 Note that if "keyslot" already contains a key, then this command
4581 will fail. You have to use "$g->luks_kill_slot" first to remove
4582 that key.
4583 This function depends on the feature "luks". See also
4585 "$g->feature-available".
4586 $g->luks_close ($device);
4588 This closes a LUKS device that was created earlier by
4589 "$g->luks_open" or "$g->luks_open_ro". The "device" parameter must
4590 be the name of the LUKS mapping device (ie. /dev/mapper/mapname)
4591 and not the name of the underlying block device.
4592 This function depends on the feature "luks". See also
4594 "$g->feature-available".
4595 This function is deprecated. In new code, use the
4597 "cryptsetup_close" call instead.
4598 Deprecated functions will not be removed from the API, but the fact
4600 that they are deprecated indicates that there are problems with
4601 correct use of these functions.
4602 $g->luks_format ($device, $key, $keyslot);
4604 This command erases existing data on "device" and formats the
4605 device as a LUKS encrypted device. "key" is the initial key, which
4606 is added to key slot "keyslot". (LUKS supports 8 key slots,
4607 numbered 0-7).
4608 This function depends on the feature "luks". See also
4610 "$g->feature-available".
4611 $g->luks_format_cipher ($device, $key, $keyslot, $cipher);
4613 This command is the same as "$g->luks_format" but it also allows
4614 you to set the "cipher" used.
4615 This function depends on the feature "luks". See also
4617 "$g->feature-available".
4618 $g->luks_kill_slot ($device, $key, $keyslot);
4620 This command deletes the key in key slot "keyslot" from the
4621 encrypted LUKS device "device". "key" must be one of the other
4622 keys.
4623 This function depends on the feature "luks". See also
4625 "$g->feature-available".
4626 $g->luks_open ($device, $key, $mapname);
4628 This command opens a block device which has been encrypted
4629 according to the Linux Unified Key Setup (LUKS) standard.
4630 "device" is the encrypted block device or partition.
4632 The caller must supply one of the keys associated with the LUKS
4634 block device, in the "key" parameter.
4635 This creates a new block device called /dev/mapper/mapname. Reads
4637 and writes to this block device are decrypted from and encrypted to
4638 the underlying "device" respectively.
4639 If this block device contains LVM volume groups, then calling
4641 "$g->lvm_scan" with the "activate" parameter "true" will make them
4642 visible.
4643 Use "$g->list_dm_devices" to list all device mapper devices.
4645 This function depends on the feature "luks". See also
4647 "$g->feature-available".
4648 This function is deprecated. In new code, use the
4650 "cryptsetup_open" call instead.
4651 Deprecated functions will not be removed from the API, but the fact
4653 that they are deprecated indicates that there are problems with
4654 correct use of these functions.
4655 $g->luks_open_ro ($device, $key, $mapname);
4657 This is the same as "$g->luks_open" except that a read-only mapping
4658 is created.
4659 This function depends on the feature "luks". See also
4661 "$g->feature-available".
4662 This function is deprecated. In new code, use the
4664 "cryptsetup_open" call instead.
4665 Deprecated functions will not be removed from the API, but the fact
4667 that they are deprecated indicates that there are problems with
4668 correct use of these functions.
4669 $uuid = $g->luks_uuid ($device);
4671 This returns the UUID of the LUKS device "device".
4672 This function depends on the feature "luks". See also
4674 "$g->feature-available".
4675 $g->lvcreate ($logvol, $volgroup, $mbytes);
4677 This creates an LVM logical volume called "logvol" on the volume
4678 group "volgroup", with "size" megabytes.
4679 This function depends on the feature "lvm2". See also
4681 "$g->feature-available".
4682 $g->lvcreate_free ($logvol, $volgroup, $percent);
4684 Create an LVM logical volume called /dev/volgroup/logvol, using
4685 approximately "percent" % of the free space remaining in the volume
4686 group. Most usefully, when "percent" is 100 this will create the
4687 largest possible LV.
4688 This function depends on the feature "lvm2". See also
4690 "$g->feature-available".
4691 $lv = $g->lvm_canonical_lv_name ($lvname);
4693 This converts alternative naming schemes for LVs that you might
4694 find to the canonical name. For example, /dev/mapper/VG-LV is
4695 converted to /dev/VG/LV.
4696 This command returns an error if the "lvname" parameter does not
4698 refer to a logical volume. In this case errno will be set to
4699 "EINVAL".
4700 See also "$g->is_lv", "$g->canonical_device_name".
4702 $g->lvm_clear_filter ();
4704 This undoes the effect of "$g->lvm_set_filter". LVM will be able
4705 to see every block device.
4706 This command also clears the LVM cache and performs a volume group
4708 scan.
4709 $g->lvm_remove_all ();
4711 This command removes all LVM logical volumes, volume groups and
4712 physical volumes.
4713 This function depends on the feature "lvm2". See also
4715 "$g->feature-available".
4716 $g->lvm_scan ($activate);
4718 This scans all block devices and rebuilds the list of LVM physical
4719 volumes, volume groups and logical volumes.
4720 If the "activate" parameter is "true" then newly found volume
4722 groups and logical volumes are activated, meaning the LV /dev/VG/LV
4723 devices become visible.
4724 When a libguestfs handle is launched it scans for existing devices,
4726 so you do not normally need to use this API. However it is useful
4727 when you have added a new device or deleted an existing device
4728 (such as when the "$g->luks_open" API is used).
4729 $g->lvm_set_filter (\@devices);
4731 This sets the LVM device filter so that LVM will only be able to
4732 "see" the block devices in the list "devices", and will ignore all
4733 other attached block devices.
4734 Where disk image(s) contain duplicate PVs or VGs, this command is
4736 useful to get LVM to ignore the duplicates, otherwise LVM can get
4737 confused. Note also there are two types of duplication possible:
4738 either cloned PVs/VGs which have identical UUIDs; or VGs that are
4739 not cloned but just happen to have the same name. In normal
4740 operation you cannot create this situation, but you can do it
4741 outside LVM, eg. by cloning disk images or by bit twiddling inside
4742 the LVM metadata.
4743 This command also clears the LVM cache and performs a volume group
4745 scan.
4746 You can filter whole block devices or individual partitions.
4748 You cannot use this if any VG is currently in use (eg. contains a
4750 mounted filesystem), even if you are not filtering out that VG.
4751 This function depends on the feature "lvm2". See also
4753 "$g->feature-available".
4754 $g->lvremove ($device);
4756 Remove an LVM logical volume "device", where "device" is the path
4757 to the LV, such as /dev/VG/LV.
4758 You can also remove all LVs in a volume group by specifying the VG
4760 name, /dev/VG.
4761 This function depends on the feature "lvm2". See also
4763 "$g->feature-available".
4764 $g->lvrename ($logvol, $newlogvol);
4766 Rename a logical volume "logvol" with the new name "newlogvol".
4767 $g->lvresize ($device, $mbytes);
4769 This resizes (expands or shrinks) an existing LVM logical volume to
4770 "mbytes". When reducing, data in the reduced part is lost.
4771 This function depends on the feature "lvm2". See also
4773 "$g->feature-available".
4774 $g->lvresize_free ($lv, $percent);
4776 This expands an existing logical volume "lv" so that it fills "pc"
4777 % of the remaining free space in the volume group. Commonly you
4778 would call this with pc = 100 which expands the logical volume as
4779 much as possible, using all remaining free space in the volume
4780 group.
4781 This function depends on the feature "lvm2". See also
4783 "$g->feature-available".
4784 @logvols = $g->lvs ();
4786 List all the logical volumes detected. This is the equivalent of
4787 the lvs(8) command.
4788 This returns a list of the logical volume device names (eg.
4790 /dev/VolGroup00/LogVol00).
4791 See also "$g->lvs_full", "$g->list_filesystems".
4793 This function depends on the feature "lvm2". See also
4795 "$g->feature-available".
4796 @logvols = $g->lvs_full ();
4798 List all the logical volumes detected. This is the equivalent of
4799 the lvs(8) command. The "full" version includes all fields.
4800 This function depends on the feature "lvm2". See also
4802 "$g->feature-available".
4803 $uuid = $g->lvuuid ($device);
4805 This command returns the UUID of the LVM LV "device".
4806 @xattrs = $g->lxattrlist ($path, \@names);
4808 This call allows you to get the extended attributes of multiple
4809 files, where all files are in the directory "path". "names" is the
4810 list of files from this directory.
4811 On return you get a flat list of xattr structs which must be
4813 interpreted sequentially. The first xattr struct always has a
4814 zero-length "attrname". "attrval" in this struct is zero-length to
4815 indicate there was an error doing "$g->lgetxattr" for this file, or
4816 is a C string which is a decimal number (the number of following
4817 attributes for this file, which could be "0"). Then after the
4818 first xattr struct are the zero or more attributes for the first
4819 named file. This repeats for the second and subsequent files.
4820 This call is intended for programs that want to efficiently list a
4822 directory contents without making many round-trips. See also
4823 "$g->lstatlist" for a similarly efficient call for getting standard
4824 stats.
4825 This function depends on the feature "linuxxattrs". See also
4827 "$g->feature-available".
4828 $disks = $g->max_disks ();
4830 Return the maximum number of disks that may be added to a handle
4831 (eg. by "$g->add_drive_opts" and similar calls).
4832 This function was added in libguestfs 1.19.7. In previous versions
4834 of libguestfs the limit was 25.
4835 See "MAXIMUM NUMBER OF DISKS" in guestfs(3) for additional
4837 information on this topic.
4838 $g->md_create ($name, \@devices [, missingbitmap => $missingbitmap] [,
4840 nrdevices => $nrdevices] [, spare => $spare] [, chunk => $chunk] [,
4841 level => $level]);
4842 Create a Linux md (RAID) device named "name" on the devices in the
4843 list "devices".
4844 The optional parameters are:
4846 "missingbitmap"
4848 A bitmap of missing devices. If a bit is set it means that a
4849 missing device is added to the array. The least significant
4850 bit corresponds to the first device in the array.
4851 As examples:
4853 If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
4855 resulting array would be "[<missing>, "/dev/sda"]".
4856 If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
4858 resulting array would be "["/dev/sda", <missing>]".
4859 This defaults to 0 (no missing devices).
4861 The length of "devices" + the number of bits set in
4863 "missingbitmap" must equal "nrdevices" + "spare".
4864 "nrdevices"
4866 The number of active RAID devices.
4867 If not set, this defaults to the length of "devices" plus the
4869 number of bits set in "missingbitmap".
4870 "spare"
4872 The number of spare devices.
4873 If not set, this defaults to 0.
4875 "chunk"
4877 The chunk size in bytes.
4878 The "chunk" parameter does not make sense, and should not be
4880 specified, when "level" is "raid1" (which is the default; see
4881 below).
4882 "level"
4884 The RAID level, which can be one of: "linear", "raid0", 0,
4885 "stripe", "raid1", 1, "mirror", "raid4", 4, "raid5", 5,
4886 "raid6", 6, "raid10", 10. Some of these are synonymous, and
4887 more levels may be added in future.
4888 If not set, this defaults to "raid1".
4890 This function depends on the feature "mdadm". See also
4892 "$g->feature-available".
4893 %info = $g->md_detail ($md);
4895 This command exposes the output of "mdadm -DY <md>". The following
4896 fields are usually present in the returned hash. Other fields may
4897 also be present.
4898 "level"
4900 The raid level of the MD device.
4901 "devices"
4903 The number of underlying devices in the MD device.
4904 "metadata"
4906 The metadata version used.
4907 "uuid"
4909 The UUID of the MD device.
4910 "name"
4912 The name of the MD device.
4913 This function depends on the feature "mdadm". See also
4915 "$g->feature-available".
4916 @devices = $g->md_stat ($md);
4918 This call returns a list of the underlying devices which make up
4919 the single software RAID array device "md".
4920 To get a list of software RAID devices, call "$g->list_md_devices".
4922 Each structure returned corresponds to one device along with
4924 additional status information:
4925 "mdstat_device"
4927 The name of the underlying device.
4928 "mdstat_index"
4930 The index of this device within the array.
4931 "mdstat_flags"
4933 Flags associated with this device. This is a string containing
4934 (in no specific order) zero or more of the following flags:
4935 "W" write-mostly
4937 "F" device is faulty
4939 "S" device is a RAID spare
4941 "R" replacement
4943 This function depends on the feature "mdadm". See also
4945 "$g->feature-available".
4946 $g->md_stop ($md);
4948 This command deactivates the MD array named "md". The device is
4949 stopped, but it is not destroyed or zeroed.
4950 This function depends on the feature "mdadm". See also
4952 "$g->feature-available".
4953 $g->mkdir ($path);
4955 Create a directory named "path".
4956 $g->mkdir_mode ($path, $mode);
4958 This command creates a directory, setting the initial permissions
4959 of the directory to "mode".
4960 For common Linux filesystems, the actual mode which is set will be
4962 "mode & ~umask & 01777". Non-native-Linux filesystems may
4963 interpret the mode in other ways.
4964 See also "$g->mkdir", "$g->umask"
4966 $g->mkdir_p ($path);
4968 Create a directory named "path", creating any parent directories as
4969 necessary. This is like the "mkdir -p" shell command.
4970 $dir = $g->mkdtemp ($tmpl);
4972 This command creates a temporary directory. The "tmpl" parameter
4973 should be a full pathname for the temporary directory name with the
4974 final six characters being "XXXXXX".
4975 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the
4977 second one being suitable for Windows filesystems.
4978 The name of the temporary directory that was created is returned.
4980 The temporary directory is created with mode 0700 and is owned by
4982 root.
4983 The caller is responsible for deleting the temporary directory and
4985 its contents after use.
4986 See also: mkdtemp(3)
4988 $g->mke2fs ($device [, blockscount => $blockscount] [, blocksize =>
4990 $blocksize] [, fragsize => $fragsize] [, blockspergroup =>
4991 $blockspergroup] [, numberofgroups => $numberofgroups] [, bytesperinode
4992 => $bytesperinode] [, inodesize => $inodesize] [, journalsize =>
4993 $journalsize] [, numberofinodes => $numberofinodes] [, stridesize =>
4994 $stridesize] [, stripewidth => $stripewidth] [, maxonlineresize =>
4995 $maxonlineresize] [, reservedblockspercentage =>
4996 $reservedblockspercentage] [, mmpupdateinterval => $mmpupdateinterval]
4997 [, journaldevice => $journaldevice] [, label => $label] [,
4998 lastmounteddir => $lastmounteddir] [, creatoros => $creatoros] [,
4999 fstype => $fstype] [, usagetype => $usagetype] [, uuid => $uuid] [,
5000 forcecreate => $forcecreate] [, writesbandgrouponly =>
5001 $writesbandgrouponly] [, lazyitableinit => $lazyitableinit] [,
5002 lazyjournalinit => $lazyjournalinit] [, testfs => $testfs] [, discard
5003 => $discard] [, quotatype => $quotatype] [, extent => $extent] [,
5004 filetype => $filetype] [, flexbg => $flexbg] [, hasjournal =>
5005 $hasjournal] [, journaldev => $journaldev] [, largefile => $largefile]
5006 [, quota => $quota] [, resizeinode => $resizeinode] [, sparsesuper =>
5007 $sparsesuper] [, uninitbg => $uninitbg]);
5008 "mke2fs" is used to create an ext2, ext3, or ext4 filesystem on
5009 "device".
5010 The optional "blockscount" is the size of the filesystem in blocks.
5012 If omitted it defaults to the size of "device". Note if the
5013 filesystem is too small to contain a journal, "mke2fs" will
5014 silently create an ext2 filesystem instead.
5015 $g->mke2fs_J ($fstype, $blocksize, $device, $journal);
5017 This creates an ext2/3/4 filesystem on "device" with an external
5018 journal on "journal". It is equivalent to the command:
5019 mke2fs -t fstype -b blocksize -J device=<journal> <device>
5021 See also "$g->mke2journal".
5023 This function is deprecated. In new code, use the "mke2fs" call
5025 instead.
5026 Deprecated functions will not be removed from the API, but the fact
5028 that they are deprecated indicates that there are problems with
5029 correct use of these functions.
5030 $g->mke2fs_JL ($fstype, $blocksize, $device, $label);
5032 This creates an ext2/3/4 filesystem on "device" with an external
5033 journal on the journal labeled "label".
5034 See also "$g->mke2journal_L".
5036 This function is deprecated. In new code, use the "mke2fs" call
5038 instead.
5039 Deprecated functions will not be removed from the API, but the fact
5041 that they are deprecated indicates that there are problems with
5042 correct use of these functions.
5043 $g->mke2fs_JU ($fstype, $blocksize, $device, $uuid);
5045 This creates an ext2/3/4 filesystem on "device" with an external
5046 journal on the journal with UUID "uuid".
5047 See also "$g->mke2journal_U".
5049 This function depends on the feature "linuxfsuuid". See also
5051 "$g->feature-available".
5052 This function is deprecated. In new code, use the "mke2fs" call
5054 instead.
5055 Deprecated functions will not be removed from the API, but the fact
5057 that they are deprecated indicates that there are problems with
5058 correct use of these functions.
5059 $g->mke2journal ($blocksize, $device);
5061 This creates an ext2 external journal on "device". It is
5062 equivalent to the command:
5063 mke2fs -O journal_dev -b blocksize device
5065 This function is deprecated. In new code, use the "mke2fs" call
5067 instead.
5068 Deprecated functions will not be removed from the API, but the fact
5070 that they are deprecated indicates that there are problems with
5071 correct use of these functions.
5072 $g->mke2journal_L ($blocksize, $label, $device);
5074 This creates an ext2 external journal on "device" with label
5075 "label".
5076 This function is deprecated. In new code, use the "mke2fs" call
5078 instead.
5079 Deprecated functions will not be removed from the API, but the fact
5081 that they are deprecated indicates that there are problems with
5082 correct use of these functions.
5083 $g->mke2journal_U ($blocksize, $uuid, $device);
5085 This creates an ext2 external journal on "device" with UUID "uuid".
5086 This function depends on the feature "linuxfsuuid". See also
5088 "$g->feature-available".
5089 This function is deprecated. In new code, use the "mke2fs" call
5091 instead.
5092 Deprecated functions will not be removed from the API, but the fact
5094 that they are deprecated indicates that there are problems with
5095 correct use of these functions.
5096 $g->mkfifo ($mode, $path);
5098 This call creates a FIFO (named pipe) called "path" with mode
5099 "mode". It is just a convenient wrapper around "$g->mknod".
5100 Unlike with "$g->mknod", "mode" must contain only permissions bits.
5102 The mode actually set is affected by the umask.
5104 This function depends on the feature "mknod". See also
5106 "$g->feature-available".
5107 $g->mkfs ($fstype, $device [, blocksize => $blocksize] [, features =>
5109 $features] [, inode => $inode] [, sectorsize => $sectorsize] [, label
5110 => $label]);
5111 This function creates a filesystem on "device". The filesystem
5112 type is "fstype", for example "ext3".
5113 The optional arguments are:
5115 "blocksize"
5117 The filesystem block size. Supported block sizes depend on the
5118 filesystem type, but typically they are 1024, 2048 or 4096 for
5119 Linux ext2/3 filesystems.
5120 For VFAT and NTFS the "blocksize" parameter is treated as the
5122 requested cluster size.
5123 For UFS block sizes, please see mkfs.ufs(8).
5125 "features"
5127 This passes the -O parameter to the external mkfs program.
5128 For certain filesystem types, this allows extra filesystem
5130 features to be selected. See mke2fs(8) and mkfs.ufs(8) for
5131 more details.
5132 You cannot use this optional parameter with the "gfs" or "gfs2"
5134 filesystem type.
5135 "inode"
5137 This passes the -I parameter to the external mke2fs(8) program
5138 which sets the inode size (only for ext2/3/4 filesystems at
5139 present).
5140 "sectorsize"
5142 This passes the -S parameter to external mkfs.ufs(8) program,
5143 which sets sector size for ufs filesystem.
5144 $g->mkfs_opts ($fstype, $device [, blocksize => $blocksize] [, features
5146 => $features] [, inode => $inode] [, sectorsize => $sectorsize] [,
5147 label => $label]);
5148 This is an alias of "mkfs".
5149 $g->mkfs_b ($fstype, $blocksize, $device);
5151 This call is similar to "$g->mkfs", but it allows you to control
5152 the block size of the resulting filesystem. Supported block sizes
5153 depend on the filesystem type, but typically they are 1024, 2048 or
5154 4096 only.
5155 For VFAT and NTFS the "blocksize" parameter is treated as the
5157 requested cluster size.
5158 This function is deprecated. In new code, use the "mkfs" call
5160 instead.
5161 Deprecated functions will not be removed from the API, but the fact
5163 that they are deprecated indicates that there are problems with
5164 correct use of these functions.
5165 $g->mkfs_btrfs (\@devices [, allocstart => $allocstart] [, bytecount =>
5167 $bytecount] [, datatype => $datatype] [, leafsize => $leafsize] [,
5168 label => $label] [, metadata => $metadata] [, nodesize => $nodesize] [,
5169 sectorsize => $sectorsize]);
5170 Create a btrfs filesystem, allowing all configurables to be set.
5171 For more information on the optional arguments, see mkfs.btrfs(8).
5172 Since btrfs filesystems can span multiple devices, this takes a
5174 non-empty list of devices.
5175 To create general filesystems, use "$g->mkfs".
5177 This function depends on the feature "btrfs". See also
5179 "$g->feature-available".
5180 $g->mklost_and_found ($mountpoint);
5182 Make the "lost+found" directory, normally in the root directory of
5183 an ext2/3/4 filesystem. "mountpoint" is the directory under which
5184 we try to create the "lost+found" directory.
5185 $g->mkmountpoint ($exemptpath);
5187 "$g->mkmountpoint" and "$g->rmmountpoint" are specialized calls
5188 that can be used to create extra mountpoints before mounting the
5189 first filesystem.
5190 These calls are only necessary in some very limited circumstances,
5192 mainly the case where you want to mount a mix of unrelated and/or
5193 read-only filesystems together.
5194 For example, live CDs often contain a "Russian doll" nest of
5196 filesystems, an ISO outer layer, with a squashfs image inside, with
5197 an ext2/3 image inside that. You can unpack this as follows in
5198 guestfish:
5199 add-ro Fedora-11-i686-Live.iso
5201 run
5202 mkmountpoint /cd
5203 mkmountpoint /sqsh
5204 mkmountpoint /ext3fs
5205 mount /dev/sda /cd
5206 mount-loop /cd/LiveOS/squashfs.img /sqsh
5207 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
5208 The inner filesystem is now unpacked under the /ext3fs mountpoint.
5210 "$g->mkmountpoint" is not compatible with "$g->umount_all". You
5212 may get unexpected errors if you try to mix these calls. It is
5213 safest to manually unmount filesystems and remove mountpoints after
5214 use.
5215 "$g->umount_all" unmounts filesystems by sorting the paths longest
5217 first, so for this to work for manual mountpoints, you must ensure
5218 that the innermost mountpoints have the longest pathnames, as in
5219 the example code above.
5220 For more details see
5222 <https://bugzilla.redhat.com/show_bug.cgi?id=599503>
5223 Autosync [see "$g->set_autosync", this is set by default on
5225 handles] can cause "$g->umount_all" to be called when the handle is
5226 closed which can also trigger these issues.
5227 $g->mknod ($mode, $devmajor, $devminor, $path);
5229 This call creates block or character special devices, or named
5230 pipes (FIFOs).
5231 The "mode" parameter should be the mode, using the standard
5233 constants. "devmajor" and "devminor" are the device major and
5234 minor numbers, only used when creating block and character special
5235 devices.
5236 Note that, just like mknod(2), the mode must be bitwise OR'd with
5238 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just
5239 creates a regular file). These constants are available in the
5240 standard Linux header files, or you can use "$g->mknod_b",
5241 "$g->mknod_c" or "$g->mkfifo" which are wrappers around this
5242 command which bitwise OR in the appropriate constant for you.
5243 The mode actually set is affected by the umask.
5245 This function depends on the feature "mknod". See also
5247 "$g->feature-available".
5248 $g->mknod_b ($mode, $devmajor, $devminor, $path);
5250 This call creates a block device node called "path" with mode
5251 "mode" and device major/minor "devmajor" and "devminor". It is
5252 just a convenient wrapper around "$g->mknod".
5253 Unlike with "$g->mknod", "mode" must contain only permissions bits.
5255 The mode actually set is affected by the umask.
5257 This function depends on the feature "mknod". See also
5259 "$g->feature-available".
5260 $g->mknod_c ($mode, $devmajor, $devminor, $path);
5262 This call creates a char device node called "path" with mode "mode"
5263 and device major/minor "devmajor" and "devminor". It is just a
5264 convenient wrapper around "$g->mknod".
5265 Unlike with "$g->mknod", "mode" must contain only permissions bits.
5267 The mode actually set is affected by the umask.
5269 This function depends on the feature "mknod". See also
5271 "$g->feature-available".
5272 $g->mksquashfs ($path, $filename [, compress => $compress] [, excludes
5274 => $excludes]);
5275 Create a squashfs filesystem for the specified "path".
5276 The optional "compress" flag controls compression. If not given,
5278 then the output compressed using "gzip". Otherwise one of the
5279 following strings may be given to select the compression type of
5280 the squashfs: "gzip", "lzma", "lzo", "lz4", "xz".
5281 The other optional arguments are:
5283 "excludes"
5285 A list of wildcards. Files are excluded if they match any of
5286 the wildcards.
5287 Please note that this API may fail when used to compress
5289 directories with large files, such as the resulting squashfs will
5290 be over 3GB big.
5291 This function depends on the feature "squashfs". See also
5293 "$g->feature-available".
5294 $g->mkswap ($device [, label => $label] [, uuid => $uuid]);
5296 Create a Linux swap partition on "device".
5297 The option arguments "label" and "uuid" allow you to set the label
5299 and/or UUID of the new swap partition.
5300 $g->mkswap_opts ($device [, label => $label] [, uuid => $uuid]);
5302 This is an alias of "mkswap".
5303 $g->mkswap_L ($label, $device);
5305 Create a swap partition on "device" with label "label".
5306 Note that you cannot attach a swap label to a block device (eg.
5308 /dev/sda), just to a partition. This appears to be a limitation of
5309 the kernel or swap tools.
5310 This function is deprecated. In new code, use the "mkswap" call
5312 instead.
5313 Deprecated functions will not be removed from the API, but the fact
5315 that they are deprecated indicates that there are problems with
5316 correct use of these functions.
5317 $g->mkswap_U ($uuid, $device);
5319 Create a swap partition on "device" with UUID "uuid".
5320 This function depends on the feature "linuxfsuuid". See also
5322 "$g->feature-available".
5323 This function is deprecated. In new code, use the "mkswap" call
5325 instead.
5326 Deprecated functions will not be removed from the API, but the fact
5328 that they are deprecated indicates that there are problems with
5329 correct use of these functions.
5330 $g->mkswap_file ($path);
5332 Create a swap file.
5333 This command just writes a swap file signature to an existing file.
5335 To create the file itself, use something like "$g->fallocate".
5336 $path = $g->mktemp ($tmpl [, suffix => $suffix]);
5338 This command creates a temporary file. The "tmpl" parameter should
5339 be a full pathname for the temporary directory name with the final
5340 six characters being "XXXXXX".
5341 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the
5343 second one being suitable for Windows filesystems.
5344 The name of the temporary file that was created is returned.
5346 The temporary file is created with mode 0600 and is owned by root.
5348 The caller is responsible for deleting the temporary file after
5350 use.
5351 If the optional "suffix" parameter is given, then the suffix (eg.
5353 ".txt") is appended to the temporary name.
5354 See also: "$g->mkdtemp".
5356 $g->modprobe ($modulename);
5358 This loads a kernel module in the appliance.
5359 This function depends on the feature "linuxmodules". See also
5361 "$g->feature-available".
5362 $g->mount ($mountable, $mountpoint);
5364 Mount a guest disk at a position in the filesystem. Block devices
5365 are named /dev/sda, /dev/sdb and so on, as they were added to the
5366 guest. If those block devices contain partitions, they will have
5367 the usual names (eg. /dev/sda1). Also LVM /dev/VG/LV-style names
5368 can be used, or ‘mountable’ strings returned by
5369 "$g->list_filesystems" or "$g->inspect_get_mountpoints".
5370 The rules are the same as for mount(2): A filesystem must first be
5372 mounted on / before others can be mounted. Other filesystems can
5373 only be mounted on directories which already exist.
5374 The mounted filesystem is writable, if we have sufficient
5376 permissions on the underlying device.
5377 Before libguestfs 1.13.16, this call implicitly added the options
5379 "sync" and "noatime". The "sync" option greatly slowed writes and
5380 caused many problems for users. If your program might need to work
5381 with older versions of libguestfs, use "$g->mount_options" instead
5382 (using an empty string for the first parameter if you don't want
5383 any options).
5384 $g->mount_9p ($mounttag, $mountpoint [, options => $options]);
5386 This call does nothing and returns an error.
5387 This function is deprecated. There is no replacement. Consult the
5389 API documentation in guestfs(3) for further information.
5390 Deprecated functions will not be removed from the API, but the fact
5392 that they are deprecated indicates that there are problems with
5393 correct use of these functions.
5394 $g->mount_local ($localmountpoint [, readonly => $readonly] [, options
5396 => $options] [, cachetimeout => $cachetimeout] [, debugcalls =>
5397 $debugcalls]);
5398 This call exports the libguestfs-accessible filesystem to a local
5399 mountpoint (directory) called "localmountpoint". Ordinary reads
5400 and writes to files and directories under "localmountpoint" are
5401 redirected through libguestfs.
5402 If the optional "readonly" flag is set to true, then writes to the
5404 filesystem return error "EROFS".
5405 "options" is a comma-separated list of mount options. See
5407 guestmount(1) for some useful options.
5408 "cachetimeout" sets the timeout (in seconds) for cached directory
5410 entries. The default is 60 seconds. See guestmount(1) for further
5411 information.
5412 If "debugcalls" is set to true, then additional debugging
5414 information is generated for every FUSE call.
5415 When "$g->mount_local" returns, the filesystem is ready, but is not
5417 processing requests (access to it will block). You have to call
5418 "$g->mount_local_run" to run the main loop.
5419 See "MOUNT LOCAL" in guestfs(3) for full documentation.
5421 $g->mount_local_run ();
5423 Run the main loop which translates kernel calls to libguestfs
5424 calls.
5425 This should only be called after "$g->mount_local" returns
5427 successfully. The call will not return until the filesystem is
5428 unmounted.
5429 Note you must not make concurrent libguestfs calls on the same
5431 handle from another thread.
5432 You may call this from a different thread than the one which called
5434 "$g->mount_local", subject to the usual rules for threads and
5435 libguestfs (see "MULTIPLE HANDLES AND MULTIPLE THREADS" in
5436 guestfs(3)).
5437 See "MOUNT LOCAL" in guestfs(3) for full documentation.
5439 $g->mount_loop ($file, $mountpoint);
5441 This command lets you mount file (a filesystem image in a file) on
5442 a mount point. It is entirely equivalent to the command "mount -o
5443 loop file mountpoint".
5444 $g->mount_options ($options, $mountable, $mountpoint);
5446 This is the same as the "$g->mount" command, but it allows you to
5447 set the mount options as for the mount(8) -o flag.
5448 If the "options" parameter is an empty string, then no options are
5450 passed (all options default to whatever the filesystem uses).
5451 $g->mount_ro ($mountable, $mountpoint);
5453 This is the same as the "$g->mount" command, but it mounts the
5454 filesystem with the read-only (-o ro) flag.
5455 $g->mount_vfs ($options, $vfstype, $mountable, $mountpoint);
5457 This is the same as the "$g->mount" command, but it allows you to
5458 set both the mount options and the vfstype as for the mount(8) -o
5459 and -t flags.
5460 $device = $g->mountable_device ($mountable);
5462 Returns the device name of a mountable. In quite a lot of cases,
5463 the mountable is the device name.
5464 However this doesn't apply for btrfs subvolumes, where the
5466 mountable is a combination of both the device name and the
5467 subvolume path (see also "$g->mountable_subvolume" to extract the
5468 subvolume path of the mountable if any).
5469 $subvolume = $g->mountable_subvolume ($mountable);
5471 Returns the subvolume path of a mountable. Btrfs subvolumes
5472 mountables are a combination of both the device name and the
5473 subvolume path (see also "$g->mountable_device" to extract the
5474 device of the mountable).
5475 If the mountable does not represent a btrfs subvolume, then this
5477 function fails and the "errno" is set to "EINVAL".
5478 %mps = $g->mountpoints ();
5480 This call is similar to "$g->mounts". That call returns a list of
5481 devices. This one returns a hash table (map) of device name to
5482 directory where the device is mounted.
5483 @devices = $g->mounts ();
5485 This returns the list of currently mounted filesystems. It returns
5486 the list of devices (eg. /dev/sda1, /dev/VG/LV).
5487 Some internal mounts are not shown.
5489 See also: "$g->mountpoints"
5491 $g->mv ($src, $dest);
5493 This moves a file from "src" to "dest" where "dest" is either a
5494 destination filename or destination directory.
5495 See also: "$g->rename".
5497 $nrdisks = $g->nr_devices ();
5499 This returns the number of whole block devices that were added.
5500 This is the same as the number of devices that would be returned if
5501 you called "$g->list_devices".
5502 To find out the maximum number of devices that could be added, call
5504 "$g->max_disks".
5505 $status = $g->ntfs_3g_probe ($rw, $device);
5507 This command runs the ntfs-3g.probe(8) command which probes an NTFS
5508 "device" for mountability. (Not all NTFS volumes can be mounted
5509 read-write, and some cannot be mounted at all).
5510 "rw" is a boolean flag. Set it to true if you want to test if the
5512 volume can be mounted read-write. Set it to false if you want to
5513 test if the volume can be mounted read-only.
5514 The return value is an integer which 0 if the operation would
5516 succeed, or some non-zero value documented in the ntfs-3g.probe(8)
5517 manual page.
5518 This function depends on the feature "ntfs3g". See also
5520 "$g->feature-available".
5521 $g->ntfscat_i ($device, $inode, $filename);
5523 Download a file given its inode from a NTFS filesystem and save it
5524 as filename on the local machine.
5525 This allows to download some otherwise inaccessible files such as
5527 the ones within the $Extend folder.
5528 The filesystem from which to extract the file must be unmounted,
5530 otherwise the call will fail.
5531 $g->ntfsclone_in ($backupfile, $device);
5533 Restore the "backupfile" (from a previous call to
5534 "$g->ntfsclone_out") to "device", overwriting any existing contents
5535 of this device.
5536 This function depends on the feature "ntfs3g". See also
5538 "$g->feature-available".
5539 $g->ntfsclone_out ($device, $backupfile [, metadataonly =>
5541 $metadataonly] [, rescue => $rescue] [, ignorefscheck =>
5542 $ignorefscheck] [, preservetimestamps => $preservetimestamps] [, force
5543 => $force]);
5544 Stream the NTFS filesystem "device" to the local file "backupfile".
5545 The format used for the backup file is a special format used by the
5546 ntfsclone(8) tool.
5547 If the optional "metadataonly" flag is true, then only the metadata
5549 is saved, losing all the user data (this is useful for diagnosing
5550 some filesystem problems).
5551 The optional "rescue", "ignorefscheck", "preservetimestamps" and
5553 "force" flags have precise meanings detailed in the ntfsclone(8)
5554 man page.
5555 Use "$g->ntfsclone_in" to restore the file back to a libguestfs
5557 device.
5558 This function depends on the feature "ntfs3g". See also
5560 "$g->feature-available".
5561 $g->ntfsfix ($device [, clearbadsectors => $clearbadsectors]);
5563 This command repairs some fundamental NTFS inconsistencies, resets
5564 the NTFS journal file, and schedules an NTFS consistency check for
5565 the first boot into Windows.
5566 This is not an equivalent of Windows "chkdsk". It does not scan
5568 the filesystem for inconsistencies.
5569 The optional "clearbadsectors" flag clears the list of bad sectors.
5571 This is useful after cloning a disk with bad sectors to a new disk.
5572 This function depends on the feature "ntfs3g". See also
5574 "$g->feature-available".
5575 $g->ntfsresize ($device [, size => $size] [, force => $force]);
5577 This command resizes an NTFS filesystem, expanding or shrinking it
5578 to the size of the underlying device.
5579 The optional parameters are:
5581 "size"
5583 The new size (in bytes) of the filesystem. If omitted, the
5584 filesystem is resized to fit the container (eg. partition).
5585 "force"
5587 If this option is true, then force the resize of the filesystem
5588 even if the filesystem is marked as requiring a consistency
5589 check.
5590 After the resize operation, the filesystem is always marked as
5592 requiring a consistency check (for safety). You have to boot
5593 into Windows to perform this check and clear this condition.
5594 If you don't set the "force" option then it is not possible to
5595 call "$g->ntfsresize" multiple times on a single filesystem
5596 without booting into Windows between each resize.
5597 See also ntfsresize(8).
5599 This function depends on the feature "ntfsprogs". See also
5601 "$g->feature-available".
5602 $g->ntfsresize_opts ($device [, size => $size] [, force => $force]);
5604 This is an alias of "ntfsresize".
5605 $g->ntfsresize_size ($device, $size);
5607 This command is the same as "$g->ntfsresize" except that it allows
5608 you to specify the new size (in bytes) explicitly.
5609 This function depends on the feature "ntfsprogs". See also
5611 "$g->feature-available".
5612 This function is deprecated. In new code, use the "ntfsresize"
5614 call instead.
5615 Deprecated functions will not be removed from the API, but the fact
5617 that they are deprecated indicates that there are problems with
5618 correct use of these functions.
5619 $g->parse_environment ();
5621 Parse the program’s environment and set flags in the handle
5622 accordingly. For example if "LIBGUESTFS_DEBUG=1" then the
5623 ‘verbose’ flag is set in the handle.
5624 Most programs do not need to call this. It is done implicitly when
5626 you call "$g->create".
5627 See "ENVIRONMENT VARIABLES" in guestfs(3) for a list of environment
5629 variables that can affect libguestfs handles. See also
5630 "guestfs_create_flags" in guestfs(3), and
5631 "$g->parse_environment_list".
5632 $g->parse_environment_list (\@environment);
5634 Parse the list of strings in the argument "environment" and set
5635 flags in the handle accordingly. For example if
5636 "LIBGUESTFS_DEBUG=1" is a string in the list, then the ‘verbose’
5637 flag is set in the handle.
5638 This is the same as "$g->parse_environment" except that it parses
5640 an explicit list of strings instead of the program's environment.
5641 $g->part_add ($device, $prlogex, $startsect, $endsect);
5643 This command adds a partition to "device". If there is no
5644 partition table on the device, call "$g->part_init" first.
5645 The "prlogex" parameter is the type of partition. Normally you
5647 should pass "p" or "primary" here, but MBR partition tables also
5648 support "l" (or "logical") and "e" (or "extended") partition types.
5649 "startsect" and "endsect" are the start and end of the partition in
5651 sectors. "endsect" may be negative, which means it counts
5652 backwards from the end of the disk (-1 is the last sector).
5653 Creating a partition which covers the whole disk is not so easy.
5655 Use "$g->part_disk" to do that.
5656 $g->part_del ($device, $partnum);
5658 This command deletes the partition numbered "partnum" on "device".
5659 Note that in the case of MBR partitioning, deleting an extended
5661 partition also deletes any logical partitions it contains.
5662 $g->part_disk ($device, $parttype);
5664 This command is simply a combination of "$g->part_init" followed by
5665 "$g->part_add" to create a single primary partition covering the
5666 whole disk.
5667 "parttype" is the partition table type, usually "mbr" or "gpt", but
5669 other possible values are described in "$g->part_init".
5670 $g->part_expand_gpt ($device);
5672 Move backup GPT data structures to the end of the disk. This is
5673 useful in case of in-place image expand since disk space after
5674 backup GPT header is not usable. This is equivalent to "sgdisk
5675 -e".
5676 See also sgdisk(8).
5678 This function depends on the feature "gdisk". See also
5680 "$g->feature-available".
5681 $bootable = $g->part_get_bootable ($device, $partnum);
5683 This command returns true if the partition "partnum" on "device"
5684 has the bootable flag set.
5685 See also "$g->part_set_bootable".
5687 $guid = $g->part_get_disk_guid ($device);
5689 Return the disk identifier (GUID) of a GPT-partitioned "device".
5690 Behaviour is undefined for other partition types.
5691 This function depends on the feature "gdisk". See also
5693 "$g->feature-available".
5694 $attributes = $g->part_get_gpt_attributes ($device, $partnum);
5696 Return the attribute flags of numbered GPT partition "partnum". An
5697 error is returned for MBR partitions.
5698 This function depends on the feature "gdisk". See also
5700 "$g->feature-available".
5701 $guid = $g->part_get_gpt_guid ($device, $partnum);
5703 Return the GUID of numbered GPT partition "partnum".
5704 This function depends on the feature "gdisk". See also
5706 "$g->feature-available".
5707 $guid = $g->part_get_gpt_type ($device, $partnum);
5709 Return the type GUID of numbered GPT partition "partnum". For MBR
5710 partitions, return an appropriate GUID corresponding to the MBR
5711 type. Behaviour is undefined for other partition types.
5712 This function depends on the feature "gdisk". See also
5714 "$g->feature-available".
5715 $idbyte = $g->part_get_mbr_id ($device, $partnum);
5717 Returns the MBR type byte (also known as the ID byte) from the
5718 numbered partition "partnum".
5719 Note that only MBR (old DOS-style) partitions have type bytes. You
5721 will get undefined results for other partition table types (see
5722 "$g->part_get_parttype").
5723 $partitiontype = $g->part_get_mbr_part_type ($device, $partnum);
5725 This returns the partition type of an MBR partition numbered
5726 "partnum" on device "device".
5727 It returns "primary", "logical", or "extended".
5729 $name = $g->part_get_name ($device, $partnum);
5731 This gets the partition name on partition numbered "partnum" on
5732 device "device". Note that partitions are numbered from 1.
5733 The partition name can only be read on certain types of partition
5735 table. This works on "gpt" but not on "mbr" partitions.
5736 $parttype = $g->part_get_parttype ($device);
5738 This command examines the partition table on "device" and returns
5739 the partition table type (format) being used.
5740 Common return values include: "msdos" (a DOS/Windows style MBR
5742 partition table), "gpt" (a GPT/EFI-style partition table). Other
5743 values are possible, although unusual. See "$g->part_init" for a
5744 full list.
5745 $g->part_init ($device, $parttype);
5747 This creates an empty partition table on "device" of one of the
5748 partition types listed below. Usually "parttype" should be either
5749 "msdos" or "gpt" (for large disks).
5750 Initially there are no partitions. Following this, you should call
5752 "$g->part_add" for each partition required.
5753 Possible values for "parttype" are:
5755 "efi"
5757 "gpt"
5758 Intel EFI / GPT partition table.
5759 This is recommended for >= 2 TB partitions that will be
5761 accessed from Linux and Intel-based Mac OS X. It also has
5762 limited backwards compatibility with the "mbr" format.
5763 "mbr"
5765 "msdos"
5766 The standard PC "Master Boot Record" (MBR) format used by MS-
5767 DOS and Windows. This partition type will only work for device
5768 sizes up to 2 TB. For large disks we recommend using "gpt".
5769 Other partition table types that may work but are not supported
5771 include:
5772 "aix"
5774 AIX disk labels.
5775 "amiga"
5777 "rdb"
5778 Amiga "Rigid Disk Block" format.
5779 "bsd"
5781 BSD disk labels.
5782 "dasd"
5784 DASD, used on IBM mainframes.
5785 "dvh"
5787 MIPS/SGI volumes.
5788 "mac"
5790 Old Mac partition format. Modern Macs use "gpt".
5791 "pc98"
5793 NEC PC-98 format, common in Japan apparently.
5794 "sun"
5796 Sun disk labels.
5797 @partitions = $g->part_list ($device);
5799 This command parses the partition table on "device" and returns the
5800 list of partitions found.
5801 The fields in the returned structure are:
5803 "part_num"
5805 Partition number, counting from 1.
5806 "part_start"
5808 Start of the partition in bytes. To get sectors you have to
5809 divide by the device’s sector size, see "$g->blockdev_getss".
5810 "part_end"
5812 End of the partition in bytes.
5813 "part_size"
5815 Size of the partition in bytes.
5816 $g->part_resize ($device, $partnum, $endsect);
5818 This command resizes the partition numbered "partnum" on "device"
5819 by moving the end position.
5820 Note that this does not modify any filesystem present in the
5822 partition. If you wish to do this, you will need to use filesystem
5823 resizing commands like "$g->resize2fs".
5824 When growing a partition you will want to grow the filesystem
5826 afterwards, but when shrinking, you need to shrink the filesystem
5827 before the partition.
5828 $g->part_set_bootable ($device, $partnum, $bootable);
5830 This sets the bootable flag on partition numbered "partnum" on
5831 device "device". Note that partitions are numbered from 1.
5832 The bootable flag is used by some operating systems (notably
5834 Windows) to determine which partition to boot from. It is by no
5835 means universally recognized.
5836 $g->part_set_disk_guid ($device, $guid);
5838 Set the disk identifier (GUID) of a GPT-partitioned "device" to
5839 "guid". Return an error if the partition table of "device" isn't
5840 GPT, or if "guid" is not a valid GUID.
5841 This function depends on the feature "gdisk". See also
5843 "$g->feature-available".
5844 $g->part_set_disk_guid_random ($device);
5846 Set the disk identifier (GUID) of a GPT-partitioned "device" to a
5847 randomly generated value. Return an error if the partition table
5848 of "device" isn't GPT.
5849 This function depends on the feature "gdisk". See also
5851 "$g->feature-available".
5852 $g->part_set_gpt_attributes ($device, $partnum, $attributes);
5854 Set the attribute flags of numbered GPT partition "partnum" to
5855 "attributes". Return an error if the partition table of "device"
5856 isn't GPT.
5857 See
5859 <https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_entries>
5860 for a useful list of partition attributes.
5861 This function depends on the feature "gdisk". See also
5863 "$g->feature-available".
5864 $g->part_set_gpt_guid ($device, $partnum, $guid);
5866 Set the GUID of numbered GPT partition "partnum" to "guid". Return
5867 an error if the partition table of "device" isn't GPT, or if "guid"
5868 is not a valid GUID.
5869 This function depends on the feature "gdisk". See also
5871 "$g->feature-available".
5872 $g->part_set_gpt_type ($device, $partnum, $guid);
5874 Set the type GUID of numbered GPT partition "partnum" to "guid".
5875 Return an error if the partition table of "device" isn't GPT, or if
5876 "guid" is not a valid GUID.
5877 See
5879 <https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs>
5880 for a useful list of type GUIDs.
5881 This function depends on the feature "gdisk". See also
5883 "$g->feature-available".
5884 $g->part_set_mbr_id ($device, $partnum, $idbyte);
5886 Sets the MBR type byte (also known as the ID byte) of the numbered
5887 partition "partnum" to "idbyte". Note that the type bytes quoted
5888 in most documentation are in fact hexadecimal numbers, but usually
5889 documented without any leading "0x" which might be confusing.
5890 Note that only MBR (old DOS-style) partitions have type bytes. You
5892 will get undefined results for other partition table types (see
5893 "$g->part_get_parttype").
5894 $g->part_set_name ($device, $partnum, $name);
5896 This sets the partition name on partition numbered "partnum" on
5897 device "device". Note that partitions are numbered from 1.
5898 The partition name can only be set on certain types of partition
5900 table. This works on "gpt" but not on "mbr" partitions.
5901 $device = $g->part_to_dev ($partition);
5903 This function takes a partition name (eg. "/dev/sdb1") and removes
5904 the partition number, returning the device name (eg. "/dev/sdb").
5905 The named partition must exist, for example as a string returned
5907 from "$g->list_partitions".
5908 See also "$g->part_to_partnum", "$g->device_index".
5910 $partnum = $g->part_to_partnum ($partition);
5912 This function takes a partition name (eg. "/dev/sdb1") and returns
5913 the partition number (eg. 1).
5914 The named partition must exist, for example as a string returned
5916 from "$g->list_partitions".
5917 See also "$g->part_to_dev".
5919 $g->ping_daemon ();
5921 This is a test probe into the guestfs daemon running inside the
5922 libguestfs appliance. Calling this function checks that the daemon
5923 responds to the ping message, without affecting the daemon or
5924 attached block device(s) in any other way.
5925 $content = $g->pread ($path, $count, $offset);
5927 This command lets you read part of a file. It reads "count" bytes
5928 of the file, starting at "offset", from file "path".
5929 This may read fewer bytes than requested. For further details see
5931 the pread(2) system call.
5932 See also "$g->pwrite", "$g->pread_device".
5934 Because of the message protocol, there is a transfer limit of
5936 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5937 guestfs(3).
5938 $content = $g->pread_device ($device, $count, $offset);
5940 This command lets you read part of a block device. It reads
5941 "count" bytes of "device", starting at "offset".
5942 This may read fewer bytes than requested. For further details see
5944 the pread(2) system call.
5945 See also "$g->pread".
5947 Because of the message protocol, there is a transfer limit of
5949 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5950 guestfs(3).
5951 $g->pvchange_uuid ($device);
5953 Generate a new random UUID for the physical volume "device".
5954 This function depends on the feature "lvm2". See also
5956 "$g->feature-available".
5957 $g->pvchange_uuid_all ();
5959 Generate new random UUIDs for all physical volumes.
5960 This function depends on the feature "lvm2". See also
5962 "$g->feature-available".
5963 $g->pvcreate ($device);
5965 This creates an LVM physical volume on the named "device", where
5966 "device" should usually be a partition name such as /dev/sda1.
5967 This function depends on the feature "lvm2". See also
5969 "$g->feature-available".
5970 $g->pvremove ($device);
5972 This wipes a physical volume "device" so that LVM will no longer
5973 recognise it.
5974 The implementation uses the pvremove(8) command which refuses to
5976 wipe physical volumes that contain any volume groups, so you have
5977 to remove those first.
5978 This function depends on the feature "lvm2". See also
5980 "$g->feature-available".
5981 $g->pvresize ($device);
5983 This resizes (expands or shrinks) an existing LVM physical volume
5984 to match the new size of the underlying device.
5985 This function depends on the feature "lvm2". See also
5987 "$g->feature-available".
5988 $g->pvresize_size ($device, $size);
5990 This command is the same as "$g->pvresize" except that it allows
5991 you to specify the new size (in bytes) explicitly.
5992 This function depends on the feature "lvm2". See also
5994 "$g->feature-available".
5995 @physvols = $g->pvs ();
5997 List all the physical volumes detected. This is the equivalent of
5998 the pvs(8) command.
5999 This returns a list of just the device names that contain PVs (eg.
6001 /dev/sda2).
6002 See also "$g->pvs_full".
6004 This function depends on the feature "lvm2". See also
6006 "$g->feature-available".
6007 @physvols = $g->pvs_full ();
6009 List all the physical volumes detected. This is the equivalent of
6010 the pvs(8) command. The "full" version includes all fields.
6011 This function depends on the feature "lvm2". See also
6013 "$g->feature-available".
6014 $uuid = $g->pvuuid ($device);
6016 This command returns the UUID of the LVM PV "device".
6017 $nbytes = $g->pwrite ($path, $content, $offset);
6019 This command writes to part of a file. It writes the data buffer
6020 "content" to the file "path" starting at offset "offset".
6021 This command implements the pwrite(2) system call, and like that
6023 system call it may not write the full data requested. The return
6024 value is the number of bytes that were actually written to the
6025 file. This could even be 0, although short writes are unlikely for
6026 regular files in ordinary circumstances.
6027 See also "$g->pread", "$g->pwrite_device".
6029 Because of the message protocol, there is a transfer limit of
6031 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
6032 guestfs(3).
6033 $nbytes = $g->pwrite_device ($device, $content, $offset);
6035 This command writes to part of a device. It writes the data buffer
6036 "content" to "device" starting at offset "offset".
6037 This command implements the pwrite(2) system call, and like that
6039 system call it may not write the full data requested (although
6040 short writes to disk devices and partitions are probably impossible
6041 with standard Linux kernels).
6042 See also "$g->pwrite".
6044 Because of the message protocol, there is a transfer limit of
6046 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
6047 guestfs(3).
6048 $content = $g->read_file ($path);
6050 This calls returns the contents of the file "path" as a buffer.
6051 Unlike "$g->cat", this function can correctly handle files that
6053 contain embedded ASCII NUL characters.
6054 @lines = $g->read_lines ($path);
6056 Return the contents of the file named "path".
6057 The file contents are returned as a list of lines. Trailing "LF"
6059 and "CRLF" character sequences are not returned.
6060 Note that this function cannot correctly handle binary files
6062 (specifically, files containing "\0" character which is treated as
6063 end of string). For those you need to use the "$g->read_file"
6064 function and split the buffer into lines yourself.
6065 @entries = $g->readdir ($dir);
6067 This returns the list of directory entries in directory "dir".
6068 All entries in the directory are returned, including "." and "..".
6070 The entries are not sorted, but returned in the same order as the
6071 underlying filesystem.
6072 Also this call returns basic file type information about each file.
6074 The "ftyp" field will contain one of the following characters:
6075 'b' Block special
6077 'c' Char special
6079 'd' Directory
6081 'f' FIFO (named pipe)
6083 'l' Symbolic link
6085 'r' Regular file
6087 's' Socket
6089 'u' Unknown file type
6091 '?' The readdir(3) call returned a "d_type" field with an
6093 unexpected value
6094 This function is primarily intended for use by programs. To get a
6096 simple list of names, use "$g->ls". To get a printable directory
6097 for human consumption, use "$g->ll".
6098 $link = $g->readlink ($path);
6100 This command reads the target of a symbolic link.
6101 @links = $g->readlinklist ($path, \@names);
6103 This call allows you to do a "readlink" operation on multiple
6104 files, where all files are in the directory "path". "names" is the
6105 list of files from this directory.
6106 On return you get a list of strings, with a one-to-one
6108 correspondence to the "names" list. Each string is the value of
6109 the symbolic link.
6110 If the readlink(2) operation fails on any name, then the
6112 corresponding result string is the empty string "". However the
6113 whole operation is completed even if there were readlink(2) errors,
6114 and so you can call this function with names where you don't know
6115 if they are symbolic links already (albeit slightly less
6116 efficient).
6117 This call is intended for programs that want to efficiently list a
6119 directory contents without making many round-trips.
6120 $rpath = $g->realpath ($path);
6122 Return the canonicalized absolute pathname of "path". The returned
6123 path has no ".", ".." or symbolic link path elements.
6124 $g->remount ($mountpoint [, rw => $rw]);
6126 This call allows you to change the "rw" (readonly/read-write) flag
6127 on an already mounted filesystem at "mountpoint", converting a
6128 readonly filesystem to be read-write, or vice-versa.
6129 Note that at the moment you must supply the "optional" "rw"
6131 parameter. In future we may allow other flags to be adjusted.
6132 $g->remove_drive ($label);
6134 This call does nothing and returns an error.
6135 This function is deprecated. There is no replacement. Consult the
6137 API documentation in guestfs(3) for further information.
6138 Deprecated functions will not be removed from the API, but the fact
6140 that they are deprecated indicates that there are problems with
6141 correct use of these functions.
6142 $g->removexattr ($xattr, $path);
6144 This call removes the extended attribute named "xattr" of the file
6145 "path".
6146 See also: "$g->lremovexattr", attr(5).
6148 This function depends on the feature "linuxxattrs". See also
6150 "$g->feature-available".
6151 $g->rename ($oldpath, $newpath);
6153 Rename a file to a new place on the same filesystem. This is the
6154 same as the Linux rename(2) system call. In most cases you are
6155 better to use "$g->mv" instead.
6156 $g->resize2fs ($device);
6158 This resizes an ext2, ext3 or ext4 filesystem to match the size of
6159 the underlying device.
6160 See also "RESIZE2FS ERRORS" in guestfs(3).
6162 $g->resize2fs_M ($device);
6164 This command is the same as "$g->resize2fs", but the filesystem is
6165 resized to its minimum size. This works like the -M option to the
6166 resize2fs(8) command.
6167 To get the resulting size of the filesystem you should call
6169 "$g->tune2fs_l" and read the "Block size" and "Block count" values.
6170 These two numbers, multiplied together, give the resulting size of
6171 the minimal filesystem in bytes.
6172 See also "RESIZE2FS ERRORS" in guestfs(3).
6174 $g->resize2fs_size ($device, $size);
6176 This command is the same as "$g->resize2fs" except that it allows
6177 you to specify the new size (in bytes) explicitly.
6178 See also "RESIZE2FS ERRORS" in guestfs(3).
6180 $g->rm ($path);
6182 Remove the single file "path".
6183 $g->rm_f ($path);
6185 Remove the file "path".
6186 If the file doesn't exist, that error is ignored. (Other errors,
6188 eg. I/O errors or bad paths, are not ignored)
6189 This call cannot remove directories. Use "$g->rmdir" to remove an
6191 empty directory, or "$g->rm_rf" to remove directories recursively.
6192 $g->rm_rf ($path);
6194 Remove the file or directory "path", recursively removing the
6195 contents if its a directory. This is like the "rm -rf" shell
6196 command.
6197 $g->rmdir ($path);
6199 Remove the single directory "path".
6200 $g->rmmountpoint ($exemptpath);
6202 This call removes a mountpoint that was previously created with
6203 "$g->mkmountpoint". See "$g->mkmountpoint" for full details.
6204 $g->rsync ($src, $dest [, archive => $archive] [, deletedest =>
6206 $deletedest]);
6207 This call may be used to copy or synchronize two directories under
6208 the same libguestfs handle. This uses the rsync(1) program which
6209 uses a fast algorithm that avoids copying files unnecessarily.
6210 "src" and "dest" are the source and destination directories. Files
6212 are copied from "src" to "dest".
6213 The optional arguments are:
6215 "archive"
6217 Turns on archive mode. This is the same as passing the
6218 --archive flag to "rsync".
6219 "deletedest"
6221 Delete files at the destination that do not exist at the
6222 source.
6223 This function depends on the feature "rsync". See also
6225 "$g->feature-available".
6226 $g->rsync_in ($remote, $dest [, archive => $archive] [, deletedest =>
6228 $deletedest]);
6229 This call may be used to copy or synchronize the filesystem on the
6230 host or on a remote computer with the filesystem within libguestfs.
6231 This uses the rsync(1) program which uses a fast algorithm that
6232 avoids copying files unnecessarily.
6233 This call only works if the network is enabled. See
6235 "$g->set_network" or the --network option to various tools like
6236 guestfish(1).
6237 Files are copied from the remote server and directory specified by
6239 "remote" to the destination directory "dest".
6240 The format of the remote server string is defined by rsync(1).
6242 Note that there is no way to supply a password or passphrase so the
6243 target must be set up not to require one.
6244 The optional arguments are the same as those of "$g->rsync".
6246 This function depends on the feature "rsync". See also
6248 "$g->feature-available".
6249 $g->rsync_out ($src, $remote [, archive => $archive] [, deletedest =>
6251 $deletedest]);
6252 This call may be used to copy or synchronize the filesystem within
6253 libguestfs with a filesystem on the host or on a remote computer.
6254 This uses the rsync(1) program which uses a fast algorithm that
6255 avoids copying files unnecessarily.
6256 This call only works if the network is enabled. See
6258 "$g->set_network" or the --network option to various tools like
6259 guestfish(1).
6260 Files are copied from the source directory "src" to the remote
6262 server and directory specified by "remote".
6263 The format of the remote server string is defined by rsync(1).
6265 Note that there is no way to supply a password or passphrase so the
6266 target must be set up not to require one.
6267 The optional arguments are the same as those of "$g->rsync".
6269 Globbing does not happen on the "src" parameter. In programs which
6271 use the API directly you have to expand wildcards yourself (see
6272 "$g->glob_expand"). In guestfish you can use the "glob" command
6273 (see "glob" in guestfish(1)), for example:
6274 ><fs> glob rsync-out /* rsync://remote/
6276 This function depends on the feature "rsync". See also
6278 "$g->feature-available".
6279 $g->scrub_device ($device);
6281 This command writes patterns over "device" to make data retrieval
6282 more difficult.
6283 It is an interface to the scrub(1) program. See that manual page
6285 for more details.
6286 This function depends on the feature "scrub". See also
6288 "$g->feature-available".
6289 $g->scrub_file ($file);
6291 This command writes patterns over a file to make data retrieval
6292 more difficult.
6293 The file is removed after scrubbing.
6295 It is an interface to the scrub(1) program. See that manual page
6297 for more details.
6298 This function depends on the feature "scrub". See also
6300 "$g->feature-available".
6301 $g->scrub_freespace ($dir);
6303 This command creates the directory "dir" and then fills it with
6304 files until the filesystem is full, and scrubs the files as for
6305 "$g->scrub_file", and deletes them. The intention is to scrub any
6306 free space on the partition containing "dir".
6307 It is an interface to the scrub(1) program. See that manual page
6309 for more details.
6310 This function depends on the feature "scrub". See also
6312 "$g->feature-available".
6313 $g->selinux_relabel ($specfile, $path [, force => $force]);
6315 SELinux relabel parts of the filesystem.
6316 The "specfile" parameter controls the policy spec file used. You
6318 have to parse "/etc/selinux/config" to find the correct SELinux
6319 policy and then pass the spec file, usually: "/etc/selinux/" +
6320 selinuxtype + "/contexts/files/file_contexts".
6321 The required "path" parameter is the top level directory where
6323 relabelling starts. Normally you should pass "path" as "/" to
6324 relabel the whole guest filesystem.
6325 The optional "force" boolean controls whether the context is reset
6327 for customizable files, and also whether the user, role and range
6328 parts of the file context is changed.
6329 This function depends on the feature "selinuxrelabel". See also
6331 "$g->feature-available".
6332 $g->set_append ($append);
6334 This function is used to add additional options to the libguestfs
6335 appliance kernel command line.
6336 The default is "NULL" unless overridden by setting
6338 "LIBGUESTFS_APPEND" environment variable.
6339 Setting "append" to "NULL" means no additional options are passed
6341 (libguestfs always adds a few of its own).
6342 $g->set_attach_method ($backend);
6344 Set the method that libguestfs uses to connect to the backend
6345 guestfsd daemon.
6346 See "BACKEND" in guestfs(3).
6348 This function is deprecated. In new code, use the "set_backend"
6350 call instead.
6351 Deprecated functions will not be removed from the API, but the fact
6353 that they are deprecated indicates that there are problems with
6354 correct use of these functions.
6355 $g->set_autosync ($autosync);
6357 If "autosync" is true, this enables autosync. Libguestfs will make
6358 a best effort attempt to make filesystems consistent and
6359 synchronized when the handle is closed (also if the program exits
6360 without closing handles).
6361 This is enabled by default (since libguestfs 1.5.24, previously it
6363 was disabled by default).
6364 $g->set_backend ($backend);
6366 Set the method that libguestfs uses to connect to the backend
6367 guestfsd daemon.
6368 This handle property was previously called the "attach method".
6370 See "BACKEND" in guestfs(3).
6372 $g->set_backend_setting ($name, $val);
6374 Append "name=value" to the backend settings string list. However
6375 if a string already exists matching "name" or beginning with
6376 "name=", then that setting is replaced.
6377 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
6379 $g->set_backend_settings (\@settings);
6381 Set a list of zero or more settings which are passed through to the
6382 current backend. Each setting is a string which is interpreted in
6383 a backend-specific way, or ignored if not understood by the
6384 backend.
6385 The default value is an empty list, unless the environment variable
6387 "LIBGUESTFS_BACKEND_SETTINGS" was set when the handle was created.
6388 This environment variable contains a colon-separated list of
6389 settings.
6390 This call replaces all backend settings. If you want to replace a
6392 single backend setting, see "$g->set_backend_setting". If you want
6393 to clear a single backend setting, see "$g->clear_backend_setting".
6394 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
6396 $g->set_cachedir ($cachedir);
6398 Set the directory used by the handle to store the appliance cache,
6399 when using a supermin appliance. The appliance is cached and
6400 shared between all handles which have the same effective user ID.
6401 The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR"
6403 control the default value: If "LIBGUESTFS_CACHEDIR" is set, then
6404 that is the default. Else if "TMPDIR" is set, then that is the
6405 default. Else /var/tmp is the default.
6406 $g->set_direct ($direct);
6408 If the direct appliance mode flag is enabled, then stdin and stdout
6409 are passed directly through to the appliance once it is launched.
6410 One consequence of this is that log messages aren't caught by the
6412 library and handled by "$g->set_log_message_callback", but go
6413 straight to stdout.
6414 You probably don't want to use this unless you know what you are
6416 doing.
6417 The default is disabled.
6419 This function is deprecated. In new code, use the
6421 "internal_get_console_socket" call instead.
6422 Deprecated functions will not be removed from the API, but the fact
6424 that they are deprecated indicates that there are problems with
6425 correct use of these functions.
6426 $g->set_e2attrs ($file, $attrs [, clear => $clear]);
6428 This sets or clears the file attributes "attrs" associated with the
6429 inode file.
6430 "attrs" is a string of characters representing file attributes.
6432 See "$g->get_e2attrs" for a list of possible attributes. Not all
6433 attributes can be changed.
6434 If optional boolean "clear" is not present or false, then the
6436 "attrs" listed are set in the inode.
6437 If "clear" is true, then the "attrs" listed are cleared in the
6439 inode.
6440 In both cases, other attributes not present in the "attrs" string
6442 are left unchanged.
6443 These attributes are only present when the file is located on an
6445 ext2/3/4 filesystem. Using this call on other filesystem types
6446 will result in an error.
6447 $g->set_e2generation ($file, $generation);
6449 This sets the ext2 file generation of a file.
6450 See "$g->get_e2generation".
6452 $g->set_e2label ($device, $label);
6454 This sets the ext2/3/4 filesystem label of the filesystem on
6455 "device" to "label". Filesystem labels are limited to 16
6456 characters.
6457 You can use either "$g->tune2fs_l" or "$g->get_e2label" to return
6459 the existing label on a filesystem.
6460 This function is deprecated. In new code, use the "set_label" call
6462 instead.
6463 Deprecated functions will not be removed from the API, but the fact
6465 that they are deprecated indicates that there are problems with
6466 correct use of these functions.
6467 $g->set_e2uuid ($device, $uuid);
6469 This sets the ext2/3/4 filesystem UUID of the filesystem on
6470 "device" to "uuid". The format of the UUID and alternatives such
6471 as "clear", "random" and "time" are described in the tune2fs(8)
6472 manpage.
6473 You can use "$g->vfs_uuid" to return the existing UUID of a
6475 filesystem.
6476 This function is deprecated. In new code, use the "set_uuid" call
6478 instead.
6479 Deprecated functions will not be removed from the API, but the fact
6481 that they are deprecated indicates that there are problems with
6482 correct use of these functions.
6483 $g->set_hv ($hv);
6485 Set the hypervisor binary that we will use. The hypervisor depends
6486 on the backend, but is usually the location of the qemu/KVM
6487 hypervisor.
6488 The default is chosen when the library was compiled by the
6490 configure script.
6491 You can also override this by setting the "LIBGUESTFS_HV"
6493 environment variable.
6494 Note that you should call this function as early as possible after
6496 creating the handle. This is because some pre-launch operations
6497 depend on testing qemu features (by running "qemu -help"). If the
6498 qemu binary changes, we don't retest features, and so you might see
6499 inconsistent results. Using the environment variable
6500 "LIBGUESTFS_HV" is safest of all since that picks the qemu binary
6501 at the same time as the handle is created.
6502 $g->set_identifier ($identifier);
6504 This is an informative string which the caller may optionally set
6505 in the handle. It is printed in various places, allowing the
6506 current handle to be identified in debugging output.
6507 One important place is when tracing is enabled. If the identifier
6509 string is not an empty string, then trace messages change from
6510 this:
6511 libguestfs: trace: get_tmpdir
6513 libguestfs: trace: get_tmpdir = "/tmp"
6514 to this:
6516 libguestfs: trace: ID: get_tmpdir
6518 libguestfs: trace: ID: get_tmpdir = "/tmp"
6519 where "ID" is the identifier string set by this call.
6521 The identifier must only contain alphanumeric ASCII characters,
6523 underscore and minus sign. The default is the empty string.
6524 See also "$g->set_program", "$g->set_trace", "$g->get_identifier".
6526 $g->set_label ($mountable, $label);
6528 Set the filesystem label on "mountable" to "label".
6529 Only some filesystem types support labels, and libguestfs supports
6531 setting labels on only a subset of these.
6532 ext2, ext3, ext4
6534 Labels are limited to 16 bytes.
6535 NTFS
6537 Labels are limited to 128 unicode characters.
6538 XFS The label is limited to 12 bytes. The filesystem must not be
6540 mounted when trying to set the label.
6541 btrfs
6543 The label is limited to 255 bytes and some characters are not
6544 allowed. Setting the label on a btrfs subvolume will set the
6545 label on its parent filesystem. The filesystem must not be
6546 mounted when trying to set the label.
6547 fat The label is limited to 11 bytes.
6549 swap
6551 The label is limited to 16 bytes.
6552 If there is no support for changing the label for the type of the
6554 specified filesystem, set_label will fail and set errno as ENOTSUP.
6555 To read the label on a filesystem, call "$g->vfs_label".
6557 $g->set_libvirt_requested_credential ($index, $cred);
6559 After requesting the "index"'th credential from the user, call this
6560 function to pass the answer back to libvirt.
6561 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
6563 example code.
6564 $g->set_libvirt_supported_credentials (\@creds);
6566 Call this function before setting an event handler for
6567 "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential
6568 types that the program knows how to process.
6569 The "creds" list must be a non-empty list of strings. Possible
6571 strings are:
6572 "username"
6574 "authname"
6575 "language"
6576 "cnonce"
6577 "passphrase"
6578 "echoprompt"
6579 "noechoprompt"
6580 "realm"
6581 "external"
6582 See libvirt documentation for the meaning of these credential
6584 types.
6585 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
6587 example code.
6588 $g->set_memsize ($memsize);
6590 This sets the memory size in megabytes allocated to the hypervisor.
6591 This only has any effect if called before "$g->launch".
6592 You can also change this by setting the environment variable
6594 "LIBGUESTFS_MEMSIZE" before the handle is created.
6595 For more information on the architecture of libguestfs, see
6597 guestfs(3).
6598 $g->set_network ($network);
6600 If "network" is true, then the network is enabled in the libguestfs
6601 appliance. The default is false.
6602 This affects whether commands are able to access the network (see
6604 "RUNNING COMMANDS" in guestfs(3)).
6605 You must call this before calling "$g->launch", otherwise it has no
6607 effect.
6608 $g->set_path ($searchpath);
6610 Set the path that libguestfs searches for kernel and initrd.img.
6611 The default is "$libdir/guestfs" unless overridden by setting
6613 "LIBGUESTFS_PATH" environment variable.
6614 Setting "path" to "NULL" restores the default path.
6616 $g->set_pgroup ($pgroup);
6618 If "pgroup" is true, child processes are placed into their own
6619 process group.
6620 The practical upshot of this is that signals like "SIGINT" (from
6622 users pressing "^C") won't be received by the child process.
6623 The default for this flag is false, because usually you want "^C"
6625 to kill the subprocess. Guestfish sets this flag to true when used
6626 interactively, so that "^C" can cancel long-running commands
6627 gracefully (see "$g->user_cancel").
6628 $g->set_program ($program);
6630 Set the program name. This is an informative string which the main
6631 program may optionally set in the handle.
6632 When the handle is created, the program name in the handle is set
6634 to the basename from "argv[0]". The program name can never be
6635 "NULL".
6636 $g->set_qemu ($hv);
6638 Set the hypervisor binary (usually qemu) that we will use.
6639 The default is chosen when the library was compiled by the
6641 configure script.
6642 You can also override this by setting the "LIBGUESTFS_HV"
6644 environment variable.
6645 Setting "hv" to "NULL" restores the default qemu binary.
6647 Note that you should call this function as early as possible after
6649 creating the handle. This is because some pre-launch operations
6650 depend on testing qemu features (by running "qemu -help"). If the
6651 qemu binary changes, we don't retest features, and so you might see
6652 inconsistent results. Using the environment variable
6653 "LIBGUESTFS_HV" is safest of all since that picks the qemu binary
6654 at the same time as the handle is created.
6655 This function is deprecated. In new code, use the "set_hv" call
6657 instead.
6658 Deprecated functions will not be removed from the API, but the fact
6660 that they are deprecated indicates that there are problems with
6661 correct use of these functions.
6662 $g->set_recovery_proc ($recoveryproc);
6664 If this is called with the parameter "false" then "$g->launch" does
6665 not create a recovery process. The purpose of the recovery process
6666 is to stop runaway hypervisor processes in the case where the main
6667 program aborts abruptly.
6668 This only has any effect if called before "$g->launch", and the
6670 default is true.
6671 About the only time when you would want to disable this is if the
6673 main process will fork itself into the background ("daemonize"
6674 itself). In this case the recovery process thinks that the main
6675 program has disappeared and so kills the hypervisor, which is not
6676 very helpful.
6677 $g->set_selinux ($selinux);
6679 This sets the selinux flag that is passed to the appliance at boot
6680 time. The default is "selinux=0" (disabled).
6681 Note that if SELinux is enabled, it is always in Permissive mode
6683 ("enforcing=0").
6684 For more information on the architecture of libguestfs, see
6686 guestfs(3).
6687 This function is deprecated. In new code, use the
6689 "selinux_relabel" call instead.
6690 Deprecated functions will not be removed from the API, but the fact
6692 that they are deprecated indicates that there are problems with
6693 correct use of these functions.
6694 $g->set_smp ($smp);
6696 Change the number of virtual CPUs assigned to the appliance. The
6697 default is 1. Increasing this may improve performance, though
6698 often it has no effect.
6699 This function must be called before "$g->launch".
6701 $g->set_tmpdir ($tmpdir);
6703 Set the directory used by the handle to store temporary files.
6704 The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control
6706 the default value: If "LIBGUESTFS_TMPDIR" is set, then that is the
6707 default. Else if "TMPDIR" is set, then that is the default. Else
6708 /tmp is the default.
6709 $g->set_trace ($trace);
6711 If the command trace flag is set to 1, then libguestfs calls,
6712 parameters and return values are traced.
6713 If you want to trace C API calls into libguestfs (and other
6715 libraries) then possibly a better way is to use the external
6716 ltrace(1) command.
6717 Command traces are disabled unless the environment variable
6719 "LIBGUESTFS_TRACE" is defined and set to 1.
6720 Trace messages are normally sent to "stderr", unless you register a
6722 callback to send them somewhere else (see
6723 "$g->set_event_callback").
6724 $g->set_uuid ($device, $uuid);
6726 Set the filesystem UUID on "device" to "uuid". If this fails and
6727 the errno is ENOTSUP, means that there is no support for changing
6728 the UUID for the type of the specified filesystem.
6729 Only some filesystem types support setting UUIDs.
6731 To read the UUID on a filesystem, call "$g->vfs_uuid".
6733 $g->set_uuid_random ($device);
6735 Set the filesystem UUID on "device" to a random UUID. If this
6736 fails and the errno is ENOTSUP, means that there is no support for
6737 changing the UUID for the type of the specified filesystem.
6738 Only some filesystem types support setting UUIDs.
6740 To read the UUID on a filesystem, call "$g->vfs_uuid".
6742 $g->set_verbose ($verbose);
6744 If "verbose" is true, this turns on verbose messages.
6745 Verbose messages are disabled unless the environment variable
6747 "LIBGUESTFS_DEBUG" is defined and set to 1.
6748 Verbose messages are normally sent to "stderr", unless you register
6750 a callback to send them somewhere else (see
6751 "$g->set_event_callback").
6752 $g->setcon ($context);
6754 This sets the SELinux security context of the daemon to the string
6755 "context".
6756 See the documentation about SELINUX in guestfs(3).
6758 This function depends on the feature "selinux". See also
6760 "$g->feature-available".
6761 This function is deprecated. In new code, use the
6763 "selinux_relabel" call instead.
6764 Deprecated functions will not be removed from the API, but the fact
6766 that they are deprecated indicates that there are problems with
6767 correct use of these functions.
6768 $g->setxattr ($xattr, $val, $vallen, $path);
6770 This call sets the extended attribute named "xattr" of the file
6771 "path" to the value "val" (of length "vallen"). The value is
6772 arbitrary 8 bit data.
6773 See also: "$g->lsetxattr", attr(5).
6775 This function depends on the feature "linuxxattrs". See also
6777 "$g->feature-available".
6778 $g->sfdisk ($device, $cyls, $heads, $sectors, \@lines);
6780 This is a direct interface to the sfdisk(8) program for creating
6781 partitions on block devices.
6782 "device" should be a block device, for example /dev/sda.
6784 "cyls", "heads" and "sectors" are the number of cylinders, heads
6786 and sectors on the device, which are passed directly to sfdisk(8)
6787 as the -C, -H and -S parameters. If you pass 0 for any of these,
6788 then the corresponding parameter is omitted. Usually for ‘large’
6789 disks, you can just pass 0 for these, but for small (floppy-sized)
6790 disks, sfdisk(8) (or rather, the kernel) cannot work out the right
6791 geometry and you will need to tell it.
6792 "lines" is a list of lines that we feed to sfdisk(8). For more
6794 information refer to the sfdisk(8) manpage.
6795 To create a single partition occupying the whole disk, you would
6797 pass "lines" as a single element list, when the single element
6798 being the string "," (comma).
6799 See also: "$g->sfdisk_l", "$g->sfdisk_N", "$g->part_init"
6801 This function is deprecated. In new code, use the "part_add" call
6803 instead.
6804 Deprecated functions will not be removed from the API, but the fact
6806 that they are deprecated indicates that there are problems with
6807 correct use of these functions.
6808 $g->sfdiskM ($device, \@lines);
6810 This is a simplified interface to the "$g->sfdisk" command, where
6811 partition sizes are specified in megabytes only (rounded to the
6812 nearest cylinder) and you don't need to specify the cyls, heads and
6813 sectors parameters which were rarely if ever used anyway.
6814 See also: "$g->sfdisk", the sfdisk(8) manpage and "$g->part_disk"
6816 This function is deprecated. In new code, use the "part_add" call
6818 instead.
6819 Deprecated functions will not be removed from the API, but the fact
6821 that they are deprecated indicates that there are problems with
6822 correct use of these functions.
6823 $g->sfdisk_N ($device, $partnum, $cyls, $heads, $sectors, $line);
6825 This runs sfdisk(8) option to modify just the single partition "n"
6826 (note: "n" counts from 1).
6827 For other parameters, see "$g->sfdisk". You should usually pass 0
6829 for the cyls/heads/sectors parameters.
6830 See also: "$g->part_add"
6832 This function is deprecated. In new code, use the "part_add" call
6834 instead.
6835 Deprecated functions will not be removed from the API, but the fact
6837 that they are deprecated indicates that there are problems with
6838 correct use of these functions.
6839 $partitions = $g->sfdisk_disk_geometry ($device);
6841 This displays the disk geometry of "device" read from the partition
6842 table. Especially in the case where the underlying block device
6843 has been resized, this can be different from the kernel’s idea of
6844 the geometry (see "$g->sfdisk_kernel_geometry").
6845 The result is in human-readable format, and not designed to be
6847 parsed.
6848 $partitions = $g->sfdisk_kernel_geometry ($device);
6850 This displays the kernel’s idea of the geometry of "device".
6851 The result is in human-readable format, and not designed to be
6853 parsed.
6854 $partitions = $g->sfdisk_l ($device);
6856 This displays the partition table on "device", in the human-
6857 readable output of the sfdisk(8) command. It is not intended to be
6858 parsed.
6859 See also: "$g->part_list"
6861 This function is deprecated. In new code, use the "part_list" call
6863 instead.
6864 Deprecated functions will not be removed from the API, but the fact
6866 that they are deprecated indicates that there are problems with
6867 correct use of these functions.
6868 $output = $g->sh ($command);
6870 This call runs a command from the guest filesystem via the guest’s
6871 /bin/sh.
6872 This is like "$g->command", but passes the command to:
6874 /bin/sh -c "command"
6876 Depending on the guest’s shell, this usually results in wildcards
6878 being expanded, shell expressions being interpolated and so on.
6879 All the provisos about "$g->command" apply to this call.
6881 @lines = $g->sh_lines ($command);
6883 This is the same as "$g->sh", but splits the result into a list of
6884 lines.
6885 See also: "$g->command_lines"
6887 $g->shutdown ();
6889 This is the opposite of "$g->launch". It performs an orderly
6890 shutdown of the backend process(es). If the autosync flag is set
6891 (which is the default) then the disk image is synchronized.
6892 If the subprocess exits with an error then this function will
6894 return an error, which should not be ignored (it may indicate that
6895 the disk image could not be written out properly).
6896 It is safe to call this multiple times. Extra calls are ignored.
6898 This call does not close or free up the handle. You still need to
6900 call "$g->close" afterwards.
6901 "$g->close" will call this if you don't do it explicitly, but note
6903 that any errors are ignored in that case.
6904 $g->sleep ($secs);
6906 Sleep for "secs" seconds.
6907 %statbuf = $g->stat ($path);
6909 Returns file information for the given "path".
6910 This is the same as the stat(2) system call.
6912 This function is deprecated. In new code, use the "statns" call
6914 instead.
6915 Deprecated functions will not be removed from the API, but the fact
6917 that they are deprecated indicates that there are problems with
6918 correct use of these functions.
6919 %statbuf = $g->statns ($path);
6921 Returns file information for the given "path".
6922 This is the same as the stat(2) system call.
6924 %statbuf = $g->statvfs ($path);
6926 Returns file system statistics for any mounted file system. "path"
6927 should be a file or directory in the mounted file system (typically
6928 it is the mount point itself, but it doesn't need to be).
6929 This is the same as the statvfs(2) system call.
6931 @stringsout = $g->strings ($path);
6933 This runs the strings(1) command on a file and returns the list of
6934 printable strings found.
6935 The "strings" command has, in the past, had problems with parsing
6937 untrusted files. These are mitigated in the current version of
6938 libguestfs, but see "CVE-2014-8484" in guestfs(3).
6939 Because of the message protocol, there is a transfer limit of
6941 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
6942 guestfs(3).
6943 @stringsout = $g->strings_e ($encoding, $path);
6945 This is like the "$g->strings" command, but allows you to specify
6946 the encoding of strings that are looked for in the source file
6947 "path".
6948 Allowed encodings are:
6950 s Single 7-bit-byte characters like ASCII and the ASCII-
6952 compatible parts of ISO-8859-X (this is what "$g->strings"
6953 uses).
6954 S Single 8-bit-byte characters.
6956 b 16-bit big endian strings such as those encoded in UTF-16BE or
6958 UCS-2BE.
6959 l (lower case letter L)
6961 16-bit little endian such as UTF-16LE and UCS-2LE. This is
6962 useful for examining binaries in Windows guests.
6963 B 32-bit big endian such as UCS-4BE.
6965 L 32-bit little endian such as UCS-4LE.
6967 The returned strings are transcoded to UTF-8.
6969 The "strings" command has, in the past, had problems with parsing
6971 untrusted files. These are mitigated in the current version of
6972 libguestfs, but see "CVE-2014-8484" in guestfs(3).
6973 Because of the message protocol, there is a transfer limit of
6975 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
6976 guestfs(3).
6977 $g->swapoff_device ($device);
6979 This command disables the libguestfs appliance swap device or
6980 partition named "device". See "$g->swapon_device".
6981 $g->swapoff_file ($file);
6983 This command disables the libguestfs appliance swap on file.
6984 $g->swapoff_label ($label);
6986 This command disables the libguestfs appliance swap on labeled swap
6987 partition.
6988 $g->swapoff_uuid ($uuid);
6990 This command disables the libguestfs appliance swap partition with
6991 the given UUID.
6992 This function depends on the feature "linuxfsuuid". See also
6994 "$g->feature-available".
6995 $g->swapon_device ($device);
6997 This command enables the libguestfs appliance to use the swap
6998 device or partition named "device". The increased memory is made
6999 available for all commands, for example those run using
7000 "$g->command" or "$g->sh".
7001 Note that you should not swap to existing guest swap partitions
7003 unless you know what you are doing. They may contain hibernation
7004 information, or other information that the guest doesn't want you
7005 to trash. You also risk leaking information about the host to the
7006 guest this way. Instead, attach a new host device to the guest and
7007 swap on that.
7008 $g->swapon_file ($file);
7010 This command enables swap to a file. See "$g->swapon_device" for
7011 other notes.
7012 $g->swapon_label ($label);
7014 This command enables swap to a labeled swap partition. See
7015 "$g->swapon_device" for other notes.
7016 $g->swapon_uuid ($uuid);
7018 This command enables swap to a swap partition with the given UUID.
7019 See "$g->swapon_device" for other notes.
7020 This function depends on the feature "linuxfsuuid". See also
7022 "$g->feature-available".
7023 $g->sync ();
7025 This syncs the disk, so that any writes are flushed through to the
7026 underlying disk image.
7027 You should always call this if you have modified a disk image,
7029 before closing the handle.
7030 $g->syslinux ($device [, directory => $directory]);
7032 Install the SYSLINUX bootloader on "device".
7033 The device parameter must be either a whole disk formatted as a FAT
7035 filesystem, or a partition formatted as a FAT filesystem. In the
7036 latter case, the partition should be marked as "active"
7037 ("$g->part_set_bootable") and a Master Boot Record must be
7038 installed (eg. using "$g->pwrite_device") on the first sector of
7039 the whole disk. The SYSLINUX package comes with some suitable
7040 Master Boot Records. See the syslinux(1) man page for further
7041 information.
7042 The optional arguments are:
7044 directory
7046 Install SYSLINUX in the named subdirectory, instead of in the
7047 root directory of the FAT filesystem.
7048 Additional configuration can be supplied to SYSLINUX by placing a
7050 file called syslinux.cfg on the FAT filesystem, either in the root
7051 directory, or under directory if that optional argument is being
7052 used. For further information about the contents of this file, see
7053 syslinux(1).
7054 See also "$g->extlinux".
7056 This function depends on the feature "syslinux". See also
7058 "$g->feature-available".
7059 @lines = $g->tail ($path);
7061 This command returns up to the last 10 lines of a file as a list of
7062 strings.
7063 Because of the message protocol, there is a transfer limit of
7065 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7066 guestfs(3).
7067 @lines = $g->tail_n ($nrlines, $path);
7069 If the parameter "nrlines" is a positive number, this returns the
7070 last "nrlines" lines of the file "path".
7071 If the parameter "nrlines" is a negative number, this returns lines
7073 from the file "path", starting with the "-nrlines"'th line.
7074 If the parameter "nrlines" is zero, this returns an empty list.
7076 Because of the message protocol, there is a transfer limit of
7078 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7079 guestfs(3).
7080 $g->tar_in ($tarfile, $directory [, compress => $compress] [, xattrs =>
7082 $xattrs] [, selinux => $selinux] [, acls => $acls]);
7083 This command uploads and unpacks local file "tarfile" into
7084 directory.
7085 The optional "compress" flag controls compression. If not given,
7087 then the input should be an uncompressed tar file. Otherwise one
7088 of the following strings may be given to select the compression
7089 type of the input file: "compress", "gzip", "bzip2", "xz", "lzop",
7090 "lzma", "zstd". (Note that not all builds of libguestfs will
7091 support all of these compression types).
7092 The other optional arguments are:
7094 "xattrs"
7096 If set to true, extended attributes are restored from the tar
7097 file.
7098 "selinux"
7100 If set to true, SELinux contexts are restored from the tar
7101 file.
7102 "acls"
7104 If set to true, POSIX ACLs are restored from the tar file.
7105 $g->tar_in_opts ($tarfile, $directory [, compress => $compress] [,
7107 xattrs => $xattrs] [, selinux => $selinux] [, acls => $acls]);
7108 This is an alias of "tar_in".
7109 $g->tar_out ($directory, $tarfile [, compress => $compress] [,
7111 numericowner => $numericowner] [, excludes => $excludes] [, xattrs =>
7112 $xattrs] [, selinux => $selinux] [, acls => $acls]);
7113 This command packs the contents of directory and downloads it to
7114 local file "tarfile".
7115 The optional "compress" flag controls compression. If not given,
7117 then the output will be an uncompressed tar file. Otherwise one of
7118 the following strings may be given to select the compression type
7119 of the output file: "compress", "gzip", "bzip2", "xz", "lzop",
7120 "lzma", "zstd". (Note that not all builds of libguestfs will
7121 support all of these compression types).
7122 The other optional arguments are:
7124 "excludes"
7126 A list of wildcards. Files are excluded if they match any of
7127 the wildcards.
7128 "numericowner"
7130 If set to true, the output tar file will contain UID/GID
7131 numbers instead of user/group names.
7132 "xattrs"
7134 If set to true, extended attributes are saved in the output
7135 tar.
7136 "selinux"
7138 If set to true, SELinux contexts are saved in the output tar.
7139 "acls"
7141 If set to true, POSIX ACLs are saved in the output tar.
7142 $g->tar_out_opts ($directory, $tarfile [, compress => $compress] [,
7144 numericowner => $numericowner] [, excludes => $excludes] [, xattrs =>
7145 $xattrs] [, selinux => $selinux] [, acls => $acls]);
7146 This is an alias of "tar_out".
7147 $g->tgz_in ($tarball, $directory);
7149 This command uploads and unpacks local file "tarball" (a gzip
7150 compressed tar file) into directory.
7151 This function is deprecated. In new code, use the "tar_in" call
7153 instead.
7154 Deprecated functions will not be removed from the API, but the fact
7156 that they are deprecated indicates that there are problems with
7157 correct use of these functions.
7158 $g->tgz_out ($directory, $tarball);
7160 This command packs the contents of directory and downloads it to
7161 local file "tarball".
7162 This function is deprecated. In new code, use the "tar_out" call
7164 instead.
7165 Deprecated functions will not be removed from the API, but the fact
7167 that they are deprecated indicates that there are problems with
7168 correct use of these functions.
7169 $g->touch ($path);
7171 Touch acts like the touch(1) command. It can be used to update the
7172 timestamps on a file, or, if the file does not exist, to create a
7173 new zero-length file.
7174 This command only works on regular files, and will fail on other
7176 file types such as directories, symbolic links, block special etc.
7177 $g->truncate ($path);
7179 This command truncates "path" to a zero-length file. The file must
7180 exist already.
7181 $g->truncate_size ($path, $size);
7183 This command truncates "path" to size "size" bytes. The file must
7184 exist already.
7185 If the current file size is less than "size" then the file is
7187 extended to the required size with zero bytes. This creates a
7188 sparse file (ie. disk blocks are not allocated for the file until
7189 you write to it). To create a non-sparse file of zeroes, use
7190 "$g->fallocate64" instead.
7191 $g->tune2fs ($device [, force => $force] [, maxmountcount =>
7193 $maxmountcount] [, mountcount => $mountcount] [, errorbehavior =>
7194 $errorbehavior] [, group => $group] [, intervalbetweenchecks =>
7195 $intervalbetweenchecks] [, reservedblockspercentage =>
7196 $reservedblockspercentage] [, lastmounteddirectory =>
7197 $lastmounteddirectory] [, reservedblockscount => $reservedblockscount]
7198 [, user => $user]);
7199 This call allows you to adjust various filesystem parameters of an
7200 ext2/ext3/ext4 filesystem called "device".
7201 The optional parameters are:
7203 "force"
7205 Force tune2fs to complete the operation even in the face of
7206 errors. This is the same as the tune2fs(8) "-f" option.
7207 "maxmountcount"
7209 Set the number of mounts after which the filesystem is checked
7210 by e2fsck(8). If this is 0 then the number of mounts is
7211 disregarded. This is the same as the tune2fs(8) "-c" option.
7212 "mountcount"
7214 Set the number of times the filesystem has been mounted. This
7215 is the same as the tune2fs(8) "-C" option.
7216 "errorbehavior"
7218 Change the behavior of the kernel code when errors are
7219 detected. Possible values currently are: "continue",
7220 "remount-ro", "panic". In practice these options don't really
7221 make any difference, particularly for write errors.
7222 This is the same as the tune2fs(8) "-e" option.
7224 "group"
7226 Set the group which can use reserved filesystem blocks. This
7227 is the same as the tune2fs(8) "-g" option except that it can
7228 only be specified as a number.
7229 "intervalbetweenchecks"
7231 Adjust the maximal time between two filesystem checks (in
7232 seconds). If the option is passed as 0 then time-dependent
7233 checking is disabled.
7234 This is the same as the tune2fs(8) "-i" option.
7236 "reservedblockspercentage"
7238 Set the percentage of the filesystem which may only be
7239 allocated by privileged processes. This is the same as the
7240 tune2fs(8) "-m" option.
7241 "lastmounteddirectory"
7243 Set the last mounted directory. This is the same as the
7244 tune2fs(8) "-M" option.
7245 "reservedblockscount" Set the number of reserved filesystem blocks.
7247 This is the same as the tune2fs(8) "-r" option.
7248 "user"
7249 Set the user who can use the reserved filesystem blocks. This
7250 is the same as the tune2fs(8) "-u" option except that it can
7251 only be specified as a number.
7252 To get the current values of filesystem parameters, see
7254 "$g->tune2fs_l". For precise details of how tune2fs works, see the
7255 tune2fs(8) man page.
7256 %superblock = $g->tune2fs_l ($device);
7258 This returns the contents of the ext2, ext3 or ext4 filesystem
7259 superblock on "device".
7260 It is the same as running "tune2fs -l device". See tune2fs(8)
7262 manpage for more details. The list of fields returned isn't
7263 clearly defined, and depends on both the version of "tune2fs" that
7264 libguestfs was built against, and the filesystem itself.
7265 $g->txz_in ($tarball, $directory);
7267 This command uploads and unpacks local file "tarball" (an xz
7268 compressed tar file) into directory.
7269 This function depends on the feature "xz". See also
7271 "$g->feature-available".
7272 This function is deprecated. In new code, use the "tar_in" call
7274 instead.
7275 Deprecated functions will not be removed from the API, but the fact
7277 that they are deprecated indicates that there are problems with
7278 correct use of these functions.
7279 $g->txz_out ($directory, $tarball);
7281 This command packs the contents of directory and downloads it to
7282 local file "tarball" (as an xz compressed tar archive).
7283 This function depends on the feature "xz". See also
7285 "$g->feature-available".
7286 This function is deprecated. In new code, use the "tar_out" call
7288 instead.
7289 Deprecated functions will not be removed from the API, but the fact
7291 that they are deprecated indicates that there are problems with
7292 correct use of these functions.
7293 $oldmask = $g->umask ($mask);
7295 This function sets the mask used for creating new files and device
7296 nodes to "mask & 0777".
7297 Typical umask values would be 022 which creates new files with
7299 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which
7300 creates new files with permissions like "-rw-rw-r--" or
7301 "-rwxrwxr-x".
7302 The default umask is 022. This is important because it means that
7304 directories and device nodes will be created with 0644 or 0755 mode
7305 even if you specify 0777.
7306 See also "$g->get_umask", umask(2), "$g->mknod", "$g->mkdir".
7308 This call returns the previous umask.
7310 $g->umount ($pathordevice [, force => $force] [, lazyunmount =>
7312 $lazyunmount]);
7313 This unmounts the given filesystem. The filesystem may be
7314 specified either by its mountpoint (path) or the device which
7315 contains the filesystem.
7316 $g->umount_opts ($pathordevice [, force => $force] [, lazyunmount =>
7318 $lazyunmount]);
7319 This is an alias of "umount".
7320 $g->umount_all ();
7322 This unmounts all mounted filesystems.
7323 Some internal mounts are not unmounted by this call.
7325 $g->umount_local ([retry => $retry]);
7327 If libguestfs is exporting the filesystem on a local mountpoint,
7328 then this unmounts it.
7329 See "MOUNT LOCAL" in guestfs(3) for full documentation.
7331 $g->upload ($filename, $remotefilename);
7333 Upload local file filename to remotefilename on the filesystem.
7334 filename can also be a named pipe.
7336 See also "$g->download".
7338 $g->upload_offset ($filename, $remotefilename, $offset);
7340 Upload local file filename to remotefilename on the filesystem.
7341 remotefilename is overwritten starting at the byte "offset"
7343 specified. The intention is to overwrite parts of existing files
7344 or devices, although if a non-existent file is specified then it is
7345 created with a "hole" before "offset". The size of the data
7346 written is implicit in the size of the source filename.
7347 Note that there is no limit on the amount of data that can be
7349 uploaded with this call, unlike with "$g->pwrite", and this call
7350 always writes the full amount unless an error occurs.
7351 See also "$g->upload", "$g->pwrite".
7353 $g->user_cancel ();
7355 This function cancels the current upload or download operation.
7356 Unlike most other libguestfs calls, this function is signal safe
7358 and thread safe. You can call it from a signal handler or from
7359 another thread, without needing to do any locking.
7360 The transfer that was in progress (if there is one) will stop
7362 shortly afterwards, and will return an error. The errno (see
7363 "guestfs_last_errno") is set to "EINTR", so you can test for this
7364 to find out if the operation was cancelled or failed because of
7365 another error.
7366 No cleanup is performed: for example, if a file was being uploaded
7368 then after cancellation there may be a partially uploaded file. It
7369 is the caller’s responsibility to clean up if necessary.
7370 There are two common places that you might call "$g->user_cancel":
7372 In an interactive text-based program, you might call it from a
7374 "SIGINT" signal handler so that pressing "^C" cancels the current
7375 operation. (You also need to call "$g->set_pgroup" so that child
7376 processes don't receive the "^C" signal).
7377 In a graphical program, when the main thread is displaying a
7379 progress bar with a cancel button, wire up the cancel button to
7380 call this function.
7381 $g->utimens ($path, $atsecs, $atnsecs, $mtsecs, $mtnsecs);
7383 This command sets the timestamps of a file with nanosecond
7384 precision.
7385 "atsecs", "atnsecs" are the last access time (atime) in secs and
7387 nanoseconds from the epoch.
7388 "mtsecs", "mtnsecs" are the last modification time (mtime) in secs
7390 and nanoseconds from the epoch.
7391 If the *nsecs field contains the special value -1 then the
7393 corresponding timestamp is set to the current time. (The *secs
7394 field is ignored in this case).
7395 If the *nsecs field contains the special value -2 then the
7397 corresponding timestamp is left unchanged. (The *secs field is
7398 ignored in this case).
7399 %uts = $g->utsname ();
7401 This returns the kernel version of the appliance, where this is
7402 available. This information is only useful for debugging. Nothing
7403 in the returned structure is defined by the API.
7404 %version = $g->version ();
7406 Return the libguestfs version number that the program is linked
7407 against.
7408 Note that because of dynamic linking this is not necessarily the
7410 version of libguestfs that you compiled against. You can compile
7411 the program, and then at runtime dynamically link against a
7412 completely different libguestfs.so library.
7413 This call was added in version 1.0.58. In previous versions of
7415 libguestfs there was no way to get the version number. From C code
7416 you can use dynamic linker functions to find out if this symbol
7417 exists (if it doesn't, then it’s an earlier version).
7418 The call returns a structure with four elements. The first three
7420 ("major", "minor" and "release") are numbers and correspond to the
7421 usual version triplet. The fourth element ("extra") is a string
7422 and is normally empty, but may be used for distro-specific
7423 information.
7424 To construct the original version string:
7426 "$major.$minor.$release$extra"
7427 See also: "LIBGUESTFS VERSION NUMBERS" in guestfs(3).
7429 Note: Don't use this call to test for availability of features. In
7431 enterprise distributions we backport features from later versions
7432 into earlier versions, making this an unreliable way to test for
7433 features. Use "$g->available" or "$g->feature_available" instead.
7434 $label = $g->vfs_label ($mountable);
7436 This returns the label of the filesystem on "mountable".
7437 If the filesystem is unlabeled, this returns the empty string.
7439 To find a filesystem from the label, use "$g->findfs_label".
7441 $sizeinbytes = $g->vfs_minimum_size ($mountable);
7443 Get the minimum size of filesystem in bytes. This is the minimum
7444 possible size for filesystem shrinking.
7445 If getting minimum size of specified filesystem is not supported,
7447 this will fail and set errno as ENOTSUP.
7448 See also ntfsresize(8), resize2fs(8), btrfs(8), xfs_info(8).
7450 $fstype = $g->vfs_type ($mountable);
7452 This command gets the filesystem type corresponding to the
7453 filesystem on "mountable".
7454 For most filesystems, the result is the name of the Linux VFS
7456 module which would be used to mount this filesystem if you mounted
7457 it without specifying the filesystem type. For example a string
7458 such as "ext3" or "ntfs".
7459 $uuid = $g->vfs_uuid ($mountable);
7461 This returns the filesystem UUID of the filesystem on "mountable".
7462 If the filesystem does not have a UUID, this returns the empty
7464 string.
7465 To find a filesystem from the UUID, use "$g->findfs_uuid".
7467 $g->vg_activate ($activate, \@volgroups);
7469 This command activates or (if "activate" is false) deactivates all
7470 logical volumes in the listed volume groups "volgroups".
7471 This command is the same as running "vgchange -a y|n volgroups..."
7473 Note that if "volgroups" is an empty list then all volume groups
7475 are activated or deactivated.
7476 This function depends on the feature "lvm2". See also
7478 "$g->feature-available".
7479 $g->vg_activate_all ($activate);
7481 This command activates or (if "activate" is false) deactivates all
7482 logical volumes in all volume groups.
7483 This command is the same as running "vgchange -a y|n"
7485 This function depends on the feature "lvm2". See also
7487 "$g->feature-available".
7488 $g->vgchange_uuid ($vg);
7490 Generate a new random UUID for the volume group "vg".
7491 This function depends on the feature "lvm2". See also
7493 "$g->feature-available".
7494 $g->vgchange_uuid_all ();
7496 Generate new random UUIDs for all volume groups.
7497 This function depends on the feature "lvm2". See also
7499 "$g->feature-available".
7500 $g->vgcreate ($volgroup, \@physvols);
7502 This creates an LVM volume group called "volgroup" from the non-
7503 empty list of physical volumes "physvols".
7504 This function depends on the feature "lvm2". See also
7506 "$g->feature-available".
7507 @uuids = $g->vglvuuids ($vgname);
7509 Given a VG called "vgname", this returns the UUIDs of all the
7510 logical volumes created in this volume group.
7511 You can use this along with "$g->lvs" and "$g->lvuuid" calls to
7513 associate logical volumes and volume groups.
7514 See also "$g->vgpvuuids".
7516 $metadata = $g->vgmeta ($vgname);
7518 "vgname" is an LVM volume group. This command examines the volume
7519 group and returns its metadata.
7520 Note that the metadata is an internal structure used by LVM,
7522 subject to change at any time, and is provided for information
7523 only.
7524 This function depends on the feature "lvm2". See also
7526 "$g->feature-available".
7527 @uuids = $g->vgpvuuids ($vgname);
7529 Given a VG called "vgname", this returns the UUIDs of all the
7530 physical volumes that this volume group resides on.
7531 You can use this along with "$g->pvs" and "$g->pvuuid" calls to
7533 associate physical volumes and volume groups.
7534 See also "$g->vglvuuids".
7536 $g->vgremove ($vgname);
7538 Remove an LVM volume group "vgname", (for example "VG").
7539 This also forcibly removes all logical volumes in the volume group
7541 (if any).
7542 This function depends on the feature "lvm2". See also
7544 "$g->feature-available".
7545 $g->vgrename ($volgroup, $newvolgroup);
7547 Rename a volume group "volgroup" with the new name "newvolgroup".
7548 @volgroups = $g->vgs ();
7550 List all the volumes groups detected. This is the equivalent of
7551 the vgs(8) command.
7552 This returns a list of just the volume group names that were
7554 detected (eg. "VolGroup00").
7555 See also "$g->vgs_full".
7557 This function depends on the feature "lvm2". See also
7559 "$g->feature-available".
7560 @volgroups = $g->vgs_full ();
7562 List all the volumes groups detected. This is the equivalent of
7563 the vgs(8) command. The "full" version includes all fields.
7564 This function depends on the feature "lvm2". See also
7566 "$g->feature-available".
7567 $g->vgscan ();
7569 This rescans all block devices and rebuilds the list of LVM
7570 physical volumes, volume groups and logical volumes.
7571 This function is deprecated. In new code, use the "lvm_scan" call
7573 instead.
7574 Deprecated functions will not be removed from the API, but the fact
7576 that they are deprecated indicates that there are problems with
7577 correct use of these functions.
7578 $uuid = $g->vguuid ($vgname);
7580 This command returns the UUID of the LVM VG named "vgname".
7581 $g->wait_ready ();
7583 This function is a no op.
7584 In versions of the API < 1.0.71 you had to call this function just
7586 after calling "$g->launch" to wait for the launch to complete.
7587 However this is no longer necessary because "$g->launch" now does
7588 the waiting.
7589 If you see any calls to this function in code then you can just
7591 remove them, unless you want to retain compatibility with older
7592 versions of the API.
7593 This function is deprecated. There is no replacement. Consult the
7595 API documentation in guestfs(3) for further information.
7596 Deprecated functions will not be removed from the API, but the fact
7598 that they are deprecated indicates that there are problems with
7599 correct use of these functions.
7600 $chars = $g->wc_c ($path);
7602 This command counts the characters in a file, using the "wc -c"
7603 external command.
7604 $lines = $g->wc_l ($path);
7606 This command counts the lines in a file, using the "wc -l" external
7607 command.
7608 $words = $g->wc_w ($path);
7610 This command counts the words in a file, using the "wc -w" external
7611 command.
7612 $g->wipefs ($device);
7614 This command erases filesystem or RAID signatures from the
7615 specified "device" to make the filesystem invisible to libblkid.
7616 This does not erase the filesystem itself nor any other data from
7618 the "device".
7619 Compare with "$g->zero" which zeroes the first few blocks of a
7621 device.
7622 This function depends on the feature "wipefs". See also
7624 "$g->feature-available".
7625 $g->write ($path, $content);
7627 This call creates a file called "path". The content of the file is
7628 the string "content" (which can contain any 8 bit data).
7629 See also "$g->write_append".
7631 $g->write_append ($path, $content);
7633 This call appends "content" to the end of file "path". If "path"
7634 does not exist, then a new file is created.
7635 See also "$g->write".
7637 $g->write_file ($path, $content, $size);
7639 This call creates a file called "path". The contents of the file
7640 is the string "content" (which can contain any 8 bit data), with
7641 length "size".
7642 As a special case, if "size" is 0 then the length is calculated
7644 using "strlen" (so in this case the content cannot contain embedded
7645 ASCII NULs).
7646 NB. Owing to a bug, writing content containing ASCII NUL characters
7648 does not work, even if the length is specified.
7649 Because of the message protocol, there is a transfer limit of
7651 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7652 guestfs(3).
7653 This function is deprecated. In new code, use the "write" call
7655 instead.
7656 Deprecated functions will not be removed from the API, but the fact
7658 that they are deprecated indicates that there are problems with
7659 correct use of these functions.
7660 $g->xfs_admin ($device [, extunwritten => $extunwritten] [, imgfile =>
7662 $imgfile] [, v2log => $v2log] [, projid32bit => $projid32bit] [,
7663 lazycounter => $lazycounter] [, label => $label] [, uuid => $uuid]);
7664 Change the parameters of the XFS filesystem on "device".
7665 Devices that are mounted cannot be modified. Administrators must
7667 unmount filesystems before this call can modify parameters.
7668 Some of the parameters of a mounted filesystem can be examined and
7670 modified using the "$g->xfs_info" and "$g->xfs_growfs" calls.
7671 Beginning with XFS version 5, it is no longer possible to modify
7673 the lazy-counters setting (ie. "lazycounter" parameter has no
7674 effect).
7675 This function depends on the feature "xfs". See also
7677 "$g->feature-available".
7678 $g->xfs_growfs ($path [, datasec => $datasec] [, logsec => $logsec] [,
7680 rtsec => $rtsec] [, datasize => $datasize] [, logsize => $logsize] [,
7681 rtsize => $rtsize] [, rtextsize => $rtextsize] [, maxpct => $maxpct]);
7682 Grow the XFS filesystem mounted at "path".
7683 The returned struct contains geometry information. Missing fields
7685 are returned as -1 (for numeric fields) or empty string.
7686 This function depends on the feature "xfs". See also
7688 "$g->feature-available".
7689 %info = $g->xfs_info ($pathordevice);
7691 "pathordevice" is a mounted XFS filesystem or a device containing
7692 an XFS filesystem. This command returns the geometry of the
7693 filesystem.
7694 The returned struct contains geometry information. Missing fields
7696 are returned as -1 (for numeric fields) or empty string.
7697 This function depends on the feature "xfs". See also
7699 "$g->feature-available".
7700 $status = $g->xfs_repair ($device [, forcelogzero => $forcelogzero] [,
7702 nomodify => $nomodify] [, noprefetch => $noprefetch] [, forcegeometry
7703 => $forcegeometry] [, maxmem => $maxmem] [, ihashsize => $ihashsize] [,
7704 bhashsize => $bhashsize] [, agstride => $agstride] [, logdev =>
7705 $logdev] [, rtdev => $rtdev]);
7706 Repair corrupt or damaged XFS filesystem on "device".
7707 The filesystem is specified using the "device" argument which
7709 should be the device name of the disk partition or volume
7710 containing the filesystem. If given the name of a block device,
7711 "xfs_repair" will attempt to find the raw device associated with
7712 the specified block device and will use the raw device instead.
7713 Regardless, the filesystem to be repaired must be unmounted,
7715 otherwise, the resulting filesystem may be inconsistent or corrupt.
7716 The returned status indicates whether filesystem corruption was
7718 detected (returns 1) or was not detected (returns 0).
7719 This function depends on the feature "xfs". See also
7721 "$g->feature-available".
7722 $g->yara_destroy ();
7724 Destroy previously loaded Yara rules in order to free libguestfs
7725 resources.
7726 This function depends on the feature "libyara". See also
7728 "$g->feature-available".
7729 $g->yara_load ($filename);
7731 Upload a set of Yara rules from local file filename.
7732 Yara rules allow to categorize files based on textual or binary
7734 patterns within their content. See "$g->yara_scan" to see how to
7735 scan files with the loaded rules.
7736 Rules can be in binary format, as when compiled with yarac command,
7738 or in source code format. In the latter case, the rules will be
7739 first compiled and then loaded.
7740 Rules in source code format cannot include external files. In such
7742 cases, it is recommended to compile them first.
7743 Previously loaded rules will be destroyed.
7745 This function depends on the feature "libyara". See also
7747 "$g->feature-available".
7748 @detections = $g->yara_scan ($path);
7750 Scan a file with the previously loaded Yara rules.
7751 For each matching rule, a "yara_detection" structure is returned.
7753 The "yara_detection" structure contains the following fields.
7755 "yara_name"
7757 Path of the file matching a Yara rule.
7758 "yara_rule"
7760 Identifier of the Yara rule which matched against the given
7761 file.
7762 This function depends on the feature "libyara". See also
7764 "$g->feature-available".
7765 @lines = $g->zegrep ($regex, $path);
7767 This calls the external "zegrep" program and returns the matching
7768 lines.
7769 Because of the message protocol, there is a transfer limit of
7771 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7772 guestfs(3).
7773 This function is deprecated. In new code, use the "grep" call
7775 instead.
7776 Deprecated functions will not be removed from the API, but the fact
7778 that they are deprecated indicates that there are problems with
7779 correct use of these functions.
7780 @lines = $g->zegrepi ($regex, $path);
7782 This calls the external "zegrep -i" program and returns the
7783 matching lines.
7784 Because of the message protocol, there is a transfer limit of
7786 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7787 guestfs(3).
7788 This function is deprecated. In new code, use the "grep" call
7790 instead.
7791 Deprecated functions will not be removed from the API, but the fact
7793 that they are deprecated indicates that there are problems with
7794 correct use of these functions.
7795 $g->zero ($device);
7797 This command writes zeroes over the first few blocks of "device".
7798 How many blocks are zeroed isn't specified (but it’s not enough to
7800 securely wipe the device). It should be sufficient to remove any
7801 partition tables, filesystem superblocks and so on.
7802 If blocks are already zero, then this command avoids writing
7804 zeroes. This prevents the underlying device from becoming non-
7805 sparse or growing unnecessarily.
7806 See also: "$g->zero_device", "$g->scrub_device",
7808 "$g->is_zero_device"
7809 $g->zero_device ($device);
7811 This command writes zeroes over the entire "device". Compare with
7812 "$g->zero" which just zeroes the first few blocks of a device.
7813 If blocks are already zero, then this command avoids writing
7815 zeroes. This prevents the underlying device from becoming non-
7816 sparse or growing unnecessarily.
7817 $g->zero_free_space ($directory);
7819 Zero the free space in the filesystem mounted on directory. The
7820 filesystem must be mounted read-write.
7821 The filesystem contents are not affected, but any free space in the
7823 filesystem is freed.
7824 Free space is not "trimmed". You may want to call "$g->fstrim"
7826 either as an alternative to this, or after calling this, depending
7827 on your requirements.
7828 $g->zerofree ($device);
7830 This runs the zerofree program on "device". This program claims to
7831 zero unused inodes and disk blocks on an ext2/3 filesystem, thus
7832 making it possible to compress the filesystem more effectively.
7833 You should not run this program if the filesystem is mounted.
7835 It is possible that using this program can damage the filesystem or
7837 data on the filesystem.
7838 This function depends on the feature "zerofree". See also
7840 "$g->feature-available".
7841 @lines = $g->zfgrep ($pattern, $path);
7843 This calls the external "zfgrep" program and returns the matching
7844 lines.
7845 Because of the message protocol, there is a transfer limit of
7847 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7848 guestfs(3).
7849 This function is deprecated. In new code, use the "grep" call
7851 instead.
7852 Deprecated functions will not be removed from the API, but the fact
7854 that they are deprecated indicates that there are problems with
7855 correct use of these functions.
7856 @lines = $g->zfgrepi ($pattern, $path);
7858 This calls the external "zfgrep -i" program and returns the
7859 matching lines.
7860 Because of the message protocol, there is a transfer limit of
7862 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7863 guestfs(3).
7864 This function is deprecated. In new code, use the "grep" call
7866 instead.
7867 Deprecated functions will not be removed from the API, but the fact
7869 that they are deprecated indicates that there are problems with
7870 correct use of these functions.
7871 $description = $g->zfile ($meth, $path);
7873 This command runs file(1) after first decompressing "path" using
7874 "meth".
7875 "meth" must be one of "gzip", "compress" or "bzip2".
7877 Since 1.0.63, use "$g->file" instead which can now process
7879 compressed files.
7880 This function is deprecated. In new code, use the "file" call
7882 instead.
7883 Deprecated functions will not be removed from the API, but the fact
7885 that they are deprecated indicates that there are problems with
7886 correct use of these functions.
7887 @lines = $g->zgrep ($regex, $path);
7889 This calls the external zgrep(1) program and returns the matching
7890 lines.
7891 Because of the message protocol, there is a transfer limit of
7893 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7894 guestfs(3).
7895 This function is deprecated. In new code, use the "grep" call
7897 instead.
7898 Deprecated functions will not be removed from the API, but the fact
7900 that they are deprecated indicates that there are problems with
7901 correct use of these functions.
7902 @lines = $g->zgrepi ($regex, $path);
7904 This calls the external "zgrep -i" program and returns the matching
7905 lines.
7906 Because of the message protocol, there is a transfer limit of
7908 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7909 guestfs(3).
7910 This function is deprecated. In new code, use the "grep" call
7912 instead.
7913 Deprecated functions will not be removed from the API, but the fact
7915 that they are deprecated indicates that there are problems with
7916 correct use of these functions.
7917
7919 From time to time we add new libguestfs APIs. Also some libguestfs
7920 APIs won't be available in all builds of libguestfs (the Fedora build
7921 is full-featured, but other builds may disable features). How do you
7922 test whether the APIs that your Perl program needs are available in the
7923 version of "Sys::Guestfs" that you are using?
7924 To test if a particular function is available in the "Sys::Guestfs"
7926 class, use the ordinary Perl UNIVERSAL method can(METHOD) (see
7927 perlobj(1)). For example:
7928 use Sys::Guestfs;
7930 if (defined (Sys::Guestfs->can ("set_verbose"))) {
7931 print "\$g->set_verbose is available\n";
7932 }
7933 To test if particular features are supported by the current build, use
7935 the "feature_available" method like the example below. Note that the
7936 appliance must be launched first.
7937 $g->feature_available ( ["augeas"] );
7939 For further discussion on this topic, refer to "AVAILABILITY" in
7941 guestfs(3).
7942
7944 The handle returned from "new" is a hash reference. The hash normally
7945 contains some elements:
7946 {
7948 _g => [private data used by libguestfs],
7949 _flags => [flags provided when creating the handle]
7950 }
7951 Callers can add other elements to this hash to store data for their own
7953 purposes. The data lasts for the lifetime of the handle.
7954 Any fields whose names begin with an underscore are reserved for
7956 private use by libguestfs. We may add more in future.
7957 It is recommended that callers prefix the name of their field(s) with
7959 some unique string, to avoid conflicts with other users.
7960
7962 Copyright (C) 2009-2023 Red Hat Inc.
7963
7965 Please see the file COPYING.LIB for the full license.
7966
7968 guestfs(3), guestfish(1), <http://libguestfs.org>.
7969perl v5.38.2 2023-12-09 Sys::Guestfs(3pm)