1Sys::Guestfs(3) User Contributed Perl Documentation Sys::Guestfs(3)
2
6 Sys::Guestfs - Perl bindings for libguestfs
7
9 use Sys::Guestfs;
10 my $g = Sys::Guestfs->new ();
12 $g->add_drive_opts ('guest.img', format => 'raw');
13 $g->launch ();
14 $g->mount ('/dev/sda1', '/');
15 $g->touch ('/hello');
16 $g->shutdown ();
17 $g->close ();
18
20 The "Sys::Guestfs" module provides a Perl XS binding to the libguestfs
21 API for examining and modifying virtual machine disk images.
22 Amongst the things this is good for: making batch configuration changes
24 to guests, getting disk used/free statistics (see also: virt-df),
25 migrating between virtualization systems (see also: virt-p2v),
26 performing partial backups, performing partial guest clones, cloning
27 guests and changing registry/UUID/hostname info, and much else besides.
28 Libguestfs uses Linux kernel and qemu code, and can access any type of
30 guest filesystem that Linux and qemu can, including but not limited to:
31 ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
32 schemes, qcow, qcow2, vmdk.
33 Libguestfs provides ways to enumerate guest storage (eg. partitions,
35 LVs, what filesystem is in each LV, etc.). It can also run commands in
36 the context of the guest. Also you can access filesystems over FUSE.
37
39 All errors turn into calls to "croak" (see Carp(3)).
40 The error string from libguestfs is directly available from $@. Use
42 the "last_errno" method if you want to get the errno.
43
45 $g = Sys::Guestfs->new ([environment => 0,] [close_on_exit => 0]);
46 Create a new guestfs handle.
47 If the optional argument "environment" is false, then the
49 "GUESTFS_CREATE_NO_ENVIRONMENT" flag is set.
50 If the optional argument "close_on_exit" is false, then the
52 "GUESTFS_CREATE_NO_CLOSE_ON_EXIT" flag is set.
53 $g->close ();
55 Explicitly close the guestfs handle.
56 Note: You should not usually call this function. The handle will
58 be closed implicitly when its reference count goes to zero (eg.
59 when it goes out of scope or the program ends). This call is only
60 required in some exceptional cases, such as where the program may
61 contain cached references to the handle 'somewhere' and you really
62 have to have the close happen right away. After calling "close"
63 the program must not call any method (including "close") on the
64 handle (but the implicit call to "DESTROY" that happens when the
65 final reference is cleaned up is OK).
66 $Sys::Guestfs::EVENT_CLOSE
68 See "GUESTFS_EVENT_CLOSE" in guestfs(3).
69 $Sys::Guestfs::EVENT_SUBPROCESS_QUIT
71 See "GUESTFS_EVENT_SUBPROCESS_QUIT" in guestfs(3).
72 $Sys::Guestfs::EVENT_LAUNCH_DONE
74 See "GUESTFS_EVENT_LAUNCH_DONE" in guestfs(3).
75 $Sys::Guestfs::EVENT_PROGRESS
77 See "GUESTFS_EVENT_PROGRESS" in guestfs(3).
78 $Sys::Guestfs::EVENT_APPLIANCE
80 See "GUESTFS_EVENT_APPLIANCE" in guestfs(3).
81 $Sys::Guestfs::EVENT_LIBRARY
83 See "GUESTFS_EVENT_LIBRARY" in guestfs(3).
84 $Sys::Guestfs::EVENT_TRACE
86 See "GUESTFS_EVENT_TRACE" in guestfs(3).
87 $Sys::Guestfs::EVENT_ENTER
89 See "GUESTFS_EVENT_ENTER" in guestfs(3).
90 $Sys::Guestfs::EVENT_LIBVIRT_AUTH
92 See "GUESTFS_EVENT_LIBVIRT_AUTH" in guestfs(3).
93 $Sys::Guestfs::EVENT_WARNING
95 See "GUESTFS_EVENT_WARNING" in guestfs(3).
96 $Sys::Guestfs::EVENT_ALL
98 See "GUESTFS_EVENT_ALL" in guestfs(3).
99 $event_handle = $g->set_event_callback (\&cb, $event_bitmask);
101 Register "cb" as a callback function for all of the events in
102 $event_bitmask (one or more "$Sys::Guestfs::EVENT_*" flags
103 logically or'd together).
104 This function returns an event handle which can be used to delete
106 the callback using "delete_event_callback".
107 The callback function receives 4 parameters:
109 &cb ($event, $event_handle, $buf, $array)
111 $event
113 The event which happened (equal to one of
114 "$Sys::Guestfs::EVENT_*").
115 $event_handle
117 The event handle.
118 $buf
120 For some event types, this is a message buffer (ie. a string).
121 $array
123 For some event types (notably progress events), this is an
124 array of integers.
125 You should carefully read the documentation for
127 "guestfs_set_event_callback" in guestfs(3) before using this
128 function.
129 $g->delete_event_callback ($event_handle);
131 This removes the callback which was previously registered using
132 "set_event_callback".
133 $str = Sys::Guestfs::event_to_string ($events);
135 $events is either a single event or a bitmask of events. This
136 returns a printable string, useful for debugging.
137 Note that this is a class function, not a method.
139 $errnum = $g->last_errno ();
141 This returns the last error number (errno) that happened on the
142 handle $g.
143 If successful, an errno integer not equal to zero is returned.
145 If no error number is available, this returns 0. See
147 "guestfs_last_errno" in guestfs(3) for more details of why this can
148 happen.
149 You can use the standard Perl module Errno(3) to compare the
151 numeric error returned from this call with symbolic errnos:
152 $g->mkdir ("/foo");
154 if ($g->last_errno() == Errno::EEXIST()) {
155 # mkdir failed because the directory exists already.
156 }
157 $g->acl_delete_def_file ($dir);
159 This function deletes the default POSIX Access Control List (ACL)
160 attached to directory "dir".
161 This function depends on the feature "acl". See also
163 "$g->feature-available".
164 $acl = $g->acl_get_file ($path, $acltype);
166 This function returns the POSIX Access Control List (ACL) attached
167 to "path". The ACL is returned in "long text form" (see acl(5)).
168 The "acltype" parameter may be:
170 "access"
172 Return the ordinary (access) ACL for any file, directory or
173 other filesystem object.
174 "default"
176 Return the default ACL. Normally this only makes sense if
177 "path" is a directory.
178 This function depends on the feature "acl". See also
180 "$g->feature-available".
181 $g->acl_set_file ($path, $acltype, $acl);
183 This function sets the POSIX Access Control List (ACL) attached to
184 "path".
185 The "acltype" parameter may be:
187 "access"
189 Set the ordinary (access) ACL for any file, directory or other
190 filesystem object.
191 "default"
193 Set the default ACL. Normally this only makes sense if "path"
194 is a directory.
195 The "acl" parameter is the new ACL in either "long text form" or
197 "short text form" (see acl(5)). The new ACL completely replaces
198 any previous ACL on the file. The ACL must contain the full Unix
199 permissions (eg. "u::rwx,g::rx,o::rx").
200 If you are specifying individual users or groups, then the mask
202 field is also required (eg. "m::rwx"), followed by the "u:ID:..."
203 and/or "g:ID:..." field(s). A full ACL string might therefore look
204 like this:
205 u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx
207 \ Unix permissions / \mask/ \ ACL /
208 You should use numeric UIDs and GIDs. To map usernames and
210 groupnames to the correct numeric ID in the context of the guest,
211 use the Augeas functions (see "$g->aug_init").
212 This function depends on the feature "acl". See also
214 "$g->feature-available".
215 $g->add_cdrom ($filename);
217 This function adds a virtual CD-ROM disk image to the guest.
218 The image is added as read-only drive, so this function is
220 equivalent of "$g->add_drive_ro".
221 This function is deprecated. In new code, use the "add_drive_ro"
223 call instead.
224 Deprecated functions will not be removed from the API, but the fact
226 that they are deprecated indicates that there are problems with
227 correct use of these functions.
228 $nrdisks = $g->add_domain ($dom [, libvirturi => $libvirturi] [,
230 readonly => $readonly] [, iface => $iface] [, live => $live] [,
231 allowuuid => $allowuuid] [, readonlydisk => $readonlydisk] [, cachemode
232 => $cachemode] [, discard => $discard] [, copyonread => $copyonread]);
233 This function adds the disk(s) attached to the named libvirt domain
234 "dom". It works by connecting to libvirt, requesting the domain
235 and domain XML from libvirt, parsing it for disks, and calling
236 "$g->add_drive_opts" on each one.
237 The number of disks added is returned. This operation is atomic:
239 if an error is returned, then no disks are added.
240 This function does some minimal checks to make sure the libvirt
242 domain is not running (unless "readonly" is true). In a future
243 version we will try to acquire the libvirt lock on each disk.
244 Disks must be accessible locally. This often means that adding
246 disks from a remote libvirt connection (see
247 <https://libvirt.org/remote.html>) will fail unless those disks are
248 accessible via the same device path locally too.
249 The optional "libvirturi" parameter sets the libvirt URI (see
251 <https://libvirt.org/uri.html>). If this is not set then we
252 connect to the default libvirt URI (or one set through an
253 environment variable, see the libvirt documentation for full
254 details).
255 The optional "live" flag 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
2724 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 The environment variable "XDG_RUNTIME_DIR" controls the default
2731 value: If "XDG_RUNTIME_DIR" is set, then that is the default. Else
2732 /tmp is the default.
2733 $state = $g->get_state ();
2735 This returns the current state as an opaque integer. This is only
2736 useful for printing debug and internal error messages.
2737 For more information on states, see guestfs(3).
2739 $tmpdir = $g->get_tmpdir ();
2741 Get the directory used by the handle to store temporary files.
2742 $trace = $g->get_trace ();
2744 Return the command trace flag.
2745 $mask = $g->get_umask ();
2747 Return the current umask. By default the umask is 022 unless it
2748 has been set by calling "$g->umask".
2749 $verbose = $g->get_verbose ();
2751 This returns the verbose messages flag.
2752 $context = $g->getcon ();
2754 This gets the SELinux security context of the daemon.
2755 See the documentation about SELINUX in guestfs(3), and "$g->setcon"
2757 This function depends on the feature "selinux". See also
2759 "$g->feature-available".
2760 This function is deprecated. In new code, use the
2762 "selinux_relabel" call instead.
2763 Deprecated functions will not be removed from the API, but the fact
2765 that they are deprecated indicates that there are problems with
2766 correct use of these functions.
2767 $xattr = $g->getxattr ($path, $name);
2769 Get a single extended attribute from file "path" named "name".
2770 This call follows symlinks. If you want to lookup an extended
2771 attribute for the symlink itself, use "$g->lgetxattr".
2772 Normally it is better to get all extended attributes from a file in
2774 one go by calling "$g->getxattrs". However some Linux filesystem
2775 implementations are buggy and do not provide a way to list out
2776 attributes. For these filesystems (notably ntfs-3g) you have to
2777 know the names of the extended attributes you want in advance and
2778 call this function.
2779 Extended attribute values are blobs of binary data. If there is no
2781 extended attribute named "name", this returns an error.
2782 See also: "$g->getxattrs", "$g->lgetxattr", attr(5).
2784 This function depends on the feature "linuxxattrs". See also
2786 "$g->feature-available".
2787 @xattrs = $g->getxattrs ($path);
2789 This call lists the extended attributes of the file or directory
2790 "path".
2791 At the system call level, this is a combination of the listxattr(2)
2793 and getxattr(2) calls.
2794 See also: "$g->lgetxattrs", attr(5).
2796 This function depends on the feature "linuxxattrs". See also
2798 "$g->feature-available".
2799 @paths = $g->glob_expand ($pattern [, directoryslash =>
2801 $directoryslash]);
2802 This command searches for all the pathnames matching "pattern"
2803 according to the wildcard expansion rules used by the shell.
2804 If no paths match, then this returns an empty list (note: not an
2806 error).
2807 It is just a wrapper around the C glob(3) function with flags
2809 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
2810 "directoryslash" controls whether use the "GLOB_MARK" flag for
2812 glob(3), and it defaults to true. It can be explicitly set as off
2813 to return no trailing slashes in filenames of directories.
2814 Notice that there is no equivalent command for expanding a device
2816 name (eg. /dev/sd*). Use "$g->list_devices", "$g->list_partitions"
2817 etc functions instead.
2818 @paths = $g->glob_expand_opts ($pattern [, directoryslash =>
2820 $directoryslash]);
2821 This is an alias of "glob_expand".
2822 @lines = $g->grep ($regex, $path [, extended => $extended] [, fixed =>
2824 $fixed] [, insensitive => $insensitive] [, compressed => $compressed]);
2825 This calls the external grep(1) program and returns the matching
2826 lines.
2827 The optional flags are:
2829 "extended"
2831 Use extended regular expressions. This is the same as using
2832 the -E flag.
2833 "fixed"
2835 Match fixed (don't use regular expressions). This is the same
2836 as using the -F flag.
2837 "insensitive"
2839 Match case-insensitive. This is the same as using the -i flag.
2840 "compressed"
2842 Use zgrep(1) instead of grep(1). This allows the input to be
2843 compress- or gzip-compressed.
2844 Because of the message protocol, there is a transfer limit of
2846 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2847 guestfs(3).
2848 @lines = $g->grep_opts ($regex, $path [, extended => $extended] [,
2850 fixed => $fixed] [, insensitive => $insensitive] [, compressed =>
2851 $compressed]);
2852 This is an alias of "grep".
2853 @lines = $g->grepi ($regex, $path);
2855 This calls the external "grep -i" program and returns the matching
2856 lines.
2857 Because of the message protocol, there is a transfer limit of
2859 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2860 guestfs(3).
2861 This function is deprecated. In new code, use the "grep" call
2863 instead.
2864 Deprecated functions will not be removed from the API, but the fact
2866 that they are deprecated indicates that there are problems with
2867 correct use of these functions.
2868 $g->grub_install ($root, $device);
2870 This command installs GRUB 1 (the Grand Unified Bootloader) on
2871 "device", with the root directory being "root".
2872 Notes:
2874 • There is currently no way in the API to install grub2, which is
2876 used by most modern Linux guests. It is possible to run the
2877 grub2 command from the guest, although see the caveats in
2878 "RUNNING COMMANDS" in guestfs(3).
2879 • This uses grub-install(8) from the host. Unfortunately grub is
2881 not always compatible with itself, so this only works in rather
2882 narrow circumstances. Careful testing with each guest version
2883 is advisable.
2884 • If grub-install reports the error "No suitable drive was found
2886 in the generated device map." it may be that you need to
2887 create a /boot/grub/device.map file first that contains the
2888 mapping between grub device names and Linux device names. It
2889 is usually sufficient to create a file containing:
2890 (hd0) /dev/vda
2892 replacing /dev/vda with the name of the installation device.
2894 This function depends on the feature "grub". See also
2896 "$g->feature-available".
2897 @lines = $g->head ($path);
2899 This command returns up to the first 10 lines of a file as a list
2900 of strings.
2901 Because of the message protocol, there is a transfer limit of
2903 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2904 guestfs(3).
2905 @lines = $g->head_n ($nrlines, $path);
2907 If the parameter "nrlines" is a positive number, this returns the
2908 first "nrlines" lines of the file "path".
2909 If the parameter "nrlines" is a negative number, this returns lines
2911 from the file "path", excluding the last "nrlines" lines.
2912 If the parameter "nrlines" is zero, this returns an empty list.
2914 Because of the message protocol, there is a transfer limit of
2916 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2917 guestfs(3).
2918 $dump = $g->hexdump ($path);
2920 This runs "hexdump -C" on the given "path". The result is the
2921 human-readable, canonical hex dump of the file.
2922 Because of the message protocol, there is a transfer limit of
2924 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2925 guestfs(3).
2926 $g->hivex_close ();
2928 Close the current hivex handle.
2929 This is a wrapper around the hivex(3) call of the same name.
2931 This function depends on the feature "hivex". See also
2933 "$g->feature-available".
2934 $g->hivex_commit ($filename);
2936 Commit (write) changes to the hive.
2937 If the optional filename parameter is null, then the changes are
2939 written back to the same hive that was opened. If this is not null
2940 then they are written to the alternate filename given and the
2941 original hive is left untouched.
2942 This is a wrapper around the hivex(3) call of the same name.
2944 This function depends on the feature "hivex". See also
2946 "$g->feature-available".
2947 $nodeh = $g->hivex_node_add_child ($parent, $name);
2949 Add a child node to "parent" named "name".
2950 This is a wrapper around the hivex(3) call of the same name.
2952 This function depends on the feature "hivex". See also
2954 "$g->feature-available".
2955 @nodehs = $g->hivex_node_children ($nodeh);
2957 Return the list of nodes which are subkeys of "nodeh".
2958 This is a wrapper around the hivex(3) call of the same name.
2960 This function depends on the feature "hivex". See also
2962 "$g->feature-available".
2963 $g->hivex_node_delete_child ($nodeh);
2965 Delete "nodeh", recursively if necessary.
2966 This is a wrapper around the hivex(3) call of the same name.
2968 This function depends on the feature "hivex". See also
2970 "$g->feature-available".
2971 $child = $g->hivex_node_get_child ($nodeh, $name);
2973 Return the child of "nodeh" with the name "name", if it exists.
2974 This can return 0 meaning the name was not found.
2975 This is a wrapper around the hivex(3) call of the same name.
2977 This function depends on the feature "hivex". See also
2979 "$g->feature-available".
2980 $valueh = $g->hivex_node_get_value ($nodeh, $key);
2982 Return the value attached to "nodeh" which has the name "key", if
2983 it exists. This can return 0 meaning the key was not found.
2984 This is a wrapper around the hivex(3) call of the same name.
2986 This function depends on the feature "hivex". See also
2988 "$g->feature-available".
2989 $name = $g->hivex_node_name ($nodeh);
2991 Return the name of "nodeh".
2992 This is a wrapper around the hivex(3) call of the same name.
2994 This function depends on the feature "hivex". See also
2996 "$g->feature-available".
2997 $parent = $g->hivex_node_parent ($nodeh);
2999 Return the parent node of "nodeh".
3000 This is a wrapper around the hivex(3) call of the same name.
3002 This function depends on the feature "hivex". See also
3004 "$g->feature-available".
3005 $g->hivex_node_set_value ($nodeh, $key, $t, $val);
3007 Set or replace a single value under the node "nodeh". The "key" is
3008 the name, "t" is the type, and "val" is the data.
3009 This is a wrapper around the hivex(3) call of the same name.
3011 This function depends on the feature "hivex". See also
3013 "$g->feature-available".
3014 @valuehs = $g->hivex_node_values ($nodeh);
3016 Return the array of (key, datatype, data) tuples attached to
3017 "nodeh".
3018 This is a wrapper around the hivex(3) call of the same name.
3020 This function depends on the feature "hivex". See also
3022 "$g->feature-available".
3023 $g->hivex_open ($filename [, verbose => $verbose] [, debug => $debug]
3025 [, write => $write] [, unsafe => $unsafe]);
3026 Open the Windows Registry hive file named filename. If there was
3027 any previous hivex handle associated with this guestfs session,
3028 then it is closed.
3029 This is a wrapper around the hivex(3) call of the same name.
3031 This function depends on the feature "hivex". See also
3033 "$g->feature-available".
3034 $nodeh = $g->hivex_root ();
3036 Return the root node of the hive.
3037 This is a wrapper around the hivex(3) call of the same name.
3039 This function depends on the feature "hivex". See also
3041 "$g->feature-available".
3042 $key = $g->hivex_value_key ($valueh);
3044 Return the key (name) field of a (key, datatype, data) tuple.
3045 This is a wrapper around the hivex(3) call of the same name.
3047 This function depends on the feature "hivex". See also
3049 "$g->feature-available".
3050 $databuf = $g->hivex_value_string ($valueh);
3052 This calls "$g->hivex_value_value" (which returns the data field
3053 from a hivex value tuple). It then assumes that the field is a
3054 UTF-16LE string and converts the result to UTF-8 (or if this is not
3055 possible, it returns an error).
3056 This is useful for reading strings out of the Windows registry.
3058 However it is not foolproof because the registry is not strongly-
3059 typed and fields can contain arbitrary or unexpected data.
3060 This function depends on the feature "hivex". See also
3062 "$g->feature-available".
3063 $datatype = $g->hivex_value_type ($valueh);
3065 Return the data type field from a (key, datatype, data) tuple.
3066 This is a wrapper around the hivex(3) call of the same name.
3068 This function depends on the feature "hivex". See also
3070 "$g->feature-available".
3071 $databuf = $g->hivex_value_utf8 ($valueh);
3073 This calls "$g->hivex_value_value" (which returns the data field
3074 from a hivex value tuple). It then assumes that the field is a
3075 UTF-16LE string and converts the result to UTF-8 (or if this is not
3076 possible, it returns an error).
3077 This is useful for reading strings out of the Windows registry.
3079 However it is not foolproof because the registry is not strongly-
3080 typed and fields can contain arbitrary or unexpected data.
3081 This function depends on the feature "hivex". See also
3083 "$g->feature-available".
3084 This function is deprecated. In new code, use the
3086 "hivex_value_string" call instead.
3087 Deprecated functions will not be removed from the API, but the fact
3089 that they are deprecated indicates that there are problems with
3090 correct use of these functions.
3091 $databuf = $g->hivex_value_value ($valueh);
3093 Return the data field of a (key, datatype, data) tuple.
3094 This is a wrapper around the hivex(3) call of the same name.
3096 See also: "$g->hivex_value_utf8".
3098 This function depends on the feature "hivex". See also
3100 "$g->feature-available".
3101 $content = $g->initrd_cat ($initrdpath, $filename);
3103 This command unpacks the file filename from the initrd file called
3104 initrdpath. The filename must be given without the initial /
3105 character.
3106 For example, in guestfish you could use the following command to
3108 examine the boot script (usually called /init) contained in a Linux
3109 initrd or initramfs image:
3110 initrd-cat /boot/initrd-<version>.img init
3112 See also "$g->initrd_list".
3114 Because of the message protocol, there is a transfer limit of
3116 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
3117 guestfs(3).
3118 @filenames = $g->initrd_list ($path);
3120 This command lists out files contained in an initrd.
3121 The files are listed without any initial / character. The files
3123 are listed in the order they appear (not necessarily alphabetical).
3124 Directory names are listed as separate items.
3125 Old Linux kernels (2.4 and earlier) used a compressed ext2
3127 filesystem as initrd. We only support the newer initramfs format
3128 (compressed cpio files).
3129 $wd = $g->inotify_add_watch ($path, $mask);
3131 Watch "path" for the events listed in "mask".
3132 Note that if "path" is a directory then events within that
3134 directory are watched, but this does not happen recursively (in
3135 subdirectories).
3136 Note for non-C or non-Linux callers: the inotify events are defined
3138 by the Linux kernel ABI and are listed in
3139 /usr/include/sys/inotify.h.
3140 This function depends on the feature "inotify". See also
3142 "$g->feature-available".
3143 $g->inotify_close ();
3145 This closes the inotify handle which was previously opened by
3146 inotify_init. It removes all watches, throws away any pending
3147 events, and deallocates all resources.
3148 This function depends on the feature "inotify". See also
3150 "$g->feature-available".
3151 @paths = $g->inotify_files ();
3153 This function is a helpful wrapper around "$g->inotify_read" which
3154 just returns a list of pathnames of objects that were touched. The
3155 returned pathnames are sorted and deduplicated.
3156 This function depends on the feature "inotify". See also
3158 "$g->feature-available".
3159 $g->inotify_init ($maxevents);
3161 This command creates a new inotify handle. The inotify subsystem
3162 can be used to notify events which happen to objects in the guest
3163 filesystem.
3164 "maxevents" is the maximum number of events which will be queued up
3166 between calls to "$g->inotify_read" or "$g->inotify_files". If
3167 this is passed as 0, then the kernel (or previously set) default is
3168 used. For Linux 2.6.29 the default was 16384 events. Beyond this
3169 limit, the kernel throws away events, but records the fact that it
3170 threw them away by setting a flag "IN_Q_OVERFLOW" in the returned
3171 structure list (see "$g->inotify_read").
3172 Before any events are generated, you have to add some watches to
3174 the internal watch list. See: "$g->inotify_add_watch" and
3175 "$g->inotify_rm_watch".
3176 Queued up events should be read periodically by calling
3178 "$g->inotify_read" (or "$g->inotify_files" which is just a helpful
3179 wrapper around "$g->inotify_read"). If you don't read the events
3180 out often enough then you risk the internal queue overflowing.
3181 The handle should be closed after use by calling
3183 "$g->inotify_close". This also removes any watches automatically.
3184 See also inotify(7) for an overview of the inotify interface as
3186 exposed by the Linux kernel, which is roughly what we expose via
3187 libguestfs. Note that there is one global inotify handle per
3188 libguestfs instance.
3189 This function depends on the feature "inotify". See also
3191 "$g->feature-available".
3192 @events = $g->inotify_read ();
3194 Return the complete queue of events that have happened since the
3195 previous read call.
3196 If no events have happened, this returns an empty list.
3198 Note: In order to make sure that all events have been read, you
3200 must call this function repeatedly until it returns an empty list.
3201 The reason is that the call will read events up to the maximum
3202 appliance-to-host message size and leave remaining events in the
3203 queue.
3204 This function depends on the feature "inotify". See also
3206 "$g->feature-available".
3207 $g->inotify_rm_watch ($wd);
3209 Remove a previously defined inotify watch. See
3210 "$g->inotify_add_watch".
3211 This function depends on the feature "inotify". See also
3213 "$g->feature-available".
3214 $arch = $g->inspect_get_arch ($root);
3216 This returns the architecture of the inspected operating system.
3217 The possible return values are listed under
3218 "$g->file_architecture".
3219 If the architecture could not be determined, then the string
3221 "unknown" is returned.
3222 Please read "INSPECTION" in guestfs(3) for more details.
3224 $buildid = $g->inspect_get_build_id ($root);
3226 This returns the build ID of the system, or the string "unknown" if
3227 the system does not have a build ID.
3228 For Windows, this gets the build number. Although it is returned
3230 as a string, it is (so far) always a number. See
3231 <https://en.wikipedia.org/wiki/List_of_Microsoft_Windows_versions>
3232 for some possible values.
3233 For Linux, this returns the "BUILD_ID" string from /etc/os-release,
3235 although this is not often used.
3236 Please read "INSPECTION" in guestfs(3) for more details.
3238 $distro = $g->inspect_get_distro ($root);
3240 This returns the distro (distribution) of the inspected operating
3241 system.
3242 Currently defined distros are:
3244 "alpinelinux"
3246 Alpine Linux.
3247 "altlinux"
3249 ALT Linux.
3250 "archlinux"
3252 Arch Linux.
3253 "buildroot"
3255 Buildroot-derived distro, but not one we specifically
3256 recognize.
3257 "centos"
3259 CentOS.
3260 "cirros"
3262 Cirros.
3263 "coreos"
3265 CoreOS.
3266 "debian"
3268 Debian.
3269 "fedora"
3271 Fedora.
3272 "freebsd"
3274 FreeBSD.
3275 "freedos"
3277 FreeDOS.
3278 "frugalware"
3280 Frugalware.
3281 "gentoo"
3283 Gentoo.
3284 "kalilinux"
3286 Kali Linux.
3287 "kylin"
3289 Kylin.
3290 "linuxmint"
3292 Linux Mint.
3293 "mageia"
3295 Mageia.
3296 "mandriva"
3298 Mandriva.
3299 "meego"
3301 MeeGo.
3302 "msdos"
3304 Microsoft DOS.
3305 "neokylin"
3307 NeoKylin.
3308 "netbsd"
3310 NetBSD.
3311 "openbsd"
3313 OpenBSD.
3314 "openmandriva"
3316 OpenMandriva Lx.
3317 "opensuse"
3319 OpenSUSE.
3320 "oraclelinux"
3322 Oracle Linux.
3323 "pardus"
3325 Pardus.
3326 "pldlinux"
3328 PLD Linux.
3329 "redhat-based"
3331 Some Red Hat-derived distro.
3332 "rhel"
3334 Red Hat Enterprise Linux.
3335 "rocky"
3337 Rocky Linux.
3338 "scientificlinux"
3340 Scientific Linux.
3341 "slackware"
3343 Slackware.
3344 "sles"
3346 SuSE Linux Enterprise Server or Desktop.
3347 "suse-based"
3349 Some openSuSE-derived distro.
3350 "ttylinux"
3352 ttylinux.
3353 "ubuntu"
3355 Ubuntu.
3356 "unknown"
3358 The distro could not be determined.
3359 "voidlinux"
3361 Void Linux.
3362 "windows"
3364 Windows does not have distributions. This string is returned
3365 if the OS type is Windows.
3366 Future versions of libguestfs may return other strings here. The
3368 caller should be prepared to handle any string.
3369 Please read "INSPECTION" in guestfs(3) for more details.
3371 %drives = $g->inspect_get_drive_mappings ($root);
3373 This call is useful for Windows which uses a primitive system of
3374 assigning drive letters (like C:\) to partitions. This inspection
3375 API examines the Windows Registry to find out how disks/partitions
3376 are mapped to drive letters, and returns a hash table as in the
3377 example below:
3378 C => /dev/vda2
3380 E => /dev/vdb1
3381 F => /dev/vdc1
3382 Note that keys are drive letters. For Windows, the key is case
3384 insensitive and just contains the drive letter, without the
3385 customary colon separator character.
3386 In future we may support other operating systems that also used
3388 drive letters, but the keys for those might not be case insensitive
3389 and might be longer than 1 character. For example in OS-9, hard
3390 drives were named "h0", "h1" etc.
3391 For Windows guests, currently only hard drive mappings are
3393 returned. Removable disks (eg. DVD-ROMs) are ignored.
3394 For guests that do not use drive mappings, or if the drive mappings
3396 could not be determined, this returns an empty hash table.
3397 Please read "INSPECTION" in guestfs(3) for more details. See also
3399 "$g->inspect_get_mountpoints", "$g->inspect_get_filesystems".
3400 @filesystems = $g->inspect_get_filesystems ($root);
3402 This returns a list of all the filesystems that we think are
3403 associated with this operating system. This includes the root
3404 filesystem, other ordinary filesystems, and non-mounted devices
3405 like swap partitions.
3406 In the case of a multi-boot virtual machine, it is possible for a
3408 filesystem to be shared between operating systems.
3409 Please read "INSPECTION" in guestfs(3) for more details. See also
3411 "$g->inspect_get_mountpoints".
3412 $format = $g->inspect_get_format ($root);
3414 Before libguestfs 1.38, there was some unreliable support for
3415 detecting installer CDs. This API would return:
3416 "installed"
3418 This is an installed operating system.
3419 "installer"
3421 The disk image being inspected is not an installed operating
3422 system, but a bootable install disk, live CD, or similar.
3423 "unknown"
3425 The format of this disk image is not known.
3426 In libguestfs ≥ 1.38, this only returns "installed". Use libosinfo
3428 directly to detect installer CDs.
3429 Please read "INSPECTION" in guestfs(3) for more details.
3431 This function is deprecated. There is no replacement. Consult the
3433 API documentation in guestfs(3) for further information.
3434 Deprecated functions will not be removed from the API, but the fact
3436 that they are deprecated indicates that there are problems with
3437 correct use of these functions.
3438 $hostname = $g->inspect_get_hostname ($root);
3440 This function returns the hostname of the operating system as found
3441 by inspection of the guest’s configuration files.
3442 If the hostname could not be determined, then the string "unknown"
3444 is returned.
3445 Please read "INSPECTION" in guestfs(3) for more details.
3447 $icon = $g->inspect_get_icon ($root [, favicon => $favicon] [,
3449 highquality => $highquality]);
3450 This function returns an icon corresponding to the inspected
3451 operating system. The icon is returned as a buffer containing a
3452 PNG image (re-encoded to PNG if necessary).
3453 If it was not possible to get an icon this function returns a zero-
3455 length (non-NULL) buffer. Callers must check for this case.
3456 Libguestfs will start by looking for a file called /etc/favicon.png
3458 or C:\etc\favicon.png and if it has the correct format, the
3459 contents of this file will be returned. You can disable favicons
3460 by passing the optional "favicon" boolean as false (default is
3461 true).
3462 If finding the favicon fails, then we look in other places in the
3464 guest for a suitable icon.
3465 If the optional "highquality" boolean is true then only high
3467 quality icons are returned, which means only icons of high
3468 resolution with an alpha channel. The default (false) is to return
3469 any icon we can, even if it is of substandard quality.
3470 Notes:
3472 • Unlike most other inspection API calls, the guest’s disks must
3474 be mounted up before you call this, since it needs to read
3475 information from the guest filesystem during the call.
3476 • Security: The icon data comes from the untrusted guest, and
3478 should be treated with caution. PNG files have been known to
3479 contain exploits. Ensure that libpng (or other relevant
3480 libraries) are fully up to date before trying to process or
3481 display the icon.
3482 • The PNG image returned can be any size. It might not be
3484 square. Libguestfs tries to return the largest, highest
3485 quality icon available. The application must scale the icon to
3486 the required size.
3487 • Extracting icons from Windows guests requires the external
3489 wrestool(1) program from the "icoutils" package, and several
3490 programs (bmptopnm(1), pnmtopng(1), pamcut(1)) from the
3491 "netpbm" package. These must be installed separately.
3492 • Operating system icons are usually trademarks. Seek legal
3494 advice before using trademarks in applications.
3495 $major = $g->inspect_get_major_version ($root);
3497 This returns the major version number of the inspected operating
3498 system.
3499 Windows uses a consistent versioning scheme which is not reflected
3501 in the popular public names used by the operating system. Notably
3502 the operating system known as "Windows 7" is really version 6.1
3503 (ie. major = 6, minor = 1). You can find out the real versions
3504 corresponding to releases of Windows by consulting Wikipedia or
3505 MSDN.
3506 If the version could not be determined, then 0 is returned.
3508 Please read "INSPECTION" in guestfs(3) for more details.
3510 $minor = $g->inspect_get_minor_version ($root);
3512 This returns the minor version number of the inspected operating
3513 system.
3514 If the version could not be determined, then 0 is returned.
3516 Please read "INSPECTION" in guestfs(3) for more details. See also
3518 "$g->inspect_get_major_version".
3519 %mountpoints = $g->inspect_get_mountpoints ($root);
3521 This returns a hash of where we think the filesystems associated
3522 with this operating system should be mounted. Callers should note
3523 that this is at best an educated guess made by reading
3524 configuration files such as /etc/fstab. In particular note that
3525 this may return filesystems which are non-existent or not mountable
3526 and callers should be prepared to handle or ignore failures if they
3527 try to mount them.
3528 Each element in the returned hashtable has a key which is the path
3530 of the mountpoint (eg. /boot) and a value which is the filesystem
3531 that would be mounted there (eg. /dev/sda1).
3532 Non-mounted devices such as swap devices are not returned in this
3534 list.
3535 For operating systems like Windows which still use drive letters,
3537 this call will only return an entry for the first drive "mounted
3538 on" /. For information about the mapping of drive letters to
3539 partitions, see "$g->inspect_get_drive_mappings".
3540 Please read "INSPECTION" in guestfs(3) for more details. See also
3542 "$g->inspect_get_filesystems".
3543 $id = $g->inspect_get_osinfo ($root);
3545 This function returns a possible short ID for libosinfo
3546 corresponding to the guest.
3547 Note: The returned ID is only a guess by libguestfs, and nothing
3549 ensures that it actually exists in osinfo-db.
3550 If no ID could not be determined, then the string "unknown" is
3552 returned.
3553 $packageformat = $g->inspect_get_package_format ($root);
3555 This function and "$g->inspect_get_package_management" return the
3556 package format and package management tool used by the inspected
3557 operating system. For example for Fedora these functions would
3558 return "rpm" (package format), and "yum" or "dnf" (package
3559 management).
3560 This returns the string "unknown" if we could not determine the
3562 package format or if the operating system does not have a real
3563 packaging system (eg. Windows).
3564 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
3566 "pkgsrc", "apk", "xbps". Future versions of libguestfs may return
3567 other strings.
3568 Please read "INSPECTION" in guestfs(3) for more details.
3570 $packagemanagement = $g->inspect_get_package_management ($root);
3572 "$g->inspect_get_package_format" and this function return the
3573 package format and package management tool used by the inspected
3574 operating system. For example for Fedora these functions would
3575 return "rpm" (package format), and "yum" or "dnf" (package
3576 management).
3577 This returns the string "unknown" if we could not determine the
3579 package management tool or if the operating system does not have a
3580 real packaging system (eg. Windows).
3581 Possible strings include: "yum", "dnf", "up2date", "apt" (for all
3583 Debian derivatives), "portage", "pisi", "pacman", "urpmi",
3584 "zypper", "apk", "xbps". Future versions of libguestfs may return
3585 other strings.
3586 Please read "INSPECTION" in guestfs(3) for more details.
3588 $product = $g->inspect_get_product_name ($root);
3590 This returns the product name of the inspected operating system.
3591 The product name is generally some freeform string which can be
3592 displayed to the user, but should not be parsed by programs.
3593 If the product name could not be determined, then the string
3595 "unknown" is returned.
3596 Please read "INSPECTION" in guestfs(3) for more details.
3598 $variant = $g->inspect_get_product_variant ($root);
3600 This returns the product variant of the inspected operating system.
3601 For Windows guests, this returns the contents of the Registry key
3603 "HKLM\Software\Microsoft\Windows NT\CurrentVersion"
3604 "InstallationType" which is usually a string such as "Client" or
3605 "Server" (other values are possible). This can be used to
3606 distinguish consumer and enterprise versions of Windows that have
3607 the same version number (for example, Windows 7 and Windows 2008
3608 Server are both version 6.1, but the former is "Client" and the
3609 latter is "Server").
3610 For enterprise Linux guests, in future we intend this to return the
3612 product variant such as "Desktop", "Server" and so on. But this is
3613 not implemented at present.
3614 If the product variant could not be determined, then the string
3616 "unknown" is returned.
3617 Please read "INSPECTION" in guestfs(3) for more details. See also
3619 "$g->inspect_get_product_name", "$g->inspect_get_major_version".
3620 @roots = $g->inspect_get_roots ();
3622 This function is a convenient way to get the list of root devices,
3623 as returned from a previous call to "$g->inspect_os", but without
3624 redoing the whole inspection process.
3625 This returns an empty list if either no root devices were found or
3627 the caller has not called "$g->inspect_os".
3628 Please read "INSPECTION" in guestfs(3) for more details.
3630 $name = $g->inspect_get_type ($root);
3632 This returns the type of the inspected operating system. Currently
3633 defined types are:
3634 "linux"
3636 Any Linux-based operating system.
3637 "windows"
3639 Any Microsoft Windows operating system.
3640 "freebsd"
3642 FreeBSD.
3643 "netbsd"
3645 NetBSD.
3646 "openbsd"
3648 OpenBSD.
3649 "hurd"
3651 GNU/Hurd.
3652 "dos"
3654 MS-DOS, FreeDOS and others.
3655 "minix"
3657 MINIX.
3658 "unknown"
3660 The operating system type could not be determined.
3661 Future versions of libguestfs may return other strings here. The
3663 caller should be prepared to handle any string.
3664 Please read "INSPECTION" in guestfs(3) for more details.
3666 $controlset = $g->inspect_get_windows_current_control_set ($root);
3668 This returns the Windows CurrentControlSet of the inspected guest.
3669 The CurrentControlSet is a registry key name such as
3670 "ControlSet001".
3671 This call assumes that the guest is Windows and that the Registry
3673 could be examined by inspection. If this is not the case then an
3674 error is returned.
3675 Please read "INSPECTION" in guestfs(3) for more details.
3677 $path = $g->inspect_get_windows_software_hive ($root);
3679 This returns the path to the hive (binary Windows Registry file)
3680 corresponding to HKLM\SOFTWARE.
3681 This call assumes that the guest is Windows and that the guest has
3683 a software hive file with the right name. If this is not the case
3684 then an error is returned. This call does not check that the hive
3685 is a valid Windows Registry hive.
3686 You can use "$g->hivex_open" to read or write to the hive.
3688 Please read "INSPECTION" in guestfs(3) for more details.
3690 $path = $g->inspect_get_windows_system_hive ($root);
3692 This returns the path to the hive (binary Windows Registry file)
3693 corresponding to HKLM\SYSTEM.
3694 This call assumes that the guest is Windows and that the guest has
3696 a system hive file with the right name. If this is not the case
3697 then an error is returned. This call does not check that the hive
3698 is a valid Windows Registry hive.
3699 You can use "$g->hivex_open" to read or write to the hive.
3701 Please read "INSPECTION" in guestfs(3) for more details.
3703 $systemroot = $g->inspect_get_windows_systemroot ($root);
3705 This returns the Windows systemroot of the inspected guest. The
3706 systemroot is a directory path such as /WINDOWS.
3707 This call assumes that the guest is Windows and that the systemroot
3709 could be determined by inspection. If this is not the case then an
3710 error is returned.
3711 Please read "INSPECTION" in guestfs(3) for more details.
3713 $live = $g->inspect_is_live ($root);
3715 This is deprecated and always returns "false".
3716 Please read "INSPECTION" in guestfs(3) for more details.
3718 This function is deprecated. There is no replacement. Consult the
3720 API documentation in guestfs(3) for further information.
3721 Deprecated functions will not be removed from the API, but the fact
3723 that they are deprecated indicates that there are problems with
3724 correct use of these functions.
3725 $multipart = $g->inspect_is_multipart ($root);
3727 This is deprecated and always returns "false".
3728 Please read "INSPECTION" in guestfs(3) for more details.
3730 This function is deprecated. There is no replacement. Consult the
3732 API documentation in guestfs(3) for further information.
3733 Deprecated functions will not be removed from the API, but the fact
3735 that they are deprecated indicates that there are problems with
3736 correct use of these functions.
3737 $netinst = $g->inspect_is_netinst ($root);
3739 This is deprecated and always returns "false".
3740 Please read "INSPECTION" in guestfs(3) for more details.
3742 This function is deprecated. There is no replacement. Consult the
3744 API documentation in guestfs(3) for further information.
3745 Deprecated functions will not be removed from the API, but the fact
3747 that they are deprecated indicates that there are problems with
3748 correct use of these functions.
3749 @applications = $g->inspect_list_applications ($root);
3751 Return the list of applications installed in the operating system.
3752 Note: This call works differently from other parts of the
3754 inspection API. You have to call "$g->inspect_os", then
3755 "$g->inspect_get_mountpoints", then mount up the disks, before
3756 calling this. Listing applications is a significantly more
3757 difficult operation which requires access to the full filesystem.
3758 Also note that unlike the other "$g->inspect_get_*" calls which are
3759 just returning data cached in the libguestfs handle, this call
3760 actually reads parts of the mounted filesystems during the call.
3761 This returns an empty list if the inspection code was not able to
3763 determine the list of applications.
3764 The application structure contains the following fields:
3766 "app_name"
3768 The name of the application. For Linux guests, this is the
3769 package name.
3770 "app_display_name"
3772 The display name of the application, sometimes localized to the
3773 install language of the guest operating system.
3774 If unavailable this is returned as an empty string "". Callers
3776 needing to display something can use "app_name" instead.
3777 "app_epoch"
3779 For package managers which use epochs, this contains the epoch
3780 of the package (an integer). If unavailable, this is returned
3781 as 0.
3782 "app_version"
3784 The version string of the application or package. If
3785 unavailable this is returned as an empty string "".
3786 "app_release"
3788 The release string of the application or package, for package
3789 managers that use this. If unavailable this is returned as an
3790 empty string "".
3791 "app_install_path"
3793 The installation path of the application (on operating systems
3794 such as Windows which use installation paths). This path is in
3795 the format used by the guest operating system, it is not a
3796 libguestfs path.
3797 If unavailable this is returned as an empty string "".
3799 "app_trans_path"
3801 The install path translated into a libguestfs path. If
3802 unavailable this is returned as an empty string "".
3803 "app_publisher"
3805 The name of the publisher of the application, for package
3806 managers that use this. If unavailable this is returned as an
3807 empty string "".
3808 "app_url"
3810 The URL (eg. upstream URL) of the application. If unavailable
3811 this is returned as an empty string "".
3812 "app_source_package"
3814 For packaging systems which support this, the name of the
3815 source package. If unavailable this is returned as an empty
3816 string "".
3817 "app_summary"
3819 A short (usually one line) description of the application or
3820 package. If unavailable this is returned as an empty string
3821 "".
3822 "app_description"
3824 A longer description of the application or package. If
3825 unavailable this is returned as an empty string "".
3826 Please read "INSPECTION" in guestfs(3) for more details.
3828 This function is deprecated. In new code, use the
3830 "inspect_list_applications2" call instead.
3831 Deprecated functions will not be removed from the API, but the fact
3833 that they are deprecated indicates that there are problems with
3834 correct use of these functions.
3835 @applications2 = $g->inspect_list_applications2 ($root);
3837 Return the list of applications installed in the operating system.
3838 Note: This call works differently from other parts of the
3840 inspection API. You have to call "$g->inspect_os", then
3841 "$g->inspect_get_mountpoints", then mount up the disks, before
3842 calling this. Listing applications is a significantly more
3843 difficult operation which requires access to the full filesystem.
3844 Also note that unlike the other "$g->inspect_get_*" calls which are
3845 just returning data cached in the libguestfs handle, this call
3846 actually reads parts of the mounted filesystems during the call.
3847 This returns an empty list if the inspection code was not able to
3849 determine the list of applications.
3850 The application structure contains the following fields:
3852 "app2_name"
3854 The name of the application. For Linux guests, this is the
3855 package name.
3856 "app2_display_name"
3858 The display name of the application, sometimes localized to the
3859 install language of the guest operating system.
3860 If unavailable this is returned as an empty string "". Callers
3862 needing to display something can use "app2_name" instead.
3863 "app2_epoch"
3865 For package managers which use epochs, this contains the epoch
3866 of the package (an integer). If unavailable, this is returned
3867 as 0.
3868 "app2_version"
3870 The version string of the application or package. If
3871 unavailable this is returned as an empty string "".
3872 "app2_release"
3874 The release string of the application or package, for package
3875 managers that use this. If unavailable this is returned as an
3876 empty string "".
3877 "app2_arch"
3879 The architecture string of the application or package, for
3880 package managers that use this. If unavailable this is
3881 returned as an empty string "".
3882 "app2_install_path"
3884 The installation path of the application (on operating systems
3885 such as Windows which use installation paths). This path is in
3886 the format used by the guest operating system, it is not a
3887 libguestfs path.
3888 If unavailable this is returned as an empty string "".
3890 "app2_trans_path"
3892 The install path translated into a libguestfs path. If
3893 unavailable this is returned as an empty string "".
3894 "app2_publisher"
3896 The name of the publisher of the application, for package
3897 managers that use this. If unavailable this is returned as an
3898 empty string "".
3899 "app2_url"
3901 The URL (eg. upstream URL) of the application. If unavailable
3902 this is returned as an empty string "".
3903 "app2_source_package"
3905 For packaging systems which support this, the name of the
3906 source package. If unavailable this is returned as an empty
3907 string "".
3908 "app2_summary"
3910 A short (usually one line) description of the application or
3911 package. If unavailable this is returned as an empty string
3912 "".
3913 "app2_description"
3915 A longer description of the application or package. If
3916 unavailable this is returned as an empty string "".
3917 Please read "INSPECTION" in guestfs(3) for more details.
3919 @roots = $g->inspect_os ();
3921 This function uses other libguestfs functions and certain
3922 heuristics to inspect the disk(s) (usually disks belonging to a
3923 virtual machine), looking for operating systems.
3924 The list returned is empty if no operating systems were found.
3926 If one operating system was found, then this returns a list with a
3928 single element, which is the name of the root filesystem of this
3929 operating system. It is also possible for this function to return
3930 a list containing more than one element, indicating a dual-boot or
3931 multi-boot virtual machine, with each element being the root
3932 filesystem of one of the operating systems.
3933 You can pass the root string(s) returned to other
3935 "$g->inspect_get_*" functions in order to query further information
3936 about each operating system, such as the name and version.
3937 This function uses other libguestfs features such as "$g->mount_ro"
3939 and "$g->umount_all" in order to mount and unmount filesystems and
3940 look at the contents. This should be called with no disks
3941 currently mounted. The function may also use Augeas, so any
3942 existing Augeas handle will be closed.
3943 This function cannot decrypt encrypted disks. The caller must do
3945 that first (supplying the necessary keys) if the disk is encrypted.
3946 Please read "INSPECTION" in guestfs(3) for more details.
3948 See also "$g->list_filesystems".
3950 $flag = $g->is_blockdev ($path [, followsymlinks => $followsymlinks]);
3952 This returns "true" if and only if there is a block device with the
3953 given "path" name.
3954 If the optional flag "followsymlinks" is true, then a symlink (or
3956 chain of symlinks) that ends with a block device also causes the
3957 function to return true.
3958 This call only looks at files within the guest filesystem.
3960 Libguestfs partitions and block devices (eg. /dev/sda) cannot be
3961 used as the "path" parameter of this call.
3962 See also "$g->stat".
3964 $flag = $g->is_blockdev_opts ($path [, followsymlinks =>
3966 $followsymlinks]);
3967 This is an alias of "is_blockdev".
3968 $busy = $g->is_busy ();
3970 This always returns false. This function is deprecated with no
3971 replacement. Do not use this function.
3972 For more information on states, see guestfs(3).
3974 $flag = $g->is_chardev ($path [, followsymlinks => $followsymlinks]);
3976 This returns "true" if and only if there is a character device with
3977 the given "path" name.
3978 If the optional flag "followsymlinks" is true, then a symlink (or
3980 chain of symlinks) that ends with a chardev also causes the
3981 function to return true.
3982 See also "$g->stat".
3984 $flag = $g->is_chardev_opts ($path [, followsymlinks =>
3986 $followsymlinks]);
3987 This is an alias of "is_chardev".
3988 $config = $g->is_config ();
3990 This returns true iff this handle is being configured (in the
3991 "CONFIG" state).
3992 For more information on states, see guestfs(3).
3994 $dirflag = $g->is_dir ($path [, followsymlinks => $followsymlinks]);
3996 This returns "true" if and only if there is a directory with the
3997 given "path" name. Note that it returns false for other objects
3998 like files.
3999 If the optional flag "followsymlinks" is true, then a symlink (or
4001 chain of symlinks) that ends with a directory also causes the
4002 function to return true.
4003 See also "$g->stat".
4005 $dirflag = $g->is_dir_opts ($path [, followsymlinks =>
4007 $followsymlinks]);
4008 This is an alias of "is_dir".
4009 $flag = $g->is_fifo ($path [, followsymlinks => $followsymlinks]);
4011 This returns "true" if and only if there is a FIFO (named pipe)
4012 with the given "path" name.
4013 If the optional flag "followsymlinks" is true, then a symlink (or
4015 chain of symlinks) that ends with a FIFO also causes the function
4016 to return true.
4017 See also "$g->stat".
4019 $flag = $g->is_fifo_opts ($path [, followsymlinks => $followsymlinks]);
4021 This is an alias of "is_fifo".
4022 $fileflag = $g->is_file ($path [, followsymlinks => $followsymlinks]);
4024 This returns "true" if and only if there is a regular file with the
4025 given "path" name. Note that it returns false for other objects
4026 like directories.
4027 If the optional flag "followsymlinks" is true, then a symlink (or
4029 chain of symlinks) that ends with a file also causes the function
4030 to return true.
4031 See also "$g->stat".
4033 $fileflag = $g->is_file_opts ($path [, followsymlinks =>
4035 $followsymlinks]);
4036 This is an alias of "is_file".
4037 $launching = $g->is_launching ();
4039 This returns true iff this handle is launching the subprocess (in
4040 the "LAUNCHING" state).
4041 For more information on states, see guestfs(3).
4043 $lvflag = $g->is_lv ($mountable);
4045 This command tests whether "mountable" is a logical volume, and
4046 returns true iff this is the case.
4047 $ready = $g->is_ready ();
4049 This returns true iff this handle is ready to accept commands (in
4050 the "READY" state).
4051 For more information on states, see guestfs(3).
4053 $flag = $g->is_socket ($path [, followsymlinks => $followsymlinks]);
4055 This returns "true" if and only if there is a Unix domain socket
4056 with the given "path" name.
4057 If the optional flag "followsymlinks" is true, then a symlink (or
4059 chain of symlinks) that ends with a socket also causes the function
4060 to return true.
4061 See also "$g->stat".
4063 $flag = $g->is_socket_opts ($path [, followsymlinks =>
4065 $followsymlinks]);
4066 This is an alias of "is_socket".
4067 $flag = $g->is_symlink ($path);
4069 This returns "true" if and only if there is a symbolic link with
4070 the given "path" name.
4071 See also "$g->stat".
4073 $flag = $g->is_whole_device ($device);
4075 This returns "true" if and only if "device" refers to a whole block
4076 device. That is, not a partition or a logical device.
4077 $zeroflag = $g->is_zero ($path);
4079 This returns true iff the file exists and the file is empty or it
4080 contains all zero bytes.
4081 $zeroflag = $g->is_zero_device ($device);
4083 This returns true iff the device exists and contains all zero
4084 bytes.
4085 Note that for large devices this can take a long time to run.
4087 %isodata = $g->isoinfo ($isofile);
4089 This is the same as "$g->isoinfo_device" except that it works for
4090 an ISO file located inside some other mounted filesystem. Note
4091 that in the common case where you have added an ISO file as a
4092 libguestfs device, you would not call this. Instead you would call
4093 "$g->isoinfo_device".
4094 %isodata = $g->isoinfo_device ($device);
4096 "device" is an ISO device. This returns a struct of information
4097 read from the primary volume descriptor (the ISO equivalent of the
4098 superblock) of the device.
4099 Usually it is more efficient to use the isoinfo(1) command with the
4101 -d option on the host to analyze ISO files, instead of going
4102 through libguestfs.
4103 For information on the primary volume descriptor fields, see
4105 <https://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor>
4106 $g->journal_close ();
4108 Close the journal handle.
4109 This function depends on the feature "journal". See also
4111 "$g->feature-available".
4112 @fields = $g->journal_get ();
4114 Read the current journal entry. This returns all the fields in the
4115 journal as a set of "(attrname, attrval)" pairs. The "attrname" is
4116 the field name (a string).
4117 The "attrval" is the field value (a binary blob, often but not
4119 always a string). Please note that "attrval" is a byte array, not
4120 a \0-terminated C string.
4121 The length of data may be truncated to the data threshold (see:
4123 "$g->journal_set_data_threshold",
4124 "$g->journal_get_data_threshold").
4125 If you set the data threshold to unlimited (0) then this call can
4127 read a journal entry of any size, ie. it is not limited by the
4128 libguestfs protocol.
4129 This function depends on the feature "journal". See also
4131 "$g->feature-available".
4132 $threshold = $g->journal_get_data_threshold ();
4134 Get the current data threshold for reading journal entries. This
4135 is a hint to the journal that it may truncate data fields to this
4136 size when reading them (note also that it may not truncate them).
4137 If this returns 0, then the threshold is unlimited.
4138 See also "$g->journal_set_data_threshold".
4140 This function depends on the feature "journal". See also
4142 "$g->feature-available".
4143 $usec = $g->journal_get_realtime_usec ();
4145 Get the realtime (wallclock) timestamp of the current journal
4146 entry.
4147 This function depends on the feature "journal". See also
4149 "$g->feature-available".
4150 $more = $g->journal_next ();
4152 Move to the next journal entry. You have to call this at least
4153 once after opening the handle before you are able to read data.
4154 The returned boolean tells you if there are any more journal
4156 records to read. "true" means you can read the next record (eg.
4157 using "$g->journal_get"), and "false" means you have reached the
4158 end of the journal.
4159 This function depends on the feature "journal". See also
4161 "$g->feature-available".
4162 $g->journal_open ($directory);
4164 Open the systemd journal located in directory. Any previously
4165 opened journal handle is closed.
4166 The contents of the journal can be read using "$g->journal_next"
4168 and "$g->journal_get".
4169 After you have finished using the journal, you should close the
4171 handle by calling "$g->journal_close".
4172 This function depends on the feature "journal". See also
4174 "$g->feature-available".
4175 $g->journal_set_data_threshold ($threshold);
4177 Set the data threshold for reading journal entries. This is a hint
4178 to the journal that it may truncate data fields to this size when
4179 reading them (note also that it may not truncate them). If you set
4180 this to 0, then the threshold is unlimited.
4181 See also "$g->journal_get_data_threshold".
4183 This function depends on the feature "journal". See also
4185 "$g->feature-available".
4186 $rskip = $g->journal_skip ($skip);
4188 Skip forwards ("skip ≥ 0") or backwards ("skip < 0") in the
4189 journal.
4190 The number of entries actually skipped is returned (note
4192 "rskip ≥ 0"). If this is not the same as the absolute value of the
4193 skip parameter ("|skip|") you passed in then it means you have
4194 reached the end or the start of the journal.
4195 This function depends on the feature "journal". See also
4197 "$g->feature-available".
4198 $g->kill_subprocess ();
4200 This kills the hypervisor.
4201 Do not call this. See: "$g->shutdown" instead.
4203 This function is deprecated. In new code, use the "shutdown" call
4205 instead.
4206 Deprecated functions will not be removed from the API, but the fact
4208 that they are deprecated indicates that there are problems with
4209 correct use of these functions.
4210 $g->launch ();
4212 You should call this after configuring the handle (eg. adding
4213 drives) but before performing any actions.
4214 Do not call "$g->launch" twice on the same handle. Although it
4216 will not give an error (for historical reasons), the precise
4217 behaviour when you do this is not well defined. Handles are very
4218 cheap to create, so create a new one for each launch.
4219 $g->lchown ($owner, $group, $path);
4221 Change the file owner to "owner" and group to "group". This is
4222 like "$g->chown" but if "path" is a symlink then the link itself is
4223 changed, not the target.
4224 Only numeric uid and gid are supported. If you want to use names,
4226 you will need to locate and parse the password file yourself
4227 (Augeas support makes this relatively easy).
4228 $g->ldmtool_create_all ();
4230 This function scans all block devices looking for Windows dynamic
4231 disk volumes and partitions, and creates devices for any that were
4232 found.
4233 Call "$g->list_ldm_volumes" and "$g->list_ldm_partitions" to return
4235 all devices.
4236 Note that you don't normally need to call this explicitly, since it
4238 is done automatically at "$g->launch" time.
4239 This function depends on the feature "ldm". See also
4241 "$g->feature-available".
4242 @disks = $g->ldmtool_diskgroup_disks ($diskgroup);
4244 Return the disks in a Windows dynamic disk group. The "diskgroup"
4245 parameter should be the GUID of a disk group, one element from the
4246 list returned by "$g->ldmtool_scan".
4247 This function depends on the feature "ldm". See also
4249 "$g->feature-available".
4250 $name = $g->ldmtool_diskgroup_name ($diskgroup);
4252 Return the name of a Windows dynamic disk group. The "diskgroup"
4253 parameter should be the GUID of a disk group, one element from the
4254 list returned by "$g->ldmtool_scan".
4255 This function depends on the feature "ldm". See also
4257 "$g->feature-available".
4258 @volumes = $g->ldmtool_diskgroup_volumes ($diskgroup);
4260 Return the volumes in a Windows dynamic disk group. The
4261 "diskgroup" parameter should be the GUID of a disk group, one
4262 element from the list returned by "$g->ldmtool_scan".
4263 This function depends on the feature "ldm". See also
4265 "$g->feature-available".
4266 $g->ldmtool_remove_all ();
4268 This is essentially the opposite of "$g->ldmtool_create_all". It
4269 removes the device mapper mappings for all Windows dynamic disk
4270 volumes
4271 This function depends on the feature "ldm". See also
4273 "$g->feature-available".
4274 @guids = $g->ldmtool_scan ();
4276 This function scans for Windows dynamic disks. It returns a list
4277 of identifiers (GUIDs) for all disk groups that were found. These
4278 identifiers can be passed to other "$g->ldmtool_*" functions.
4279 This function scans all block devices. To scan a subset of block
4281 devices, call "$g->ldmtool_scan_devices" instead.
4282 This function depends on the feature "ldm". See also
4284 "$g->feature-available".
4285 @guids = $g->ldmtool_scan_devices (\@devices);
4287 This function scans for Windows dynamic disks. It returns a list
4288 of identifiers (GUIDs) for all disk groups that were found. These
4289 identifiers can be passed to other "$g->ldmtool_*" functions.
4290 The parameter "devices" is a list of block devices which are
4292 scanned. If this list is empty, all block devices are scanned.
4293 This function depends on the feature "ldm". See also
4295 "$g->feature-available".
4296 $hint = $g->ldmtool_volume_hint ($diskgroup, $volume);
4298 Return the hint field of the volume named "volume" in the disk
4299 group with GUID "diskgroup". This may not be defined, in which
4300 case the empty string is returned. The hint field is often, though
4301 not always, the name of a Windows drive, eg. "E:".
4302 This function depends on the feature "ldm". See also
4304 "$g->feature-available".
4305 @partitions = $g->ldmtool_volume_partitions ($diskgroup, $volume);
4307 Return the list of partitions in the volume named "volume" in the
4308 disk group with GUID "diskgroup".
4309 This function depends on the feature "ldm". See also
4311 "$g->feature-available".
4312 $voltype = $g->ldmtool_volume_type ($diskgroup, $volume);
4314 Return the type of the volume named "volume" in the disk group with
4315 GUID "diskgroup".
4316 Possible volume types that can be returned here include: "simple",
4318 "spanned", "striped", "mirrored", "raid5". Other types may also be
4319 returned.
4320 This function depends on the feature "ldm". See also
4322 "$g->feature-available".
4323 $xattr = $g->lgetxattr ($path, $name);
4325 Get a single extended attribute from file "path" named "name". If
4326 "path" is a symlink, then this call returns an extended attribute
4327 from the symlink.
4328 Normally it is better to get all extended attributes from a file in
4330 one go by calling "$g->getxattrs". However some Linux filesystem
4331 implementations are buggy and do not provide a way to list out
4332 attributes. For these filesystems (notably ntfs-3g) you have to
4333 know the names of the extended attributes you want in advance and
4334 call this function.
4335 Extended attribute values are blobs of binary data. If there is no
4337 extended attribute named "name", this returns an error.
4338 See also: "$g->lgetxattrs", "$g->getxattr", attr(5).
4340 This function depends on the feature "linuxxattrs". See also
4342 "$g->feature-available".
4343 @xattrs = $g->lgetxattrs ($path);
4345 This is the same as "$g->getxattrs", but if "path" is a symbolic
4346 link, then it returns the extended attributes of the link itself.
4347 This function depends on the feature "linuxxattrs". See also
4349 "$g->feature-available".
4350 @mounttags = $g->list_9p ();
4352 This call does nothing and returns an error.
4353 This function is deprecated. There is no replacement. Consult the
4355 API documentation in guestfs(3) for further information.
4356 Deprecated functions will not be removed from the API, but the fact
4358 that they are deprecated indicates that there are problems with
4359 correct use of these functions.
4360 @devices = $g->list_devices ();
4362 List all the block devices.
4363 The full block device names are returned, eg. /dev/sda.
4365 See also "$g->list_filesystems".
4367 %labels = $g->list_disk_labels ();
4369 If you add drives using the optional "label" parameter of
4370 "$g->add_drive_opts", you can use this call to map between disk
4371 labels, and raw block device and partition names (like /dev/sda and
4372 /dev/sda1).
4373 This returns a hashtable, where keys are the disk labels (without
4375 the /dev/disk/guestfs prefix), and the values are the full raw
4376 block device and partition names (eg. /dev/sda and /dev/sda1).
4377 @devices = $g->list_dm_devices ();
4379 List all device mapper devices.
4380 The returned list contains /dev/mapper/* devices, eg. ones created
4382 by a previous call to "$g->luks_open".
4383 Device mapper devices which correspond to logical volumes are not
4385 returned in this list. Call "$g->lvs" if you want to list logical
4386 volumes.
4387 %fses = $g->list_filesystems ();
4389 This inspection command looks for filesystems on partitions, block
4390 devices and logical volumes, returning a list of "mountables"
4391 containing filesystems and their type.
4392 The return value is a hash, where the keys are the devices
4394 containing filesystems, and the values are the filesystem types.
4395 For example:
4396 "/dev/sda1" => "ntfs"
4398 "/dev/sda2" => "ext2"
4399 "/dev/vg_guest/lv_root" => "ext4"
4400 "/dev/vg_guest/lv_swap" => "swap"
4401 The key is not necessarily a block device. It may also be an opaque
4403 ‘mountable’ string which can be passed to "$g->mount".
4404 The value can have the special value "unknown", meaning the content
4406 of the device is undetermined or empty. "swap" means a Linux swap
4407 partition.
4408 In libguestfs ≤ 1.36 this command ran other libguestfs commands,
4410 which might have included "$g->mount" and "$g->umount", and
4411 therefore you had to use this soon after launch and only when
4412 nothing else was mounted. This restriction is removed in
4413 libguestfs ≥ 1.38.
4414 Not all of the filesystems returned will be mountable. In
4416 particular, swap partitions are returned in the list. Also this
4417 command does not check that each filesystem found is valid and
4418 mountable, and some filesystems might be mountable but require
4419 special options. Filesystems may not all belong to a single
4420 logical operating system (use "$g->inspect_os" to look for OSes).
4421 @devices = $g->list_ldm_partitions ();
4423 This function returns all Windows dynamic disk partitions that were
4424 found at launch time. It returns a list of device names.
4425 This function depends on the feature "ldm". See also
4427 "$g->feature-available".
4428 @devices = $g->list_ldm_volumes ();
4430 This function returns all Windows dynamic disk volumes that were
4431 found at launch time. It returns a list of device names.
4432 This function depends on the feature "ldm". See also
4434 "$g->feature-available".
4435 @devices = $g->list_md_devices ();
4437 List all Linux md devices.
4438 @partitions = $g->list_partitions ();
4440 List all the partitions detected on all block devices.
4441 The full partition device names are returned, eg. /dev/sda1
4443 This does not return logical volumes. For that you will need to
4445 call "$g->lvs".
4446 See also "$g->list_filesystems".
4448 $listing = $g->ll ($directory);
4450 List the files in directory (relative to the root directory, there
4451 is no cwd) in the format of "ls -la".
4452 This command is mostly useful for interactive sessions. It is not
4454 intended that you try to parse the output string.
4455 $listing = $g->llz ($directory);
4457 List the files in directory in the format of "ls -laZ".
4458 This command is mostly useful for interactive sessions. It is not
4460 intended that you try to parse the output string.
4461 This function is deprecated. In new code, use the "lgetxattrs"
4463 call instead.
4464 Deprecated functions will not be removed from the API, but the fact
4466 that they are deprecated indicates that there are problems with
4467 correct use of these functions.
4468 $g->ln ($target, $linkname);
4470 This command creates a hard link.
4471 $g->ln_f ($target, $linkname);
4473 This command creates a hard link, removing the link "linkname" if
4474 it exists already.
4475 $g->ln_s ($target, $linkname);
4477 This command creates a symbolic link using the "ln -s" command.
4478 $g->ln_sf ($target, $linkname);
4480 This command creates a symbolic link using the "ln -sf" command,
4481 The -f option removes the link ("linkname") if it exists already.
4482 $g->lremovexattr ($xattr, $path);
4484 This is the same as "$g->removexattr", but if "path" is a symbolic
4485 link, then it removes an extended attribute of the link itself.
4486 This function depends on the feature "linuxxattrs". See also
4488 "$g->feature-available".
4489 @listing = $g->ls ($directory);
4491 List the files in directory (relative to the root directory, there
4492 is no cwd). The "." and ".." entries are not returned, but hidden
4493 files are shown.
4494 $g->ls0 ($dir, $filenames);
4496 This specialized command is used to get a listing of the filenames
4497 in the directory "dir". The list of filenames is written to the
4498 local file filenames (on the host).
4499 In the output file, the filenames are separated by "\0" characters.
4501 "." and ".." are not returned. The filenames are not sorted.
4503 $g->lsetxattr ($xattr, $val, $vallen, $path);
4505 This is the same as "$g->setxattr", but if "path" is a symbolic
4506 link, then it sets an extended attribute of the link itself.
4507 This function depends on the feature "linuxxattrs". See also
4509 "$g->feature-available".
4510 %statbuf = $g->lstat ($path);
4512 Returns file information for the given "path".
4513 This is the same as "$g->stat" except that if "path" is a symbolic
4515 link, then the link is stat-ed, not the file it refers to.
4516 This is the same as the lstat(2) system call.
4518 This function is deprecated. In new code, use the "lstatns" call
4520 instead.
4521 Deprecated functions will not be removed from the API, but the fact
4523 that they are deprecated indicates that there are problems with
4524 correct use of these functions.
4525 @statbufs = $g->lstatlist ($path, \@names);
4527 This call allows you to perform the "$g->lstat" operation on
4528 multiple files, where all files are in the directory "path".
4529 "names" is the list of files from this directory.
4530 On return you get a list of stat structs, with a one-to-one
4532 correspondence to the "names" list. If any name did not exist or
4533 could not be lstat'd, then the "st_ino" field of that structure is
4534 set to -1.
4535 This call is intended for programs that want to efficiently list a
4537 directory contents without making many round-trips. See also
4538 "$g->lxattrlist" for a similarly efficient call for getting
4539 extended attributes.
4540 This function is deprecated. In new code, use the "lstatnslist"
4542 call instead.
4543 Deprecated functions will not be removed from the API, but the fact
4545 that they are deprecated indicates that there are problems with
4546 correct use of these functions.
4547 %statbuf = $g->lstatns ($path);
4549 Returns file information for the given "path".
4550 This is the same as "$g->statns" except that if "path" is a
4552 symbolic link, then the link is stat-ed, not the file it refers to.
4553 This is the same as the lstat(2) system call.
4555 @statbufs = $g->lstatnslist ($path, \@names);
4557 This call allows you to perform the "$g->lstatns" operation on
4558 multiple files, where all files are in the directory "path".
4559 "names" is the list of files from this directory.
4560 On return you get a list of stat structs, with a one-to-one
4562 correspondence to the "names" list. If any name did not exist or
4563 could not be lstat'd, then the "st_ino" field of that structure is
4564 set to -1.
4565 This call is intended for programs that want to efficiently list a
4567 directory contents without making many round-trips. See also
4568 "$g->lxattrlist" for a similarly efficient call for getting
4569 extended attributes.
4570 $g->luks_add_key ($device, $key, $newkey, $keyslot);
4572 This command adds a new key on LUKS device "device". "key" is any
4573 existing key, and is used to access the device. "newkey" is the
4574 new key to add. "keyslot" is the key slot that will be replaced.
4575 Note that if "keyslot" already contains a key, then this command
4577 will fail. You have to use "$g->luks_kill_slot" first to remove
4578 that key.
4579 This function depends on the feature "luks". See also
4581 "$g->feature-available".
4582 $g->luks_close ($device);
4584 This closes a LUKS device that was created earlier by
4585 "$g->luks_open" or "$g->luks_open_ro". The "device" parameter must
4586 be the name of the LUKS mapping device (ie. /dev/mapper/mapname)
4587 and not the name of the underlying block device.
4588 This function depends on the feature "luks". See also
4590 "$g->feature-available".
4591 This function is deprecated. In new code, use the
4593 "cryptsetup_close" call instead.
4594 Deprecated functions will not be removed from the API, but the fact
4596 that they are deprecated indicates that there are problems with
4597 correct use of these functions.
4598 $g->luks_format ($device, $key, $keyslot);
4600 This command erases existing data on "device" and formats the
4601 device as a LUKS encrypted device. "key" is the initial key, which
4602 is added to key slot "keyslot". (LUKS supports 8 key slots,
4603 numbered 0-7).
4604 This function depends on the feature "luks". See also
4606 "$g->feature-available".
4607 $g->luks_format_cipher ($device, $key, $keyslot, $cipher);
4609 This command is the same as "$g->luks_format" but it also allows
4610 you to set the "cipher" used.
4611 This function depends on the feature "luks". See also
4613 "$g->feature-available".
4614 $g->luks_kill_slot ($device, $key, $keyslot);
4616 This command deletes the key in key slot "keyslot" from the
4617 encrypted LUKS device "device". "key" must be one of the other
4618 keys.
4619 This function depends on the feature "luks". See also
4621 "$g->feature-available".
4622 $g->luks_open ($device, $key, $mapname);
4624 This command opens a block device which has been encrypted
4625 according to the Linux Unified Key Setup (LUKS) standard.
4626 "device" is the encrypted block device or partition.
4628 The caller must supply one of the keys associated with the LUKS
4630 block device, in the "key" parameter.
4631 This creates a new block device called /dev/mapper/mapname. Reads
4633 and writes to this block device are decrypted from and encrypted to
4634 the underlying "device" respectively.
4635 If this block device contains LVM volume groups, then calling
4637 "$g->lvm_scan" with the "activate" parameter "true" will make them
4638 visible.
4639 Use "$g->list_dm_devices" to list all device mapper devices.
4641 This function depends on the feature "luks". See also
4643 "$g->feature-available".
4644 This function is deprecated. In new code, use the
4646 "cryptsetup_open" call instead.
4647 Deprecated functions will not be removed from the API, but the fact
4649 that they are deprecated indicates that there are problems with
4650 correct use of these functions.
4651 $g->luks_open_ro ($device, $key, $mapname);
4653 This is the same as "$g->luks_open" except that a read-only mapping
4654 is created.
4655 This function depends on the feature "luks". See also
4657 "$g->feature-available".
4658 This function is deprecated. In new code, use the
4660 "cryptsetup_open" call instead.
4661 Deprecated functions will not be removed from the API, but the fact
4663 that they are deprecated indicates that there are problems with
4664 correct use of these functions.
4665 $uuid = $g->luks_uuid ($device);
4667 This returns the UUID of the LUKS device "device".
4668 This function depends on the feature "luks". See also
4670 "$g->feature-available".
4671 $g->lvcreate ($logvol, $volgroup, $mbytes);
4673 This creates an LVM logical volume called "logvol" on the volume
4674 group "volgroup", with "size" megabytes.
4675 This function depends on the feature "lvm2". See also
4677 "$g->feature-available".
4678 $g->lvcreate_free ($logvol, $volgroup, $percent);
4680 Create an LVM logical volume called /dev/volgroup/logvol, using
4681 approximately "percent" % of the free space remaining in the volume
4682 group. Most usefully, when "percent" is 100 this will create the
4683 largest possible LV.
4684 This function depends on the feature "lvm2". See also
4686 "$g->feature-available".
4687 $lv = $g->lvm_canonical_lv_name ($lvname);
4689 This converts alternative naming schemes for LVs that you might
4690 find to the canonical name. For example, /dev/mapper/VG-LV is
4691 converted to /dev/VG/LV.
4692 This command returns an error if the "lvname" parameter does not
4694 refer to a logical volume. In this case errno will be set to
4695 "EINVAL".
4696 See also "$g->is_lv", "$g->canonical_device_name".
4698 $g->lvm_clear_filter ();
4700 This undoes the effect of "$g->lvm_set_filter". LVM will be able
4701 to see every block device.
4702 This command also clears the LVM cache and performs a volume group
4704 scan.
4705 $g->lvm_remove_all ();
4707 This command removes all LVM logical volumes, volume groups and
4708 physical volumes.
4709 This function depends on the feature "lvm2". See also
4711 "$g->feature-available".
4712 $g->lvm_scan ($activate);
4714 This scans all block devices and rebuilds the list of LVM physical
4715 volumes, volume groups and logical volumes.
4716 If the "activate" parameter is "true" then newly found volume
4718 groups and logical volumes are activated, meaning the LV /dev/VG/LV
4719 devices become visible.
4720 When a libguestfs handle is launched it scans for existing devices,
4722 so you do not normally need to use this API. However it is useful
4723 when you have added a new device or deleted an existing device
4724 (such as when the "$g->luks_open" API is used).
4725 $g->lvm_set_filter (\@devices);
4727 This sets the LVM device filter so that LVM will only be able to
4728 "see" the block devices in the list "devices", and will ignore all
4729 other attached block devices.
4730 Where disk image(s) contain duplicate PVs or VGs, this command is
4732 useful to get LVM to ignore the duplicates, otherwise LVM can get
4733 confused. Note also there are two types of duplication possible:
4734 either cloned PVs/VGs which have identical UUIDs; or VGs that are
4735 not cloned but just happen to have the same name. In normal
4736 operation you cannot create this situation, but you can do it
4737 outside LVM, eg. by cloning disk images or by bit twiddling inside
4738 the LVM metadata.
4739 This command also clears the LVM cache and performs a volume group
4741 scan.
4742 You can filter whole block devices or individual partitions.
4744 You cannot use this if any VG is currently in use (eg. contains a
4746 mounted filesystem), even if you are not filtering out that VG.
4747 This function depends on the feature "lvm2". See also
4749 "$g->feature-available".
4750 $g->lvremove ($device);
4752 Remove an LVM logical volume "device", where "device" is the path
4753 to the LV, such as /dev/VG/LV.
4754 You can also remove all LVs in a volume group by specifying the VG
4756 name, /dev/VG.
4757 This function depends on the feature "lvm2". See also
4759 "$g->feature-available".
4760 $g->lvrename ($logvol, $newlogvol);
4762 Rename a logical volume "logvol" with the new name "newlogvol".
4763 $g->lvresize ($device, $mbytes);
4765 This resizes (expands or shrinks) an existing LVM logical volume to
4766 "mbytes". When reducing, data in the reduced part is lost.
4767 This function depends on the feature "lvm2". See also
4769 "$g->feature-available".
4770 $g->lvresize_free ($lv, $percent);
4772 This expands an existing logical volume "lv" so that it fills "pc"
4773 % of the remaining free space in the volume group. Commonly you
4774 would call this with pc = 100 which expands the logical volume as
4775 much as possible, using all remaining free space in the volume
4776 group.
4777 This function depends on the feature "lvm2". See also
4779 "$g->feature-available".
4780 @logvols = $g->lvs ();
4782 List all the logical volumes detected. This is the equivalent of
4783 the lvs(8) command.
4784 This returns a list of the logical volume device names (eg.
4786 /dev/VolGroup00/LogVol00).
4787 See also "$g->lvs_full", "$g->list_filesystems".
4789 This function depends on the feature "lvm2". See also
4791 "$g->feature-available".
4792 @logvols = $g->lvs_full ();
4794 List all the logical volumes detected. This is the equivalent of
4795 the lvs(8) command. The "full" version includes all fields.
4796 This function depends on the feature "lvm2". See also
4798 "$g->feature-available".
4799 $uuid = $g->lvuuid ($device);
4801 This command returns the UUID of the LVM LV "device".
4802 @xattrs = $g->lxattrlist ($path, \@names);
4804 This call allows you to get the extended attributes of multiple
4805 files, where all files are in the directory "path". "names" is the
4806 list of files from this directory.
4807 On return you get a flat list of xattr structs which must be
4809 interpreted sequentially. The first xattr struct always has a
4810 zero-length "attrname". "attrval" in this struct is zero-length to
4811 indicate there was an error doing "$g->lgetxattr" for this file, or
4812 is a C string which is a decimal number (the number of following
4813 attributes for this file, which could be "0"). Then after the
4814 first xattr struct are the zero or more attributes for the first
4815 named file. This repeats for the second and subsequent files.
4816 This call is intended for programs that want to efficiently list a
4818 directory contents without making many round-trips. See also
4819 "$g->lstatlist" for a similarly efficient call for getting standard
4820 stats.
4821 This function depends on the feature "linuxxattrs". See also
4823 "$g->feature-available".
4824 $disks = $g->max_disks ();
4826 Return the maximum number of disks that may be added to a handle
4827 (eg. by "$g->add_drive_opts" and similar calls).
4828 This function was added in libguestfs 1.19.7. In previous versions
4830 of libguestfs the limit was 25.
4831 See "MAXIMUM NUMBER OF DISKS" in guestfs(3) for additional
4833 information on this topic.
4834 $g->md_create ($name, \@devices [, missingbitmap => $missingbitmap] [,
4836 nrdevices => $nrdevices] [, spare => $spare] [, chunk => $chunk] [,
4837 level => $level]);
4838 Create a Linux md (RAID) device named "name" on the devices in the
4839 list "devices".
4840 The optional parameters are:
4842 "missingbitmap"
4844 A bitmap of missing devices. If a bit is set it means that a
4845 missing device is added to the array. The least significant
4846 bit corresponds to the first device in the array.
4847 As examples:
4849 If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
4851 resulting array would be "[<missing>, "/dev/sda"]".
4852 If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
4854 resulting array would be "["/dev/sda", <missing>]".
4855 This defaults to 0 (no missing devices).
4857 The length of "devices" + the number of bits set in
4859 "missingbitmap" must equal "nrdevices" + "spare".
4860 "nrdevices"
4862 The number of active RAID devices.
4863 If not set, this defaults to the length of "devices" plus the
4865 number of bits set in "missingbitmap".
4866 "spare"
4868 The number of spare devices.
4869 If not set, this defaults to 0.
4871 "chunk"
4873 The chunk size in bytes.
4874 The "chunk" parameter does not make sense, and should not be
4876 specified, when "level" is "raid1" (which is the default; see
4877 below).
4878 "level"
4880 The RAID level, which can be one of: "linear", "raid0", 0,
4881 "stripe", "raid1", 1, "mirror", "raid4", 4, "raid5", 5,
4882 "raid6", 6, "raid10", 10. Some of these are synonymous, and
4883 more levels may be added in future.
4884 If not set, this defaults to "raid1".
4886 This function depends on the feature "mdadm". See also
4888 "$g->feature-available".
4889 %info = $g->md_detail ($md);
4891 This command exposes the output of "mdadm -DY <md>". The following
4892 fields are usually present in the returned hash. Other fields may
4893 also be present.
4894 "level"
4896 The raid level of the MD device.
4897 "devices"
4899 The number of underlying devices in the MD device.
4900 "metadata"
4902 The metadata version used.
4903 "uuid"
4905 The UUID of the MD device.
4906 "name"
4908 The name of the MD device.
4909 This function depends on the feature "mdadm". See also
4911 "$g->feature-available".
4912 @devices = $g->md_stat ($md);
4914 This call returns a list of the underlying devices which make up
4915 the single software RAID array device "md".
4916 To get a list of software RAID devices, call "$g->list_md_devices".
4918 Each structure returned corresponds to one device along with
4920 additional status information:
4921 "mdstat_device"
4923 The name of the underlying device.
4924 "mdstat_index"
4926 The index of this device within the array.
4927 "mdstat_flags"
4929 Flags associated with this device. This is a string containing
4930 (in no specific order) zero or more of the following flags:
4931 "W" write-mostly
4933 "F" device is faulty
4935 "S" device is a RAID spare
4937 "R" replacement
4939 This function depends on the feature "mdadm". See also
4941 "$g->feature-available".
4942 $g->md_stop ($md);
4944 This command deactivates the MD array named "md". The device is
4945 stopped, but it is not destroyed or zeroed.
4946 This function depends on the feature "mdadm". See also
4948 "$g->feature-available".
4949 $g->mkdir ($path);
4951 Create a directory named "path".
4952 $g->mkdir_mode ($path, $mode);
4954 This command creates a directory, setting the initial permissions
4955 of the directory to "mode".
4956 For common Linux filesystems, the actual mode which is set will be
4958 "mode & ~umask & 01777". Non-native-Linux filesystems may
4959 interpret the mode in other ways.
4960 See also "$g->mkdir", "$g->umask"
4962 $g->mkdir_p ($path);
4964 Create a directory named "path", creating any parent directories as
4965 necessary. This is like the "mkdir -p" shell command.
4966 $dir = $g->mkdtemp ($tmpl);
4968 This command creates a temporary directory. The "tmpl" parameter
4969 should be a full pathname for the temporary directory name with the
4970 final six characters being "XXXXXX".
4971 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the
4973 second one being suitable for Windows filesystems.
4974 The name of the temporary directory that was created is returned.
4976 The temporary directory is created with mode 0700 and is owned by
4978 root.
4979 The caller is responsible for deleting the temporary directory and
4981 its contents after use.
4982 See also: mkdtemp(3)
4984 $g->mke2fs ($device [, blockscount => $blockscount] [, blocksize =>
4986 $blocksize] [, fragsize => $fragsize] [, blockspergroup =>
4987 $blockspergroup] [, numberofgroups => $numberofgroups] [, bytesperinode
4988 => $bytesperinode] [, inodesize => $inodesize] [, journalsize =>
4989 $journalsize] [, numberofinodes => $numberofinodes] [, stridesize =>
4990 $stridesize] [, stripewidth => $stripewidth] [, maxonlineresize =>
4991 $maxonlineresize] [, reservedblockspercentage =>
4992 $reservedblockspercentage] [, mmpupdateinterval => $mmpupdateinterval]
4993 [, journaldevice => $journaldevice] [, label => $label] [,
4994 lastmounteddir => $lastmounteddir] [, creatoros => $creatoros] [,
4995 fstype => $fstype] [, usagetype => $usagetype] [, uuid => $uuid] [,
4996 forcecreate => $forcecreate] [, writesbandgrouponly =>
4997 $writesbandgrouponly] [, lazyitableinit => $lazyitableinit] [,
4998 lazyjournalinit => $lazyjournalinit] [, testfs => $testfs] [, discard
4999 => $discard] [, quotatype => $quotatype] [, extent => $extent] [,
5000 filetype => $filetype] [, flexbg => $flexbg] [, hasjournal =>
5001 $hasjournal] [, journaldev => $journaldev] [, largefile => $largefile]
5002 [, quota => $quota] [, resizeinode => $resizeinode] [, sparsesuper =>
5003 $sparsesuper] [, uninitbg => $uninitbg]);
5004 "mke2fs" is used to create an ext2, ext3, or ext4 filesystem on
5005 "device".
5006 The optional "blockscount" is the size of the filesystem in blocks.
5008 If omitted it defaults to the size of "device". Note if the
5009 filesystem is too small to contain a journal, "mke2fs" will
5010 silently create an ext2 filesystem instead.
5011 $g->mke2fs_J ($fstype, $blocksize, $device, $journal);
5013 This creates an ext2/3/4 filesystem on "device" with an external
5014 journal on "journal". It is equivalent to the command:
5015 mke2fs -t fstype -b blocksize -J device=<journal> <device>
5017 See also "$g->mke2journal".
5019 This function is deprecated. In new code, use the "mke2fs" call
5021 instead.
5022 Deprecated functions will not be removed from the API, but the fact
5024 that they are deprecated indicates that there are problems with
5025 correct use of these functions.
5026 $g->mke2fs_JL ($fstype, $blocksize, $device, $label);
5028 This creates an ext2/3/4 filesystem on "device" with an external
5029 journal on the journal labeled "label".
5030 See also "$g->mke2journal_L".
5032 This function is deprecated. In new code, use the "mke2fs" call
5034 instead.
5035 Deprecated functions will not be removed from the API, but the fact
5037 that they are deprecated indicates that there are problems with
5038 correct use of these functions.
5039 $g->mke2fs_JU ($fstype, $blocksize, $device, $uuid);
5041 This creates an ext2/3/4 filesystem on "device" with an external
5042 journal on the journal with UUID "uuid".
5043 See also "$g->mke2journal_U".
5045 This function depends on the feature "linuxfsuuid". See also
5047 "$g->feature-available".
5048 This function is deprecated. In new code, use the "mke2fs" call
5050 instead.
5051 Deprecated functions will not be removed from the API, but the fact
5053 that they are deprecated indicates that there are problems with
5054 correct use of these functions.
5055 $g->mke2journal ($blocksize, $device);
5057 This creates an ext2 external journal on "device". It is
5058 equivalent to the command:
5059 mke2fs -O journal_dev -b blocksize device
5061 This function is deprecated. In new code, use the "mke2fs" call
5063 instead.
5064 Deprecated functions will not be removed from the API, but the fact
5066 that they are deprecated indicates that there are problems with
5067 correct use of these functions.
5068 $g->mke2journal_L ($blocksize, $label, $device);
5070 This creates an ext2 external journal on "device" with label
5071 "label".
5072 This function is deprecated. In new code, use the "mke2fs" call
5074 instead.
5075 Deprecated functions will not be removed from the API, but the fact
5077 that they are deprecated indicates that there are problems with
5078 correct use of these functions.
5079 $g->mke2journal_U ($blocksize, $uuid, $device);
5081 This creates an ext2 external journal on "device" with UUID "uuid".
5082 This function depends on the feature "linuxfsuuid". See also
5084 "$g->feature-available".
5085 This function is deprecated. In new code, use the "mke2fs" call
5087 instead.
5088 Deprecated functions will not be removed from the API, but the fact
5090 that they are deprecated indicates that there are problems with
5091 correct use of these functions.
5092 $g->mkfifo ($mode, $path);
5094 This call creates a FIFO (named pipe) called "path" with mode
5095 "mode". It is just a convenient wrapper around "$g->mknod".
5096 Unlike with "$g->mknod", "mode" must contain only permissions bits.
5098 The mode actually set is affected by the umask.
5100 This function depends on the feature "mknod". See also
5102 "$g->feature-available".
5103 $g->mkfs ($fstype, $device [, blocksize => $blocksize] [, features =>
5105 $features] [, inode => $inode] [, sectorsize => $sectorsize] [, label
5106 => $label]);
5107 This function creates a filesystem on "device". The filesystem
5108 type is "fstype", for example "ext3".
5109 The optional arguments are:
5111 "blocksize"
5113 The filesystem block size. Supported block sizes depend on the
5114 filesystem type, but typically they are 1024, 2048 or 4096 for
5115 Linux ext2/3 filesystems.
5116 For VFAT and NTFS the "blocksize" parameter is treated as the
5118 requested cluster size.
5119 For UFS block sizes, please see mkfs.ufs(8).
5121 "features"
5123 This passes the -O parameter to the external mkfs program.
5124 For certain filesystem types, this allows extra filesystem
5126 features to be selected. See mke2fs(8) and mkfs.ufs(8) for
5127 more details.
5128 You cannot use this optional parameter with the "gfs" or "gfs2"
5130 filesystem type.
5131 "inode"
5133 This passes the -I parameter to the external mke2fs(8) program
5134 which sets the inode size (only for ext2/3/4 filesystems at
5135 present).
5136 "sectorsize"
5138 This passes the -S parameter to external mkfs.ufs(8) program,
5139 which sets sector size for ufs filesystem.
5140 $g->mkfs_opts ($fstype, $device [, blocksize => $blocksize] [, features
5142 => $features] [, inode => $inode] [, sectorsize => $sectorsize] [,
5143 label => $label]);
5144 This is an alias of "mkfs".
5145 $g->mkfs_b ($fstype, $blocksize, $device);
5147 This call is similar to "$g->mkfs", but it allows you to control
5148 the block size of the resulting filesystem. Supported block sizes
5149 depend on the filesystem type, but typically they are 1024, 2048 or
5150 4096 only.
5151 For VFAT and NTFS the "blocksize" parameter is treated as the
5153 requested cluster size.
5154 This function is deprecated. In new code, use the "mkfs" call
5156 instead.
5157 Deprecated functions will not be removed from the API, but the fact
5159 that they are deprecated indicates that there are problems with
5160 correct use of these functions.
5161 $g->mkfs_btrfs (\@devices [, allocstart => $allocstart] [, bytecount =>
5163 $bytecount] [, datatype => $datatype] [, leafsize => $leafsize] [,
5164 label => $label] [, metadata => $metadata] [, nodesize => $nodesize] [,
5165 sectorsize => $sectorsize]);
5166 Create a btrfs filesystem, allowing all configurables to be set.
5167 For more information on the optional arguments, see mkfs.btrfs(8).
5168 Since btrfs filesystems can span multiple devices, this takes a
5170 non-empty list of devices.
5171 To create general filesystems, use "$g->mkfs".
5173 This function depends on the feature "btrfs". See also
5175 "$g->feature-available".
5176 $g->mklost_and_found ($mountpoint);
5178 Make the "lost+found" directory, normally in the root directory of
5179 an ext2/3/4 filesystem. "mountpoint" is the directory under which
5180 we try to create the "lost+found" directory.
5181 $g->mkmountpoint ($exemptpath);
5183 "$g->mkmountpoint" and "$g->rmmountpoint" are specialized calls
5184 that can be used to create extra mountpoints before mounting the
5185 first filesystem.
5186 These calls are only necessary in some very limited circumstances,
5188 mainly the case where you want to mount a mix of unrelated and/or
5189 read-only filesystems together.
5190 For example, live CDs often contain a "Russian doll" nest of
5192 filesystems, an ISO outer layer, with a squashfs image inside, with
5193 an ext2/3 image inside that. You can unpack this as follows in
5194 guestfish:
5195 add-ro Fedora-11-i686-Live.iso
5197 run
5198 mkmountpoint /cd
5199 mkmountpoint /sqsh
5200 mkmountpoint /ext3fs
5201 mount /dev/sda /cd
5202 mount-loop /cd/LiveOS/squashfs.img /sqsh
5203 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
5204 The inner filesystem is now unpacked under the /ext3fs mountpoint.
5206 "$g->mkmountpoint" is not compatible with "$g->umount_all". You
5208 may get unexpected errors if you try to mix these calls. It is
5209 safest to manually unmount filesystems and remove mountpoints after
5210 use.
5211 "$g->umount_all" unmounts filesystems by sorting the paths longest
5213 first, so for this to work for manual mountpoints, you must ensure
5214 that the innermost mountpoints have the longest pathnames, as in
5215 the example code above.
5216 For more details see
5218 <https://bugzilla.redhat.com/show_bug.cgi?id=599503>
5219 Autosync [see "$g->set_autosync", this is set by default on
5221 handles] can cause "$g->umount_all" to be called when the handle is
5222 closed which can also trigger these issues.
5223 $g->mknod ($mode, $devmajor, $devminor, $path);
5225 This call creates block or character special devices, or named
5226 pipes (FIFOs).
5227 The "mode" parameter should be the mode, using the standard
5229 constants. "devmajor" and "devminor" are the device major and
5230 minor numbers, only used when creating block and character special
5231 devices.
5232 Note that, just like mknod(2), the mode must be bitwise OR'd with
5234 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just
5235 creates a regular file). These constants are available in the
5236 standard Linux header files, or you can use "$g->mknod_b",
5237 "$g->mknod_c" or "$g->mkfifo" which are wrappers around this
5238 command which bitwise OR in the appropriate constant for you.
5239 The mode actually set is affected by the umask.
5241 This function depends on the feature "mknod". See also
5243 "$g->feature-available".
5244 $g->mknod_b ($mode, $devmajor, $devminor, $path);
5246 This call creates a block device node called "path" with mode
5247 "mode" and device major/minor "devmajor" and "devminor". It is
5248 just a convenient wrapper around "$g->mknod".
5249 Unlike with "$g->mknod", "mode" must contain only permissions bits.
5251 The mode actually set is affected by the umask.
5253 This function depends on the feature "mknod". See also
5255 "$g->feature-available".
5256 $g->mknod_c ($mode, $devmajor, $devminor, $path);
5258 This call creates a char device node called "path" with mode "mode"
5259 and device major/minor "devmajor" and "devminor". It is just a
5260 convenient wrapper around "$g->mknod".
5261 Unlike with "$g->mknod", "mode" must contain only permissions bits.
5263 The mode actually set is affected by the umask.
5265 This function depends on the feature "mknod". See also
5267 "$g->feature-available".
5268 $g->mksquashfs ($path, $filename [, compress => $compress] [, excludes
5270 => $excludes]);
5271 Create a squashfs filesystem for the specified "path".
5272 The optional "compress" flag controls compression. If not given,
5274 then the output compressed using "gzip". Otherwise one of the
5275 following strings may be given to select the compression type of
5276 the squashfs: "gzip", "lzma", "lzo", "lz4", "xz".
5277 The other optional arguments are:
5279 "excludes"
5281 A list of wildcards. Files are excluded if they match any of
5282 the wildcards.
5283 Please note that this API may fail when used to compress
5285 directories with large files, such as the resulting squashfs will
5286 be over 3GB big.
5287 This function depends on the feature "squashfs". See also
5289 "$g->feature-available".
5290 $g->mkswap ($device [, label => $label] [, uuid => $uuid]);
5292 Create a Linux swap partition on "device".
5293 The option arguments "label" and "uuid" allow you to set the label
5295 and/or UUID of the new swap partition.
5296 $g->mkswap_opts ($device [, label => $label] [, uuid => $uuid]);
5298 This is an alias of "mkswap".
5299 $g->mkswap_L ($label, $device);
5301 Create a swap partition on "device" with label "label".
5302 Note that you cannot attach a swap label to a block device (eg.
5304 /dev/sda), just to a partition. This appears to be a limitation of
5305 the kernel or swap tools.
5306 This function is deprecated. In new code, use the "mkswap" call
5308 instead.
5309 Deprecated functions will not be removed from the API, but the fact
5311 that they are deprecated indicates that there are problems with
5312 correct use of these functions.
5313 $g->mkswap_U ($uuid, $device);
5315 Create a swap partition on "device" with UUID "uuid".
5316 This function depends on the feature "linuxfsuuid". See also
5318 "$g->feature-available".
5319 This function is deprecated. In new code, use the "mkswap" call
5321 instead.
5322 Deprecated functions will not be removed from the API, but the fact
5324 that they are deprecated indicates that there are problems with
5325 correct use of these functions.
5326 $g->mkswap_file ($path);
5328 Create a swap file.
5329 This command just writes a swap file signature to an existing file.
5331 To create the file itself, use something like "$g->fallocate".
5332 $path = $g->mktemp ($tmpl [, suffix => $suffix]);
5334 This command creates a temporary file. The "tmpl" parameter should
5335 be a full pathname for the temporary directory name with the final
5336 six characters being "XXXXXX".
5337 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the
5339 second one being suitable for Windows filesystems.
5340 The name of the temporary file that was created is returned.
5342 The temporary file is created with mode 0600 and is owned by root.
5344 The caller is responsible for deleting the temporary file after
5346 use.
5347 If the optional "suffix" parameter is given, then the suffix (eg.
5349 ".txt") is appended to the temporary name.
5350 See also: "$g->mkdtemp".
5352 $g->modprobe ($modulename);
5354 This loads a kernel module in the appliance.
5355 This function depends on the feature "linuxmodules". See also
5357 "$g->feature-available".
5358 $g->mount ($mountable, $mountpoint);
5360 Mount a guest disk at a position in the filesystem. Block devices
5361 are named /dev/sda, /dev/sdb and so on, as they were added to the
5362 guest. If those block devices contain partitions, they will have
5363 the usual names (eg. /dev/sda1). Also LVM /dev/VG/LV-style names
5364 can be used, or ‘mountable’ strings returned by
5365 "$g->list_filesystems" or "$g->inspect_get_mountpoints".
5366 The rules are the same as for mount(2): A filesystem must first be
5368 mounted on / before others can be mounted. Other filesystems can
5369 only be mounted on directories which already exist.
5370 The mounted filesystem is writable, if we have sufficient
5372 permissions on the underlying device.
5373 Before libguestfs 1.13.16, this call implicitly added the options
5375 "sync" and "noatime". The "sync" option greatly slowed writes and
5376 caused many problems for users. If your program might need to work
5377 with older versions of libguestfs, use "$g->mount_options" instead
5378 (using an empty string for the first parameter if you don't want
5379 any options).
5380 $g->mount_9p ($mounttag, $mountpoint [, options => $options]);
5382 This call does nothing and returns an error.
5383 This function is deprecated. There is no replacement. Consult the
5385 API documentation in guestfs(3) for further information.
5386 Deprecated functions will not be removed from the API, but the fact
5388 that they are deprecated indicates that there are problems with
5389 correct use of these functions.
5390 $g->mount_local ($localmountpoint [, readonly => $readonly] [, options
5392 => $options] [, cachetimeout => $cachetimeout] [, debugcalls =>
5393 $debugcalls]);
5394 This call exports the libguestfs-accessible filesystem to a local
5395 mountpoint (directory) called "localmountpoint". Ordinary reads
5396 and writes to files and directories under "localmountpoint" are
5397 redirected through libguestfs.
5398 If the optional "readonly" flag is set to true, then writes to the
5400 filesystem return error "EROFS".
5401 "options" is a comma-separated list of mount options. See
5403 guestmount(1) for some useful options.
5404 "cachetimeout" sets the timeout (in seconds) for cached directory
5406 entries. The default is 60 seconds. See guestmount(1) for further
5407 information.
5408 If "debugcalls" is set to true, then additional debugging
5410 information is generated for every FUSE call.
5411 When "$g->mount_local" returns, the filesystem is ready, but is not
5413 processing requests (access to it will block). You have to call
5414 "$g->mount_local_run" to run the main loop.
5415 See "MOUNT LOCAL" in guestfs(3) for full documentation.
5417 $g->mount_local_run ();
5419 Run the main loop which translates kernel calls to libguestfs
5420 calls.
5421 This should only be called after "$g->mount_local" returns
5423 successfully. The call will not return until the filesystem is
5424 unmounted.
5425 Note you must not make concurrent libguestfs calls on the same
5427 handle from another thread.
5428 You may call this from a different thread than the one which called
5430 "$g->mount_local", subject to the usual rules for threads and
5431 libguestfs (see "MULTIPLE HANDLES AND MULTIPLE THREADS" in
5432 guestfs(3)).
5433 See "MOUNT LOCAL" in guestfs(3) for full documentation.
5435 $g->mount_loop ($file, $mountpoint);
5437 This command lets you mount file (a filesystem image in a file) on
5438 a mount point. It is entirely equivalent to the command "mount -o
5439 loop file mountpoint".
5440 $g->mount_options ($options, $mountable, $mountpoint);
5442 This is the same as the "$g->mount" command, but it allows you to
5443 set the mount options as for the mount(8) -o flag.
5444 If the "options" parameter is an empty string, then no options are
5446 passed (all options default to whatever the filesystem uses).
5447 $g->mount_ro ($mountable, $mountpoint);
5449 This is the same as the "$g->mount" command, but it mounts the
5450 filesystem with the read-only (-o ro) flag.
5451 $g->mount_vfs ($options, $vfstype, $mountable, $mountpoint);
5453 This is the same as the "$g->mount" command, but it allows you to
5454 set both the mount options and the vfstype as for the mount(8) -o
5455 and -t flags.
5456 $device = $g->mountable_device ($mountable);
5458 Returns the device name of a mountable. In quite a lot of cases,
5459 the mountable is the device name.
5460 However this doesn't apply for btrfs subvolumes, where the
5462 mountable is a combination of both the device name and the
5463 subvolume path (see also "$g->mountable_subvolume" to extract the
5464 subvolume path of the mountable if any).
5465 $subvolume = $g->mountable_subvolume ($mountable);
5467 Returns the subvolume path of a mountable. Btrfs subvolumes
5468 mountables are a combination of both the device name and the
5469 subvolume path (see also "$g->mountable_device" to extract the
5470 device of the mountable).
5471 If the mountable does not represent a btrfs subvolume, then this
5473 function fails and the "errno" is set to "EINVAL".
5474 %mps = $g->mountpoints ();
5476 This call is similar to "$g->mounts". That call returns a list of
5477 devices. This one returns a hash table (map) of device name to
5478 directory where the device is mounted.
5479 @devices = $g->mounts ();
5481 This returns the list of currently mounted filesystems. It returns
5482 the list of devices (eg. /dev/sda1, /dev/VG/LV).
5483 Some internal mounts are not shown.
5485 See also: "$g->mountpoints"
5487 $g->mv ($src, $dest);
5489 This moves a file from "src" to "dest" where "dest" is either a
5490 destination filename or destination directory.
5491 See also: "$g->rename".
5493 $nrdisks = $g->nr_devices ();
5495 This returns the number of whole block devices that were added.
5496 This is the same as the number of devices that would be returned if
5497 you called "$g->list_devices".
5498 To find out the maximum number of devices that could be added, call
5500 "$g->max_disks".
5501 $status = $g->ntfs_3g_probe ($rw, $device);
5503 This command runs the ntfs-3g.probe(8) command which probes an NTFS
5504 "device" for mountability. (Not all NTFS volumes can be mounted
5505 read-write, and some cannot be mounted at all).
5506 "rw" is a boolean flag. Set it to true if you want to test if the
5508 volume can be mounted read-write. Set it to false if you want to
5509 test if the volume can be mounted read-only.
5510 The return value is an integer which 0 if the operation would
5512 succeed, or some non-zero value documented in the ntfs-3g.probe(8)
5513 manual page.
5514 This function depends on the feature "ntfs3g". See also
5516 "$g->feature-available".
5517 $g->ntfscat_i ($device, $inode, $filename);
5519 Download a file given its inode from a NTFS filesystem and save it
5520 as filename on the local machine.
5521 This allows to download some otherwise inaccessible files such as
5523 the ones within the $Extend folder.
5524 The filesystem from which to extract the file must be unmounted,
5526 otherwise the call will fail.
5527 $g->ntfsclone_in ($backupfile, $device);
5529 Restore the "backupfile" (from a previous call to
5530 "$g->ntfsclone_out") to "device", overwriting any existing contents
5531 of this device.
5532 This function depends on the feature "ntfs3g". See also
5534 "$g->feature-available".
5535 $g->ntfsclone_out ($device, $backupfile [, metadataonly =>
5537 $metadataonly] [, rescue => $rescue] [, ignorefscheck =>
5538 $ignorefscheck] [, preservetimestamps => $preservetimestamps] [, force
5539 => $force]);
5540 Stream the NTFS filesystem "device" to the local file "backupfile".
5541 The format used for the backup file is a special format used by the
5542 ntfsclone(8) tool.
5543 If the optional "metadataonly" flag is true, then only the metadata
5545 is saved, losing all the user data (this is useful for diagnosing
5546 some filesystem problems).
5547 The optional "rescue", "ignorefscheck", "preservetimestamps" and
5549 "force" flags have precise meanings detailed in the ntfsclone(8)
5550 man page.
5551 Use "$g->ntfsclone_in" to restore the file back to a libguestfs
5553 device.
5554 This function depends on the feature "ntfs3g". See also
5556 "$g->feature-available".
5557 $g->ntfsfix ($device [, clearbadsectors => $clearbadsectors]);
5559 This command repairs some fundamental NTFS inconsistencies, resets
5560 the NTFS journal file, and schedules an NTFS consistency check for
5561 the first boot into Windows.
5562 This is not an equivalent of Windows "chkdsk". It does not scan
5564 the filesystem for inconsistencies.
5565 The optional "clearbadsectors" flag clears the list of bad sectors.
5567 This is useful after cloning a disk with bad sectors to a new disk.
5568 This function depends on the feature "ntfs3g". See also
5570 "$g->feature-available".
5571 $g->ntfsresize ($device [, size => $size] [, force => $force]);
5573 This command resizes an NTFS filesystem, expanding or shrinking it
5574 to the size of the underlying device.
5575 The optional parameters are:
5577 "size"
5579 The new size (in bytes) of the filesystem. If omitted, the
5580 filesystem is resized to fit the container (eg. partition).
5581 "force"
5583 If this option is true, then force the resize of the filesystem
5584 even if the filesystem is marked as requiring a consistency
5585 check.
5586 After the resize operation, the filesystem is always marked as
5588 requiring a consistency check (for safety). You have to boot
5589 into Windows to perform this check and clear this condition.
5590 If you don't set the "force" option then it is not possible to
5591 call "$g->ntfsresize" multiple times on a single filesystem
5592 without booting into Windows between each resize.
5593 See also ntfsresize(8).
5595 This function depends on the feature "ntfsprogs". See also
5597 "$g->feature-available".
5598 $g->ntfsresize_opts ($device [, size => $size] [, force => $force]);
5600 This is an alias of "ntfsresize".
5601 $g->ntfsresize_size ($device, $size);
5603 This command is the same as "$g->ntfsresize" except that it allows
5604 you to specify the new size (in bytes) explicitly.
5605 This function depends on the feature "ntfsprogs". See also
5607 "$g->feature-available".
5608 This function is deprecated. In new code, use the "ntfsresize"
5610 call instead.
5611 Deprecated functions will not be removed from the API, but the fact
5613 that they are deprecated indicates that there are problems with
5614 correct use of these functions.
5615 $g->parse_environment ();
5617 Parse the program’s environment and set flags in the handle
5618 accordingly. For example if "LIBGUESTFS_DEBUG=1" then the
5619 ‘verbose’ flag is set in the handle.
5620 Most programs do not need to call this. It is done implicitly when
5622 you call "$g->create".
5623 See "ENVIRONMENT VARIABLES" in guestfs(3) for a list of environment
5625 variables that can affect libguestfs handles. See also
5626 "guestfs_create_flags" in guestfs(3), and
5627 "$g->parse_environment_list".
5628 $g->parse_environment_list (\@environment);
5630 Parse the list of strings in the argument "environment" and set
5631 flags in the handle accordingly. For example if
5632 "LIBGUESTFS_DEBUG=1" is a string in the list, then the ‘verbose’
5633 flag is set in the handle.
5634 This is the same as "$g->parse_environment" except that it parses
5636 an explicit list of strings instead of the program's environment.
5637 $g->part_add ($device, $prlogex, $startsect, $endsect);
5639 This command adds a partition to "device". If there is no
5640 partition table on the device, call "$g->part_init" first.
5641 The "prlogex" parameter is the type of partition. Normally you
5643 should pass "p" or "primary" here, but MBR partition tables also
5644 support "l" (or "logical") and "e" (or "extended") partition types.
5645 "startsect" and "endsect" are the start and end of the partition in
5647 sectors. "endsect" may be negative, which means it counts
5648 backwards from the end of the disk (-1 is the last sector).
5649 Creating a partition which covers the whole disk is not so easy.
5651 Use "$g->part_disk" to do that.
5652 $g->part_del ($device, $partnum);
5654 This command deletes the partition numbered "partnum" on "device".
5655 Note that in the case of MBR partitioning, deleting an extended
5657 partition also deletes any logical partitions it contains.
5658 $g->part_disk ($device, $parttype);
5660 This command is simply a combination of "$g->part_init" followed by
5661 "$g->part_add" to create a single primary partition covering the
5662 whole disk.
5663 "parttype" is the partition table type, usually "mbr" or "gpt", but
5665 other possible values are described in "$g->part_init".
5666 $g->part_expand_gpt ($device);
5668 Move backup GPT data structures to the end of the disk. This is
5669 useful in case of in-place image expand since disk space after
5670 backup GPT header is not usable. This is equivalent to "sgdisk
5671 -e".
5672 See also sgdisk(8).
5674 This function depends on the feature "gdisk". See also
5676 "$g->feature-available".
5677 $bootable = $g->part_get_bootable ($device, $partnum);
5679 This command returns true if the partition "partnum" on "device"
5680 has the bootable flag set.
5681 See also "$g->part_set_bootable".
5683 $guid = $g->part_get_disk_guid ($device);
5685 Return the disk identifier (GUID) of a GPT-partitioned "device".
5686 Behaviour is undefined for other partition types.
5687 This function depends on the feature "gdisk". See also
5689 "$g->feature-available".
5690 $attributes = $g->part_get_gpt_attributes ($device, $partnum);
5692 Return the attribute flags of numbered GPT partition "partnum". An
5693 error is returned for MBR partitions.
5694 This function depends on the feature "gdisk". See also
5696 "$g->feature-available".
5697 $guid = $g->part_get_gpt_guid ($device, $partnum);
5699 Return the GUID of numbered GPT partition "partnum".
5700 This function depends on the feature "gdisk". See also
5702 "$g->feature-available".
5703 $guid = $g->part_get_gpt_type ($device, $partnum);
5705 Return the type GUID of numbered GPT partition "partnum". For MBR
5706 partitions, return an appropriate GUID corresponding to the MBR
5707 type. Behaviour is undefined for other partition types.
5708 This function depends on the feature "gdisk". See also
5710 "$g->feature-available".
5711 $idbyte = $g->part_get_mbr_id ($device, $partnum);
5713 Returns the MBR type byte (also known as the ID byte) from the
5714 numbered partition "partnum".
5715 Note that only MBR (old DOS-style) partitions have type bytes. You
5717 will get undefined results for other partition table types (see
5718 "$g->part_get_parttype").
5719 $partitiontype = $g->part_get_mbr_part_type ($device, $partnum);
5721 This returns the partition type of an MBR partition numbered
5722 "partnum" on device "device".
5723 It returns "primary", "logical", or "extended".
5725 $name = $g->part_get_name ($device, $partnum);
5727 This gets the partition name on partition numbered "partnum" on
5728 device "device". Note that partitions are numbered from 1.
5729 The partition name can only be read on certain types of partition
5731 table. This works on "gpt" but not on "mbr" partitions.
5732 $parttype = $g->part_get_parttype ($device);
5734 This command examines the partition table on "device" and returns
5735 the partition table type (format) being used.
5736 Common return values include: "msdos" (a DOS/Windows style MBR
5738 partition table), "gpt" (a GPT/EFI-style partition table). Other
5739 values are possible, although unusual. See "$g->part_init" for a
5740 full list.
5741 $g->part_init ($device, $parttype);
5743 This creates an empty partition table on "device" of one of the
5744 partition types listed below. Usually "parttype" should be either
5745 "msdos" or "gpt" (for large disks).
5746 Initially there are no partitions. Following this, you should call
5748 "$g->part_add" for each partition required.
5749 Possible values for "parttype" are:
5751 "efi"
5753 "gpt"
5754 Intel EFI / GPT partition table.
5755 This is recommended for >= 2 TB partitions that will be
5757 accessed from Linux and Intel-based Mac OS X. It also has
5758 limited backwards compatibility with the "mbr" format.
5759 "mbr"
5761 "msdos"
5762 The standard PC "Master Boot Record" (MBR) format used by MS-
5763 DOS and Windows. This partition type will only work for device
5764 sizes up to 2 TB. For large disks we recommend using "gpt".
5765 Other partition table types that may work but are not supported
5767 include:
5768 "aix"
5770 AIX disk labels.
5771 "amiga"
5773 "rdb"
5774 Amiga "Rigid Disk Block" format.
5775 "bsd"
5777 BSD disk labels.
5778 "dasd"
5780 DASD, used on IBM mainframes.
5781 "dvh"
5783 MIPS/SGI volumes.
5784 "mac"
5786 Old Mac partition format. Modern Macs use "gpt".
5787 "pc98"
5789 NEC PC-98 format, common in Japan apparently.
5790 "sun"
5792 Sun disk labels.
5793 @partitions = $g->part_list ($device);
5795 This command parses the partition table on "device" and returns the
5796 list of partitions found.
5797 The fields in the returned structure are:
5799 "part_num"
5801 Partition number, counting from 1.
5802 "part_start"
5804 Start of the partition in bytes. To get sectors you have to
5805 divide by the device’s sector size, see "$g->blockdev_getss".
5806 "part_end"
5808 End of the partition in bytes.
5809 "part_size"
5811 Size of the partition in bytes.
5812 $g->part_resize ($device, $partnum, $endsect);
5814 This command resizes the partition numbered "partnum" on "device"
5815 by moving the end position.
5816 Note that this does not modify any filesystem present in the
5818 partition. If you wish to do this, you will need to use filesystem
5819 resizing commands like "$g->resize2fs".
5820 When growing a partition you will want to grow the filesystem
5822 afterwards, but when shrinking, you need to shrink the filesystem
5823 before the partition.
5824 $g->part_set_bootable ($device, $partnum, $bootable);
5826 This sets the bootable flag on partition numbered "partnum" on
5827 device "device". Note that partitions are numbered from 1.
5828 The bootable flag is used by some operating systems (notably
5830 Windows) to determine which partition to boot from. It is by no
5831 means universally recognized.
5832 $g->part_set_disk_guid ($device, $guid);
5834 Set the disk identifier (GUID) of a GPT-partitioned "device" to
5835 "guid". Return an error if the partition table of "device" isn't
5836 GPT, or if "guid" is not a valid GUID.
5837 This function depends on the feature "gdisk". See also
5839 "$g->feature-available".
5840 $g->part_set_disk_guid_random ($device);
5842 Set the disk identifier (GUID) of a GPT-partitioned "device" to a
5843 randomly generated value. Return an error if the partition table
5844 of "device" isn't GPT.
5845 This function depends on the feature "gdisk". See also
5847 "$g->feature-available".
5848 $g->part_set_gpt_attributes ($device, $partnum, $attributes);
5850 Set the attribute flags of numbered GPT partition "partnum" to
5851 "attributes". Return an error if the partition table of "device"
5852 isn't GPT.
5853 See
5855 <https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_entries>
5856 for a useful list of partition attributes.
5857 This function depends on the feature "gdisk". See also
5859 "$g->feature-available".
5860 $g->part_set_gpt_guid ($device, $partnum, $guid);
5862 Set the GUID of numbered GPT partition "partnum" to "guid". Return
5863 an error if the partition table of "device" isn't GPT, or if "guid"
5864 is not a valid GUID.
5865 This function depends on the feature "gdisk". See also
5867 "$g->feature-available".
5868 $g->part_set_gpt_type ($device, $partnum, $guid);
5870 Set the type GUID of numbered GPT partition "partnum" to "guid".
5871 Return an error if the partition table of "device" isn't GPT, or if
5872 "guid" is not a valid GUID.
5873 See
5875 <https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs>
5876 for a useful list of type GUIDs.
5877 This function depends on the feature "gdisk". See also
5879 "$g->feature-available".
5880 $g->part_set_mbr_id ($device, $partnum, $idbyte);
5882 Sets the MBR type byte (also known as the ID byte) of the numbered
5883 partition "partnum" to "idbyte". Note that the type bytes quoted
5884 in most documentation are in fact hexadecimal numbers, but usually
5885 documented without any leading "0x" which might be confusing.
5886 Note that only MBR (old DOS-style) partitions have type bytes. You
5888 will get undefined results for other partition table types (see
5889 "$g->part_get_parttype").
5890 $g->part_set_name ($device, $partnum, $name);
5892 This sets the partition name on partition numbered "partnum" on
5893 device "device". Note that partitions are numbered from 1.
5894 The partition name can only be set on certain types of partition
5896 table. This works on "gpt" but not on "mbr" partitions.
5897 $device = $g->part_to_dev ($partition);
5899 This function takes a partition name (eg. "/dev/sdb1") and removes
5900 the partition number, returning the device name (eg. "/dev/sdb").
5901 The named partition must exist, for example as a string returned
5903 from "$g->list_partitions".
5904 See also "$g->part_to_partnum", "$g->device_index".
5906 $partnum = $g->part_to_partnum ($partition);
5908 This function takes a partition name (eg. "/dev/sdb1") and returns
5909 the partition number (eg. 1).
5910 The named partition must exist, for example as a string returned
5912 from "$g->list_partitions".
5913 See also "$g->part_to_dev".
5915 $g->ping_daemon ();
5917 This is a test probe into the guestfs daemon running inside the
5918 libguestfs appliance. Calling this function checks that the daemon
5919 responds to the ping message, without affecting the daemon or
5920 attached block device(s) in any other way.
5921 $content = $g->pread ($path, $count, $offset);
5923 This command lets you read part of a file. It reads "count" bytes
5924 of the file, starting at "offset", from file "path".
5925 This may read fewer bytes than requested. For further details see
5927 the pread(2) system call.
5928 See also "$g->pwrite", "$g->pread_device".
5930 Because of the message protocol, there is a transfer limit of
5932 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5933 guestfs(3).
5934 $content = $g->pread_device ($device, $count, $offset);
5936 This command lets you read part of a block device. It reads
5937 "count" bytes of "device", starting at "offset".
5938 This may read fewer bytes than requested. For further details see
5940 the pread(2) system call.
5941 See also "$g->pread".
5943 Because of the message protocol, there is a transfer limit of
5945 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5946 guestfs(3).
5947 $g->pvchange_uuid ($device);
5949 Generate a new random UUID for the physical volume "device".
5950 This function depends on the feature "lvm2". See also
5952 "$g->feature-available".
5953 $g->pvchange_uuid_all ();
5955 Generate new random UUIDs for all physical volumes.
5956 This function depends on the feature "lvm2". See also
5958 "$g->feature-available".
5959 $g->pvcreate ($device);
5961 This creates an LVM physical volume on the named "device", where
5962 "device" should usually be a partition name such as /dev/sda1.
5963 This function depends on the feature "lvm2". See also
5965 "$g->feature-available".
5966 $g->pvremove ($device);
5968 This wipes a physical volume "device" so that LVM will no longer
5969 recognise it.
5970 The implementation uses the pvremove(8) command which refuses to
5972 wipe physical volumes that contain any volume groups, so you have
5973 to remove those first.
5974 This function depends on the feature "lvm2". See also
5976 "$g->feature-available".
5977 $g->pvresize ($device);
5979 This resizes (expands or shrinks) an existing LVM physical volume
5980 to match the new size of the underlying device.
5981 This function depends on the feature "lvm2". See also
5983 "$g->feature-available".
5984 $g->pvresize_size ($device, $size);
5986 This command is the same as "$g->pvresize" except that it allows
5987 you to specify the new size (in bytes) explicitly.
5988 This function depends on the feature "lvm2". See also
5990 "$g->feature-available".
5991 @physvols = $g->pvs ();
5993 List all the physical volumes detected. This is the equivalent of
5994 the pvs(8) command.
5995 This returns a list of just the device names that contain PVs (eg.
5997 /dev/sda2).
5998 See also "$g->pvs_full".
6000 This function depends on the feature "lvm2". See also
6002 "$g->feature-available".
6003 @physvols = $g->pvs_full ();
6005 List all the physical volumes detected. This is the equivalent of
6006 the pvs(8) command. The "full" version includes all fields.
6007 This function depends on the feature "lvm2". See also
6009 "$g->feature-available".
6010 $uuid = $g->pvuuid ($device);
6012 This command returns the UUID of the LVM PV "device".
6013 $nbytes = $g->pwrite ($path, $content, $offset);
6015 This command writes to part of a file. It writes the data buffer
6016 "content" to the file "path" starting at offset "offset".
6017 This command implements the pwrite(2) system call, and like that
6019 system call it may not write the full data requested. The return
6020 value is the number of bytes that were actually written to the
6021 file. This could even be 0, although short writes are unlikely for
6022 regular files in ordinary circumstances.
6023 See also "$g->pread", "$g->pwrite_device".
6025 Because of the message protocol, there is a transfer limit of
6027 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
6028 guestfs(3).
6029 $nbytes = $g->pwrite_device ($device, $content, $offset);
6031 This command writes to part of a device. It writes the data buffer
6032 "content" to "device" starting at offset "offset".
6033 This command implements the pwrite(2) system call, and like that
6035 system call it may not write the full data requested (although
6036 short writes to disk devices and partitions are probably impossible
6037 with standard Linux kernels).
6038 See also "$g->pwrite".
6040 Because of the message protocol, there is a transfer limit of
6042 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
6043 guestfs(3).
6044 $content = $g->read_file ($path);
6046 This calls returns the contents of the file "path" as a buffer.
6047 Unlike "$g->cat", this function can correctly handle files that
6049 contain embedded ASCII NUL characters.
6050 @lines = $g->read_lines ($path);
6052 Return the contents of the file named "path".
6053 The file contents are returned as a list of lines. Trailing "LF"
6055 and "CRLF" character sequences are not returned.
6056 Note that this function cannot correctly handle binary files
6058 (specifically, files containing "\0" character which is treated as
6059 end of string). For those you need to use the "$g->read_file"
6060 function and split the buffer into lines yourself.
6061 @entries = $g->readdir ($dir);
6063 This returns the list of directory entries in directory "dir".
6064 All entries in the directory are returned, including "." and "..".
6066 The entries are not sorted, but returned in the same order as the
6067 underlying filesystem.
6068 Also this call returns basic file type information about each file.
6070 The "ftyp" field will contain one of the following characters:
6071 'b' Block special
6073 'c' Char special
6075 'd' Directory
6077 'f' FIFO (named pipe)
6079 'l' Symbolic link
6081 'r' Regular file
6083 's' Socket
6085 'u' Unknown file type
6087 '?' The readdir(3) call returned a "d_type" field with an
6089 unexpected value
6090 This function is primarily intended for use by programs. To get a
6092 simple list of names, use "$g->ls". To get a printable directory
6093 for human consumption, use "$g->ll".
6094 $link = $g->readlink ($path);
6096 This command reads the target of a symbolic link.
6097 @links = $g->readlinklist ($path, \@names);
6099 This call allows you to do a "readlink" operation on multiple
6100 files, where all files are in the directory "path". "names" is the
6101 list of files from this directory.
6102 On return you get a list of strings, with a one-to-one
6104 correspondence to the "names" list. Each string is the value of
6105 the symbolic link.
6106 If the readlink(2) operation fails on any name, then the
6108 corresponding result string is the empty string "". However the
6109 whole operation is completed even if there were readlink(2) errors,
6110 and so you can call this function with names where you don't know
6111 if they are symbolic links already (albeit slightly less
6112 efficient).
6113 This call is intended for programs that want to efficiently list a
6115 directory contents without making many round-trips.
6116 $rpath = $g->realpath ($path);
6118 Return the canonicalized absolute pathname of "path". The returned
6119 path has no ".", ".." or symbolic link path elements.
6120 $g->remount ($mountpoint [, rw => $rw]);
6122 This call allows you to change the "rw" (readonly/read-write) flag
6123 on an already mounted filesystem at "mountpoint", converting a
6124 readonly filesystem to be read-write, or vice-versa.
6125 Note that at the moment you must supply the "optional" "rw"
6127 parameter. In future we may allow other flags to be adjusted.
6128 $g->remove_drive ($label);
6130 This call does nothing and returns an error.
6131 This function is deprecated. There is no replacement. Consult the
6133 API documentation in guestfs(3) for further information.
6134 Deprecated functions will not be removed from the API, but the fact
6136 that they are deprecated indicates that there are problems with
6137 correct use of these functions.
6138 $g->removexattr ($xattr, $path);
6140 This call removes the extended attribute named "xattr" of the file
6141 "path".
6142 See also: "$g->lremovexattr", attr(5).
6144 This function depends on the feature "linuxxattrs". See also
6146 "$g->feature-available".
6147 $g->rename ($oldpath, $newpath);
6149 Rename a file to a new place on the same filesystem. This is the
6150 same as the Linux rename(2) system call. In most cases you are
6151 better to use "$g->mv" instead.
6152 $g->resize2fs ($device);
6154 This resizes an ext2, ext3 or ext4 filesystem to match the size of
6155 the underlying device.
6156 See also "RESIZE2FS ERRORS" in guestfs(3).
6158 $g->resize2fs_M ($device);
6160 This command is the same as "$g->resize2fs", but the filesystem is
6161 resized to its minimum size. This works like the -M option to the
6162 resize2fs(8) command.
6163 To get the resulting size of the filesystem you should call
6165 "$g->tune2fs_l" and read the "Block size" and "Block count" values.
6166 These two numbers, multiplied together, give the resulting size of
6167 the minimal filesystem in bytes.
6168 See also "RESIZE2FS ERRORS" in guestfs(3).
6170 $g->resize2fs_size ($device, $size);
6172 This command is the same as "$g->resize2fs" except that it allows
6173 you to specify the new size (in bytes) explicitly.
6174 See also "RESIZE2FS ERRORS" in guestfs(3).
6176 $g->rm ($path);
6178 Remove the single file "path".
6179 $g->rm_f ($path);
6181 Remove the file "path".
6182 If the file doesn't exist, that error is ignored. (Other errors,
6184 eg. I/O errors or bad paths, are not ignored)
6185 This call cannot remove directories. Use "$g->rmdir" to remove an
6187 empty directory, or "$g->rm_rf" to remove directories recursively.
6188 $g->rm_rf ($path);
6190 Remove the file or directory "path", recursively removing the
6191 contents if its a directory. This is like the "rm -rf" shell
6192 command.
6193 $g->rmdir ($path);
6195 Remove the single directory "path".
6196 $g->rmmountpoint ($exemptpath);
6198 This call removes a mountpoint that was previously created with
6199 "$g->mkmountpoint". See "$g->mkmountpoint" for full details.
6200 $g->rsync ($src, $dest [, archive => $archive] [, deletedest =>
6202 $deletedest]);
6203 This call may be used to copy or synchronize two directories under
6204 the same libguestfs handle. This uses the rsync(1) program which
6205 uses a fast algorithm that avoids copying files unnecessarily.
6206 "src" and "dest" are the source and destination directories. Files
6208 are copied from "src" to "dest".
6209 The optional arguments are:
6211 "archive"
6213 Turns on archive mode. This is the same as passing the
6214 --archive flag to "rsync".
6215 "deletedest"
6217 Delete files at the destination that do not exist at the
6218 source.
6219 This function depends on the feature "rsync". See also
6221 "$g->feature-available".
6222 $g->rsync_in ($remote, $dest [, archive => $archive] [, deletedest =>
6224 $deletedest]);
6225 This call may be used to copy or synchronize the filesystem on the
6226 host or on a remote computer with the filesystem within libguestfs.
6227 This uses the rsync(1) program which uses a fast algorithm that
6228 avoids copying files unnecessarily.
6229 This call only works if the network is enabled. See
6231 "$g->set_network" or the --network option to various tools like
6232 guestfish(1).
6233 Files are copied from the remote server and directory specified by
6235 "remote" to the destination directory "dest".
6236 The format of the remote server string is defined by rsync(1).
6238 Note that there is no way to supply a password or passphrase so the
6239 target must be set up not to require one.
6240 The optional arguments are the same as those of "$g->rsync".
6242 This function depends on the feature "rsync". See also
6244 "$g->feature-available".
6245 $g->rsync_out ($src, $remote [, archive => $archive] [, deletedest =>
6247 $deletedest]);
6248 This call may be used to copy or synchronize the filesystem within
6249 libguestfs with a filesystem on the host or on a remote computer.
6250 This uses the rsync(1) program which uses a fast algorithm that
6251 avoids copying files unnecessarily.
6252 This call only works if the network is enabled. See
6254 "$g->set_network" or the --network option to various tools like
6255 guestfish(1).
6256 Files are copied from the source directory "src" to the remote
6258 server and directory specified by "remote".
6259 The format of the remote server string is defined by rsync(1).
6261 Note that there is no way to supply a password or passphrase so the
6262 target must be set up not to require one.
6263 The optional arguments are the same as those of "$g->rsync".
6265 Globbing does not happen on the "src" parameter. In programs which
6267 use the API directly you have to expand wildcards yourself (see
6268 "$g->glob_expand"). In guestfish you can use the "glob" command
6269 (see "glob" in guestfish(1)), for example:
6270 ><fs> glob rsync-out /* rsync://remote/
6272 This function depends on the feature "rsync". See also
6274 "$g->feature-available".
6275 $g->scrub_device ($device);
6277 This command writes patterns over "device" to make data retrieval
6278 more difficult.
6279 It is an interface to the scrub(1) program. See that manual page
6281 for more details.
6282 This function depends on the feature "scrub". See also
6284 "$g->feature-available".
6285 $g->scrub_file ($file);
6287 This command writes patterns over a file to make data retrieval
6288 more difficult.
6289 The file is removed after scrubbing.
6291 It is an interface to the scrub(1) program. See that manual page
6293 for more details.
6294 This function depends on the feature "scrub". See also
6296 "$g->feature-available".
6297 $g->scrub_freespace ($dir);
6299 This command creates the directory "dir" and then fills it with
6300 files until the filesystem is full, and scrubs the files as for
6301 "$g->scrub_file", and deletes them. The intention is to scrub any
6302 free space on the partition containing "dir".
6303 It is an interface to the scrub(1) program. See that manual page
6305 for more details.
6306 This function depends on the feature "scrub". See also
6308 "$g->feature-available".
6309 $g->selinux_relabel ($specfile, $path [, force => $force]);
6311 SELinux relabel parts of the filesystem.
6312 The "specfile" parameter controls the policy spec file used. You
6314 have to parse "/etc/selinux/config" to find the correct SELinux
6315 policy and then pass the spec file, usually: "/etc/selinux/" +
6316 selinuxtype + "/contexts/files/file_contexts".
6317 The required "path" parameter is the top level directory where
6319 relabelling starts. Normally you should pass "path" as "/" to
6320 relabel the whole guest filesystem.
6321 The optional "force" boolean controls whether the context is reset
6323 for customizable files, and also whether the user, role and range
6324 parts of the file context is changed.
6325 This function depends on the feature "selinuxrelabel". See also
6327 "$g->feature-available".
6328 $g->set_append ($append);
6330 This function is used to add additional options to the libguestfs
6331 appliance kernel command line.
6332 The default is "NULL" unless overridden by setting
6334 "LIBGUESTFS_APPEND" environment variable.
6335 Setting "append" to "NULL" means no additional options are passed
6337 (libguestfs always adds a few of its own).
6338 $g->set_attach_method ($backend);
6340 Set the method that libguestfs uses to connect to the backend
6341 guestfsd daemon.
6342 See "BACKEND" in guestfs(3).
6344 This function is deprecated. In new code, use the "set_backend"
6346 call instead.
6347 Deprecated functions will not be removed from the API, but the fact
6349 that they are deprecated indicates that there are problems with
6350 correct use of these functions.
6351 $g->set_autosync ($autosync);
6353 If "autosync" is true, this enables autosync. Libguestfs will make
6354 a best effort attempt to make filesystems consistent and
6355 synchronized when the handle is closed (also if the program exits
6356 without closing handles).
6357 This is enabled by default (since libguestfs 1.5.24, previously it
6359 was disabled by default).
6360 $g->set_backend ($backend);
6362 Set the method that libguestfs uses to connect to the backend
6363 guestfsd daemon.
6364 This handle property was previously called the "attach method".
6366 See "BACKEND" in guestfs(3).
6368 $g->set_backend_setting ($name, $val);
6370 Append "name=value" to the backend settings string list. However
6371 if a string already exists matching "name" or beginning with
6372 "name=", then that setting is replaced.
6373 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
6375 $g->set_backend_settings (\@settings);
6377 Set a list of zero or more settings which are passed through to the
6378 current backend. Each setting is a string which is interpreted in
6379 a backend-specific way, or ignored if not understood by the
6380 backend.
6381 The default value is an empty list, unless the environment variable
6383 "LIBGUESTFS_BACKEND_SETTINGS" was set when the handle was created.
6384 This environment variable contains a colon-separated list of
6385 settings.
6386 This call replaces all backend settings. If you want to replace a
6388 single backend setting, see "$g->set_backend_setting". If you want
6389 to clear a single backend setting, see "$g->clear_backend_setting".
6390 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
6392 $g->set_cachedir ($cachedir);
6394 Set the directory used by the handle to store the appliance cache,
6395 when using a supermin appliance. The appliance is cached and
6396 shared between all handles which have the same effective user ID.
6397 The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR"
6399 control the default value: If "LIBGUESTFS_CACHEDIR" is set, then
6400 that is the default. Else if "TMPDIR" is set, then that is the
6401 default. Else /var/tmp is the default.
6402 $g->set_direct ($direct);
6404 If the direct appliance mode flag is enabled, then stdin and stdout
6405 are passed directly through to the appliance once it is launched.
6406 One consequence of this is that log messages aren't caught by the
6408 library and handled by "$g->set_log_message_callback", but go
6409 straight to stdout.
6410 You probably don't want to use this unless you know what you are
6412 doing.
6413 The default is disabled.
6415 This function is deprecated. In new code, use the
6417 "internal_get_console_socket" call instead.
6418 Deprecated functions will not be removed from the API, but the fact
6420 that they are deprecated indicates that there are problems with
6421 correct use of these functions.
6422 $g->set_e2attrs ($file, $attrs [, clear => $clear]);
6424 This sets or clears the file attributes "attrs" associated with the
6425 inode file.
6426 "attrs" is a string of characters representing file attributes.
6428 See "$g->get_e2attrs" for a list of possible attributes. Not all
6429 attributes can be changed.
6430 If optional boolean "clear" is not present or false, then the
6432 "attrs" listed are set in the inode.
6433 If "clear" is true, then the "attrs" listed are cleared in the
6435 inode.
6436 In both cases, other attributes not present in the "attrs" string
6438 are left unchanged.
6439 These attributes are only present when the file is located on an
6441 ext2/3/4 filesystem. Using this call on other filesystem types
6442 will result in an error.
6443 $g->set_e2generation ($file, $generation);
6445 This sets the ext2 file generation of a file.
6446 See "$g->get_e2generation".
6448 $g->set_e2label ($device, $label);
6450 This sets the ext2/3/4 filesystem label of the filesystem on
6451 "device" to "label". Filesystem labels are limited to 16
6452 characters.
6453 You can use either "$g->tune2fs_l" or "$g->get_e2label" to return
6455 the existing label on a filesystem.
6456 This function is deprecated. In new code, use the "set_label" call
6458 instead.
6459 Deprecated functions will not be removed from the API, but the fact
6461 that they are deprecated indicates that there are problems with
6462 correct use of these functions.
6463 $g->set_e2uuid ($device, $uuid);
6465 This sets the ext2/3/4 filesystem UUID of the filesystem on
6466 "device" to "uuid". The format of the UUID and alternatives such
6467 as "clear", "random" and "time" are described in the tune2fs(8)
6468 manpage.
6469 You can use "$g->vfs_uuid" to return the existing UUID of a
6471 filesystem.
6472 This function is deprecated. In new code, use the "set_uuid" call
6474 instead.
6475 Deprecated functions will not be removed from the API, but the fact
6477 that they are deprecated indicates that there are problems with
6478 correct use of these functions.
6479 $g->set_hv ($hv);
6481 Set the hypervisor binary that we will use. The hypervisor depends
6482 on the backend, but is usually the location of the qemu/KVM
6483 hypervisor.
6484 The default is chosen when the library was compiled by the
6486 configure script.
6487 You can also override this by setting the "LIBGUESTFS_HV"
6489 environment variable.
6490 Note that you should call this function as early as possible after
6492 creating the handle. This is because some pre-launch operations
6493 depend on testing qemu features (by running "qemu -help"). If the
6494 qemu binary changes, we don't retest features, and so you might see
6495 inconsistent results. Using the environment variable
6496 "LIBGUESTFS_HV" is safest of all since that picks the qemu binary
6497 at the same time as the handle is created.
6498 $g->set_identifier ($identifier);
6500 This is an informative string which the caller may optionally set
6501 in the handle. It is printed in various places, allowing the
6502 current handle to be identified in debugging output.
6503 One important place is when tracing is enabled. If the identifier
6505 string is not an empty string, then trace messages change from
6506 this:
6507 libguestfs: trace: get_tmpdir
6509 libguestfs: trace: get_tmpdir = "/tmp"
6510 to this:
6512 libguestfs: trace: ID: get_tmpdir
6514 libguestfs: trace: ID: get_tmpdir = "/tmp"
6515 where "ID" is the identifier string set by this call.
6517 The identifier must only contain alphanumeric ASCII characters,
6519 underscore and minus sign. The default is the empty string.
6520 See also "$g->set_program", "$g->set_trace", "$g->get_identifier".
6522 $g->set_label ($mountable, $label);
6524 Set the filesystem label on "mountable" to "label".
6525 Only some filesystem types support labels, and libguestfs supports
6527 setting labels on only a subset of these.
6528 ext2, ext3, ext4
6530 Labels are limited to 16 bytes.
6531 NTFS
6533 Labels are limited to 128 unicode characters.
6534 XFS The label is limited to 12 bytes. The filesystem must not be
6536 mounted when trying to set the label.
6537 btrfs
6539 The label is limited to 255 bytes and some characters are not
6540 allowed. Setting the label on a btrfs subvolume will set the
6541 label on its parent filesystem. The filesystem must not be
6542 mounted when trying to set the label.
6543 fat The label is limited to 11 bytes.
6545 swap
6547 The label is limited to 16 bytes.
6548 If there is no support for changing the label for the type of the
6550 specified filesystem, set_label will fail and set errno as ENOTSUP.
6551 To read the label on a filesystem, call "$g->vfs_label".
6553 $g->set_libvirt_requested_credential ($index, $cred);
6555 After requesting the "index"'th credential from the user, call this
6556 function to pass the answer back to libvirt.
6557 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
6559 example code.
6560 $g->set_libvirt_supported_credentials (\@creds);
6562 Call this function before setting an event handler for
6563 "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential
6564 types that the program knows how to process.
6565 The "creds" list must be a non-empty list of strings. Possible
6567 strings are:
6568 "username"
6570 "authname"
6571 "language"
6572 "cnonce"
6573 "passphrase"
6574 "echoprompt"
6575 "noechoprompt"
6576 "realm"
6577 "external"
6578 See libvirt documentation for the meaning of these credential
6580 types.
6581 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
6583 example code.
6584 $g->set_memsize ($memsize);
6586 This sets the memory size in megabytes allocated to the hypervisor.
6587 This only has any effect if called before "$g->launch".
6588 You can also change this by setting the environment variable
6590 "LIBGUESTFS_MEMSIZE" before the handle is created.
6591 For more information on the architecture of libguestfs, see
6593 guestfs(3).
6594 $g->set_network ($network);
6596 If "network" is true, then the network is enabled in the libguestfs
6597 appliance. The default is false.
6598 This affects whether commands are able to access the network (see
6600 "RUNNING COMMANDS" in guestfs(3)).
6601 You must call this before calling "$g->launch", otherwise it has no
6603 effect.
6604 $g->set_path ($searchpath);
6606 Set the path that libguestfs searches for kernel and initrd.img.
6607 The default is "$libdir/guestfs" unless overridden by setting
6609 "LIBGUESTFS_PATH" environment variable.
6610 Setting "path" to "NULL" restores the default path.
6612 $g->set_pgroup ($pgroup);
6614 If "pgroup" is true, child processes are placed into their own
6615 process group.
6616 The practical upshot of this is that signals like "SIGINT" (from
6618 users pressing "^C") won't be received by the child process.
6619 The default for this flag is false, because usually you want "^C"
6621 to kill the subprocess. Guestfish sets this flag to true when used
6622 interactively, so that "^C" can cancel long-running commands
6623 gracefully (see "$g->user_cancel").
6624 $g->set_program ($program);
6626 Set the program name. This is an informative string which the main
6627 program may optionally set in the handle.
6628 When the handle is created, the program name in the handle is set
6630 to the basename from "argv[0]". The program name can never be
6631 "NULL".
6632 $g->set_qemu ($hv);
6634 Set the hypervisor binary (usually qemu) that we will use.
6635 The default is chosen when the library was compiled by the
6637 configure script.
6638 You can also override this by setting the "LIBGUESTFS_HV"
6640 environment variable.
6641 Setting "hv" to "NULL" restores the default qemu binary.
6643 Note that you should call this function as early as possible after
6645 creating the handle. This is because some pre-launch operations
6646 depend on testing qemu features (by running "qemu -help"). If the
6647 qemu binary changes, we don't retest features, and so you might see
6648 inconsistent results. Using the environment variable
6649 "LIBGUESTFS_HV" is safest of all since that picks the qemu binary
6650 at the same time as the handle is created.
6651 This function is deprecated. In new code, use the "set_hv" call
6653 instead.
6654 Deprecated functions will not be removed from the API, but the fact
6656 that they are deprecated indicates that there are problems with
6657 correct use of these functions.
6658 $g->set_recovery_proc ($recoveryproc);
6660 If this is called with the parameter "false" then "$g->launch" does
6661 not create a recovery process. The purpose of the recovery process
6662 is to stop runaway hypervisor processes in the case where the main
6663 program aborts abruptly.
6664 This only has any effect if called before "$g->launch", and the
6666 default is true.
6667 About the only time when you would want to disable this is if the
6669 main process will fork itself into the background ("daemonize"
6670 itself). In this case the recovery process thinks that the main
6671 program has disappeared and so kills the hypervisor, which is not
6672 very helpful.
6673 $g->set_selinux ($selinux);
6675 This sets the selinux flag that is passed to the appliance at boot
6676 time. The default is "selinux=0" (disabled).
6677 Note that if SELinux is enabled, it is always in Permissive mode
6679 ("enforcing=0").
6680 For more information on the architecture of libguestfs, see
6682 guestfs(3).
6683 This function is deprecated. In new code, use the
6685 "selinux_relabel" call instead.
6686 Deprecated functions will not be removed from the API, but the fact
6688 that they are deprecated indicates that there are problems with
6689 correct use of these functions.
6690 $g->set_smp ($smp);
6692 Change the number of virtual CPUs assigned to the appliance. The
6693 default is 1. Increasing this may improve performance, though
6694 often it has no effect.
6695 This function must be called before "$g->launch".
6697 $g->set_tmpdir ($tmpdir);
6699 Set the directory used by the handle to store temporary files.
6700 The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control
6702 the default value: If "LIBGUESTFS_TMPDIR" is set, then that is the
6703 default. Else if "TMPDIR" is set, then that is the default. Else
6704 /tmp is the default.
6705 $g->set_trace ($trace);
6707 If the command trace flag is set to 1, then libguestfs calls,
6708 parameters and return values are traced.
6709 If you want to trace C API calls into libguestfs (and other
6711 libraries) then possibly a better way is to use the external
6712 ltrace(1) command.
6713 Command traces are disabled unless the environment variable
6715 "LIBGUESTFS_TRACE" is defined and set to 1.
6716 Trace messages are normally sent to "stderr", unless you register a
6718 callback to send them somewhere else (see
6719 "$g->set_event_callback").
6720 $g->set_uuid ($device, $uuid);
6722 Set the filesystem UUID on "device" to "uuid". If this fails and
6723 the errno is ENOTSUP, means that there is no support for changing
6724 the UUID for the type of the specified filesystem.
6725 Only some filesystem types support setting UUIDs.
6727 To read the UUID on a filesystem, call "$g->vfs_uuid".
6729 $g->set_uuid_random ($device);
6731 Set the filesystem UUID on "device" to a random UUID. If this
6732 fails and the errno is ENOTSUP, means that there is no support for
6733 changing the UUID for the type of the specified filesystem.
6734 Only some filesystem types support setting UUIDs.
6736 To read the UUID on a filesystem, call "$g->vfs_uuid".
6738 $g->set_verbose ($verbose);
6740 If "verbose" is true, this turns on verbose messages.
6741 Verbose messages are disabled unless the environment variable
6743 "LIBGUESTFS_DEBUG" is defined and set to 1.
6744 Verbose messages are normally sent to "stderr", unless you register
6746 a callback to send them somewhere else (see
6747 "$g->set_event_callback").
6748 $g->setcon ($context);
6750 This sets the SELinux security context of the daemon to the string
6751 "context".
6752 See the documentation about SELINUX in guestfs(3).
6754 This function depends on the feature "selinux". See also
6756 "$g->feature-available".
6757 This function is deprecated. In new code, use the
6759 "selinux_relabel" call instead.
6760 Deprecated functions will not be removed from the API, but the fact
6762 that they are deprecated indicates that there are problems with
6763 correct use of these functions.
6764 $g->setxattr ($xattr, $val, $vallen, $path);
6766 This call sets the extended attribute named "xattr" of the file
6767 "path" to the value "val" (of length "vallen"). The value is
6768 arbitrary 8 bit data.
6769 See also: "$g->lsetxattr", attr(5).
6771 This function depends on the feature "linuxxattrs". See also
6773 "$g->feature-available".
6774 $g->sfdisk ($device, $cyls, $heads, $sectors, \@lines);
6776 This is a direct interface to the sfdisk(8) program for creating
6777 partitions on block devices.
6778 "device" should be a block device, for example /dev/sda.
6780 "cyls", "heads" and "sectors" are the number of cylinders, heads
6782 and sectors on the device, which are passed directly to sfdisk(8)
6783 as the -C, -H and -S parameters. If you pass 0 for any of these,
6784 then the corresponding parameter is omitted. Usually for ‘large’
6785 disks, you can just pass 0 for these, but for small (floppy-sized)
6786 disks, sfdisk(8) (or rather, the kernel) cannot work out the right
6787 geometry and you will need to tell it.
6788 "lines" is a list of lines that we feed to sfdisk(8). For more
6790 information refer to the sfdisk(8) manpage.
6791 To create a single partition occupying the whole disk, you would
6793 pass "lines" as a single element list, when the single element
6794 being the string "," (comma).
6795 See also: "$g->sfdisk_l", "$g->sfdisk_N", "$g->part_init"
6797 This function is deprecated. In new code, use the "part_add" call
6799 instead.
6800 Deprecated functions will not be removed from the API, but the fact
6802 that they are deprecated indicates that there are problems with
6803 correct use of these functions.
6804 $g->sfdiskM ($device, \@lines);
6806 This is a simplified interface to the "$g->sfdisk" command, where
6807 partition sizes are specified in megabytes only (rounded to the
6808 nearest cylinder) and you don't need to specify the cyls, heads and
6809 sectors parameters which were rarely if ever used anyway.
6810 See also: "$g->sfdisk", the sfdisk(8) manpage and "$g->part_disk"
6812 This function is deprecated. In new code, use the "part_add" call
6814 instead.
6815 Deprecated functions will not be removed from the API, but the fact
6817 that they are deprecated indicates that there are problems with
6818 correct use of these functions.
6819 $g->sfdisk_N ($device, $partnum, $cyls, $heads, $sectors, $line);
6821 This runs sfdisk(8) option to modify just the single partition "n"
6822 (note: "n" counts from 1).
6823 For other parameters, see "$g->sfdisk". You should usually pass 0
6825 for the cyls/heads/sectors parameters.
6826 See also: "$g->part_add"
6828 This function is deprecated. In new code, use the "part_add" call
6830 instead.
6831 Deprecated functions will not be removed from the API, but the fact
6833 that they are deprecated indicates that there are problems with
6834 correct use of these functions.
6835 $partitions = $g->sfdisk_disk_geometry ($device);
6837 This displays the disk geometry of "device" read from the partition
6838 table. Especially in the case where the underlying block device
6839 has been resized, this can be different from the kernel’s idea of
6840 the geometry (see "$g->sfdisk_kernel_geometry").
6841 The result is in human-readable format, and not designed to be
6843 parsed.
6844 $partitions = $g->sfdisk_kernel_geometry ($device);
6846 This displays the kernel’s idea of the geometry of "device".
6847 The result is in human-readable format, and not designed to be
6849 parsed.
6850 $partitions = $g->sfdisk_l ($device);
6852 This displays the partition table on "device", in the human-
6853 readable output of the sfdisk(8) command. It is not intended to be
6854 parsed.
6855 See also: "$g->part_list"
6857 This function is deprecated. In new code, use the "part_list" call
6859 instead.
6860 Deprecated functions will not be removed from the API, but the fact
6862 that they are deprecated indicates that there are problems with
6863 correct use of these functions.
6864 $output = $g->sh ($command);
6866 This call runs a command from the guest filesystem via the guest’s
6867 /bin/sh.
6868 This is like "$g->command", but passes the command to:
6870 /bin/sh -c "command"
6872 Depending on the guest’s shell, this usually results in wildcards
6874 being expanded, shell expressions being interpolated and so on.
6875 All the provisos about "$g->command" apply to this call.
6877 @lines = $g->sh_lines ($command);
6879 This is the same as "$g->sh", but splits the result into a list of
6880 lines.
6881 See also: "$g->command_lines"
6883 $g->shutdown ();
6885 This is the opposite of "$g->launch". It performs an orderly
6886 shutdown of the backend process(es). If the autosync flag is set
6887 (which is the default) then the disk image is synchronized.
6888 If the subprocess exits with an error then this function will
6890 return an error, which should not be ignored (it may indicate that
6891 the disk image could not be written out properly).
6892 It is safe to call this multiple times. Extra calls are ignored.
6894 This call does not close or free up the handle. You still need to
6896 call "$g->close" afterwards.
6897 "$g->close" will call this if you don't do it explicitly, but note
6899 that any errors are ignored in that case.
6900 $g->sleep ($secs);
6902 Sleep for "secs" seconds.
6903 %statbuf = $g->stat ($path);
6905 Returns file information for the given "path".
6906 This is the same as the stat(2) system call.
6908 This function is deprecated. In new code, use the "statns" call
6910 instead.
6911 Deprecated functions will not be removed from the API, but the fact
6913 that they are deprecated indicates that there are problems with
6914 correct use of these functions.
6915 %statbuf = $g->statns ($path);
6917 Returns file information for the given "path".
6918 This is the same as the stat(2) system call.
6920 %statbuf = $g->statvfs ($path);
6922 Returns file system statistics for any mounted file system. "path"
6923 should be a file or directory in the mounted file system (typically
6924 it is the mount point itself, but it doesn't need to be).
6925 This is the same as the statvfs(2) system call.
6927 @stringsout = $g->strings ($path);
6929 This runs the strings(1) command on a file and returns the list of
6930 printable strings found.
6931 The "strings" command has, in the past, had problems with parsing
6933 untrusted files. These are mitigated in the current version of
6934 libguestfs, but see "CVE-2014-8484" in guestfs(3).
6935 Because of the message protocol, there is a transfer limit of
6937 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
6938 guestfs(3).
6939 @stringsout = $g->strings_e ($encoding, $path);
6941 This is like the "$g->strings" command, but allows you to specify
6942 the encoding of strings that are looked for in the source file
6943 "path".
6944 Allowed encodings are:
6946 s Single 7-bit-byte characters like ASCII and the ASCII-
6948 compatible parts of ISO-8859-X (this is what "$g->strings"
6949 uses).
6950 S Single 8-bit-byte characters.
6952 b 16-bit big endian strings such as those encoded in UTF-16BE or
6954 UCS-2BE.
6955 l (lower case letter L)
6957 16-bit little endian such as UTF-16LE and UCS-2LE. This is
6958 useful for examining binaries in Windows guests.
6959 B 32-bit big endian such as UCS-4BE.
6961 L 32-bit little endian such as UCS-4LE.
6963 The returned strings are transcoded to UTF-8.
6965 The "strings" command has, in the past, had problems with parsing
6967 untrusted files. These are mitigated in the current version of
6968 libguestfs, but see "CVE-2014-8484" in guestfs(3).
6969 Because of the message protocol, there is a transfer limit of
6971 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
6972 guestfs(3).
6973 $g->swapoff_device ($device);
6975 This command disables the libguestfs appliance swap device or
6976 partition named "device". See "$g->swapon_device".
6977 $g->swapoff_file ($file);
6979 This command disables the libguestfs appliance swap on file.
6980 $g->swapoff_label ($label);
6982 This command disables the libguestfs appliance swap on labeled swap
6983 partition.
6984 $g->swapoff_uuid ($uuid);
6986 This command disables the libguestfs appliance swap partition with
6987 the given UUID.
6988 This function depends on the feature "linuxfsuuid". See also
6990 "$g->feature-available".
6991 $g->swapon_device ($device);
6993 This command enables the libguestfs appliance to use the swap
6994 device or partition named "device". The increased memory is made
6995 available for all commands, for example those run using
6996 "$g->command" or "$g->sh".
6997 Note that you should not swap to existing guest swap partitions
6999 unless you know what you are doing. They may contain hibernation
7000 information, or other information that the guest doesn't want you
7001 to trash. You also risk leaking information about the host to the
7002 guest this way. Instead, attach a new host device to the guest and
7003 swap on that.
7004 $g->swapon_file ($file);
7006 This command enables swap to a file. See "$g->swapon_device" for
7007 other notes.
7008 $g->swapon_label ($label);
7010 This command enables swap to a labeled swap partition. See
7011 "$g->swapon_device" for other notes.
7012 $g->swapon_uuid ($uuid);
7014 This command enables swap to a swap partition with the given UUID.
7015 See "$g->swapon_device" for other notes.
7016 This function depends on the feature "linuxfsuuid". See also
7018 "$g->feature-available".
7019 $g->sync ();
7021 This syncs the disk, so that any writes are flushed through to the
7022 underlying disk image.
7023 You should always call this if you have modified a disk image,
7025 before closing the handle.
7026 $g->syslinux ($device [, directory => $directory]);
7028 Install the SYSLINUX bootloader on "device".
7029 The device parameter must be either a whole disk formatted as a FAT
7031 filesystem, or a partition formatted as a FAT filesystem. In the
7032 latter case, the partition should be marked as "active"
7033 ("$g->part_set_bootable") and a Master Boot Record must be
7034 installed (eg. using "$g->pwrite_device") on the first sector of
7035 the whole disk. The SYSLINUX package comes with some suitable
7036 Master Boot Records. See the syslinux(1) man page for further
7037 information.
7038 The optional arguments are:
7040 directory
7042 Install SYSLINUX in the named subdirectory, instead of in the
7043 root directory of the FAT filesystem.
7044 Additional configuration can be supplied to SYSLINUX by placing a
7046 file called syslinux.cfg on the FAT filesystem, either in the root
7047 directory, or under directory if that optional argument is being
7048 used. For further information about the contents of this file, see
7049 syslinux(1).
7050 See also "$g->extlinux".
7052 This function depends on the feature "syslinux". See also
7054 "$g->feature-available".
7055 @lines = $g->tail ($path);
7057 This command returns up to the last 10 lines of a file as a list of
7058 strings.
7059 Because of the message protocol, there is a transfer limit of
7061 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7062 guestfs(3).
7063 @lines = $g->tail_n ($nrlines, $path);
7065 If the parameter "nrlines" is a positive number, this returns the
7066 last "nrlines" lines of the file "path".
7067 If the parameter "nrlines" is a negative number, this returns lines
7069 from the file "path", starting with the "-nrlines"'th line.
7070 If the parameter "nrlines" is zero, this returns an empty list.
7072 Because of the message protocol, there is a transfer limit of
7074 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7075 guestfs(3).
7076 $g->tar_in ($tarfile, $directory [, compress => $compress] [, xattrs =>
7078 $xattrs] [, selinux => $selinux] [, acls => $acls]);
7079 This command uploads and unpacks local file "tarfile" into
7080 directory.
7081 The optional "compress" flag controls compression. If not given,
7083 then the input should be an uncompressed tar file. Otherwise one
7084 of the following strings may be given to select the compression
7085 type of the input file: "compress", "gzip", "bzip2", "xz", "lzop".
7086 (Note that not all builds of libguestfs will support all of these
7087 compression types).
7088 The other optional arguments are:
7090 "xattrs"
7092 If set to true, extended attributes are restored from the tar
7093 file.
7094 "selinux"
7096 If set to true, SELinux contexts are restored from the tar
7097 file.
7098 "acls"
7100 If set to true, POSIX ACLs are restored from the tar file.
7101 $g->tar_in_opts ($tarfile, $directory [, compress => $compress] [,
7103 xattrs => $xattrs] [, selinux => $selinux] [, acls => $acls]);
7104 This is an alias of "tar_in".
7105 $g->tar_out ($directory, $tarfile [, compress => $compress] [,
7107 numericowner => $numericowner] [, excludes => $excludes] [, xattrs =>
7108 $xattrs] [, selinux => $selinux] [, acls => $acls]);
7109 This command packs the contents of directory and downloads it to
7110 local file "tarfile".
7111 The optional "compress" flag controls compression. If not given,
7113 then the output will be an uncompressed tar file. Otherwise one of
7114 the following strings may be given to select the compression type
7115 of the output file: "compress", "gzip", "bzip2", "xz", "lzop".
7116 (Note that not all builds of libguestfs will support all of these
7117 compression types).
7118 The other optional arguments are:
7120 "excludes"
7122 A list of wildcards. Files are excluded if they match any of
7123 the wildcards.
7124 "numericowner"
7126 If set to true, the output tar file will contain UID/GID
7127 numbers instead of user/group names.
7128 "xattrs"
7130 If set to true, extended attributes are saved in the output
7131 tar.
7132 "selinux"
7134 If set to true, SELinux contexts are saved in the output tar.
7135 "acls"
7137 If set to true, POSIX ACLs are saved in the output tar.
7138 $g->tar_out_opts ($directory, $tarfile [, compress => $compress] [,
7140 numericowner => $numericowner] [, excludes => $excludes] [, xattrs =>
7141 $xattrs] [, selinux => $selinux] [, acls => $acls]);
7142 This is an alias of "tar_out".
7143 $g->tgz_in ($tarball, $directory);
7145 This command uploads and unpacks local file "tarball" (a gzip
7146 compressed tar file) into directory.
7147 This function is deprecated. In new code, use the "tar_in" call
7149 instead.
7150 Deprecated functions will not be removed from the API, but the fact
7152 that they are deprecated indicates that there are problems with
7153 correct use of these functions.
7154 $g->tgz_out ($directory, $tarball);
7156 This command packs the contents of directory and downloads it to
7157 local file "tarball".
7158 This function is deprecated. In new code, use the "tar_out" call
7160 instead.
7161 Deprecated functions will not be removed from the API, but the fact
7163 that they are deprecated indicates that there are problems with
7164 correct use of these functions.
7165 $g->touch ($path);
7167 Touch acts like the touch(1) command. It can be used to update the
7168 timestamps on a file, or, if the file does not exist, to create a
7169 new zero-length file.
7170 This command only works on regular files, and will fail on other
7172 file types such as directories, symbolic links, block special etc.
7173 $g->truncate ($path);
7175 This command truncates "path" to a zero-length file. The file must
7176 exist already.
7177 $g->truncate_size ($path, $size);
7179 This command truncates "path" to size "size" bytes. The file must
7180 exist already.
7181 If the current file size is less than "size" then the file is
7183 extended to the required size with zero bytes. This creates a
7184 sparse file (ie. disk blocks are not allocated for the file until
7185 you write to it). To create a non-sparse file of zeroes, use
7186 "$g->fallocate64" instead.
7187 $g->tune2fs ($device [, force => $force] [, maxmountcount =>
7189 $maxmountcount] [, mountcount => $mountcount] [, errorbehavior =>
7190 $errorbehavior] [, group => $group] [, intervalbetweenchecks =>
7191 $intervalbetweenchecks] [, reservedblockspercentage =>
7192 $reservedblockspercentage] [, lastmounteddirectory =>
7193 $lastmounteddirectory] [, reservedblockscount => $reservedblockscount]
7194 [, user => $user]);
7195 This call allows you to adjust various filesystem parameters of an
7196 ext2/ext3/ext4 filesystem called "device".
7197 The optional parameters are:
7199 "force"
7201 Force tune2fs to complete the operation even in the face of
7202 errors. This is the same as the tune2fs(8) "-f" option.
7203 "maxmountcount"
7205 Set the number of mounts after which the filesystem is checked
7206 by e2fsck(8). If this is 0 then the number of mounts is
7207 disregarded. This is the same as the tune2fs(8) "-c" option.
7208 "mountcount"
7210 Set the number of times the filesystem has been mounted. This
7211 is the same as the tune2fs(8) "-C" option.
7212 "errorbehavior"
7214 Change the behavior of the kernel code when errors are
7215 detected. Possible values currently are: "continue",
7216 "remount-ro", "panic". In practice these options don't really
7217 make any difference, particularly for write errors.
7218 This is the same as the tune2fs(8) "-e" option.
7220 "group"
7222 Set the group which can use reserved filesystem blocks. This
7223 is the same as the tune2fs(8) "-g" option except that it can
7224 only be specified as a number.
7225 "intervalbetweenchecks"
7227 Adjust the maximal time between two filesystem checks (in
7228 seconds). If the option is passed as 0 then time-dependent
7229 checking is disabled.
7230 This is the same as the tune2fs(8) "-i" option.
7232 "reservedblockspercentage"
7234 Set the percentage of the filesystem which may only be
7235 allocated by privileged processes. This is the same as the
7236 tune2fs(8) "-m" option.
7237 "lastmounteddirectory"
7239 Set the last mounted directory. This is the same as the
7240 tune2fs(8) "-M" option.
7241 "reservedblockscount" Set the number of reserved filesystem blocks.
7243 This is the same as the tune2fs(8) "-r" option.
7244 "user"
7245 Set the user who can use the reserved filesystem blocks. This
7246 is the same as the tune2fs(8) "-u" option except that it can
7247 only be specified as a number.
7248 To get the current values of filesystem parameters, see
7250 "$g->tune2fs_l". For precise details of how tune2fs works, see the
7251 tune2fs(8) man page.
7252 %superblock = $g->tune2fs_l ($device);
7254 This returns the contents of the ext2, ext3 or ext4 filesystem
7255 superblock on "device".
7256 It is the same as running "tune2fs -l device". See tune2fs(8)
7258 manpage for more details. The list of fields returned isn't
7259 clearly defined, and depends on both the version of "tune2fs" that
7260 libguestfs was built against, and the filesystem itself.
7261 $g->txz_in ($tarball, $directory);
7263 This command uploads and unpacks local file "tarball" (an xz
7264 compressed tar file) into directory.
7265 This function depends on the feature "xz". See also
7267 "$g->feature-available".
7268 This function is deprecated. In new code, use the "tar_in" call
7270 instead.
7271 Deprecated functions will not be removed from the API, but the fact
7273 that they are deprecated indicates that there are problems with
7274 correct use of these functions.
7275 $g->txz_out ($directory, $tarball);
7277 This command packs the contents of directory and downloads it to
7278 local file "tarball" (as an xz compressed tar archive).
7279 This function depends on the feature "xz". See also
7281 "$g->feature-available".
7282 This function is deprecated. In new code, use the "tar_out" call
7284 instead.
7285 Deprecated functions will not be removed from the API, but the fact
7287 that they are deprecated indicates that there are problems with
7288 correct use of these functions.
7289 $oldmask = $g->umask ($mask);
7291 This function sets the mask used for creating new files and device
7292 nodes to "mask & 0777".
7293 Typical umask values would be 022 which creates new files with
7295 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which
7296 creates new files with permissions like "-rw-rw-r--" or
7297 "-rwxrwxr-x".
7298 The default umask is 022. This is important because it means that
7300 directories and device nodes will be created with 0644 or 0755 mode
7301 even if you specify 0777.
7302 See also "$g->get_umask", umask(2), "$g->mknod", "$g->mkdir".
7304 This call returns the previous umask.
7306 $g->umount ($pathordevice [, force => $force] [, lazyunmount =>
7308 $lazyunmount]);
7309 This unmounts the given filesystem. The filesystem may be
7310 specified either by its mountpoint (path) or the device which
7311 contains the filesystem.
7312 $g->umount_opts ($pathordevice [, force => $force] [, lazyunmount =>
7314 $lazyunmount]);
7315 This is an alias of "umount".
7316 $g->umount_all ();
7318 This unmounts all mounted filesystems.
7319 Some internal mounts are not unmounted by this call.
7321 $g->umount_local ([retry => $retry]);
7323 If libguestfs is exporting the filesystem on a local mountpoint,
7324 then this unmounts it.
7325 See "MOUNT LOCAL" in guestfs(3) for full documentation.
7327 $g->upload ($filename, $remotefilename);
7329 Upload local file filename to remotefilename on the filesystem.
7330 filename can also be a named pipe.
7332 See also "$g->download".
7334 $g->upload_offset ($filename, $remotefilename, $offset);
7336 Upload local file filename to remotefilename on the filesystem.
7337 remotefilename is overwritten starting at the byte "offset"
7339 specified. The intention is to overwrite parts of existing files
7340 or devices, although if a non-existent file is specified then it is
7341 created with a "hole" before "offset". The size of the data
7342 written is implicit in the size of the source filename.
7343 Note that there is no limit on the amount of data that can be
7345 uploaded with this call, unlike with "$g->pwrite", and this call
7346 always writes the full amount unless an error occurs.
7347 See also "$g->upload", "$g->pwrite".
7349 $g->user_cancel ();
7351 This function cancels the current upload or download operation.
7352 Unlike most other libguestfs calls, this function is signal safe
7354 and thread safe. You can call it from a signal handler or from
7355 another thread, without needing to do any locking.
7356 The transfer that was in progress (if there is one) will stop
7358 shortly afterwards, and will return an error. The errno (see
7359 "guestfs_last_errno") is set to "EINTR", so you can test for this
7360 to find out if the operation was cancelled or failed because of
7361 another error.
7362 No cleanup is performed: for example, if a file was being uploaded
7364 then after cancellation there may be a partially uploaded file. It
7365 is the caller’s responsibility to clean up if necessary.
7366 There are two common places that you might call "$g->user_cancel":
7368 In an interactive text-based program, you might call it from a
7370 "SIGINT" signal handler so that pressing "^C" cancels the current
7371 operation. (You also need to call "$g->set_pgroup" so that child
7372 processes don't receive the "^C" signal).
7373 In a graphical program, when the main thread is displaying a
7375 progress bar with a cancel button, wire up the cancel button to
7376 call this function.
7377 $g->utimens ($path, $atsecs, $atnsecs, $mtsecs, $mtnsecs);
7379 This command sets the timestamps of a file with nanosecond
7380 precision.
7381 "atsecs", "atnsecs" are the last access time (atime) in secs and
7383 nanoseconds from the epoch.
7384 "mtsecs", "mtnsecs" are the last modification time (mtime) in secs
7386 and nanoseconds from the epoch.
7387 If the *nsecs field contains the special value -1 then the
7389 corresponding timestamp is set to the current time. (The *secs
7390 field is ignored in this case).
7391 If the *nsecs field contains the special value -2 then the
7393 corresponding timestamp is left unchanged. (The *secs field is
7394 ignored in this case).
7395 %uts = $g->utsname ();
7397 This returns the kernel version of the appliance, where this is
7398 available. This information is only useful for debugging. Nothing
7399 in the returned structure is defined by the API.
7400 %version = $g->version ();
7402 Return the libguestfs version number that the program is linked
7403 against.
7404 Note that because of dynamic linking this is not necessarily the
7406 version of libguestfs that you compiled against. You can compile
7407 the program, and then at runtime dynamically link against a
7408 completely different libguestfs.so library.
7409 This call was added in version 1.0.58. In previous versions of
7411 libguestfs there was no way to get the version number. From C code
7412 you can use dynamic linker functions to find out if this symbol
7413 exists (if it doesn't, then it’s an earlier version).
7414 The call returns a structure with four elements. The first three
7416 ("major", "minor" and "release") are numbers and correspond to the
7417 usual version triplet. The fourth element ("extra") is a string
7418 and is normally empty, but may be used for distro-specific
7419 information.
7420 To construct the original version string:
7422 "$major.$minor.$release$extra"
7423 See also: "LIBGUESTFS VERSION NUMBERS" in guestfs(3).
7425 Note: Don't use this call to test for availability of features. In
7427 enterprise distributions we backport features from later versions
7428 into earlier versions, making this an unreliable way to test for
7429 features. Use "$g->available" or "$g->feature_available" instead.
7430 $label = $g->vfs_label ($mountable);
7432 This returns the label of the filesystem on "mountable".
7433 If the filesystem is unlabeled, this returns the empty string.
7435 To find a filesystem from the label, use "$g->findfs_label".
7437 $sizeinbytes = $g->vfs_minimum_size ($mountable);
7439 Get the minimum size of filesystem in bytes. This is the minimum
7440 possible size for filesystem shrinking.
7441 If getting minimum size of specified filesystem is not supported,
7443 this will fail and set errno as ENOTSUP.
7444 See also ntfsresize(8), resize2fs(8), btrfs(8), xfs_info(8).
7446 $fstype = $g->vfs_type ($mountable);
7448 This command gets the filesystem type corresponding to the
7449 filesystem on "mountable".
7450 For most filesystems, the result is the name of the Linux VFS
7452 module which would be used to mount this filesystem if you mounted
7453 it without specifying the filesystem type. For example a string
7454 such as "ext3" or "ntfs".
7455 $uuid = $g->vfs_uuid ($mountable);
7457 This returns the filesystem UUID of the filesystem on "mountable".
7458 If the filesystem does not have a UUID, this returns the empty
7460 string.
7461 To find a filesystem from the UUID, use "$g->findfs_uuid".
7463 $g->vg_activate ($activate, \@volgroups);
7465 This command activates or (if "activate" is false) deactivates all
7466 logical volumes in the listed volume groups "volgroups".
7467 This command is the same as running "vgchange -a y|n volgroups..."
7469 Note that if "volgroups" is an empty list then all volume groups
7471 are activated or deactivated.
7472 This function depends on the feature "lvm2". See also
7474 "$g->feature-available".
7475 $g->vg_activate_all ($activate);
7477 This command activates or (if "activate" is false) deactivates all
7478 logical volumes in all volume groups.
7479 This command is the same as running "vgchange -a y|n"
7481 This function depends on the feature "lvm2". See also
7483 "$g->feature-available".
7484 $g->vgchange_uuid ($vg);
7486 Generate a new random UUID for the volume group "vg".
7487 This function depends on the feature "lvm2". See also
7489 "$g->feature-available".
7490 $g->vgchange_uuid_all ();
7492 Generate new random UUIDs for all volume groups.
7493 This function depends on the feature "lvm2". See also
7495 "$g->feature-available".
7496 $g->vgcreate ($volgroup, \@physvols);
7498 This creates an LVM volume group called "volgroup" from the non-
7499 empty list of physical volumes "physvols".
7500 This function depends on the feature "lvm2". See also
7502 "$g->feature-available".
7503 @uuids = $g->vglvuuids ($vgname);
7505 Given a VG called "vgname", this returns the UUIDs of all the
7506 logical volumes created in this volume group.
7507 You can use this along with "$g->lvs" and "$g->lvuuid" calls to
7509 associate logical volumes and volume groups.
7510 See also "$g->vgpvuuids".
7512 $metadata = $g->vgmeta ($vgname);
7514 "vgname" is an LVM volume group. This command examines the volume
7515 group and returns its metadata.
7516 Note that the metadata is an internal structure used by LVM,
7518 subject to change at any time, and is provided for information
7519 only.
7520 This function depends on the feature "lvm2". See also
7522 "$g->feature-available".
7523 @uuids = $g->vgpvuuids ($vgname);
7525 Given a VG called "vgname", this returns the UUIDs of all the
7526 physical volumes that this volume group resides on.
7527 You can use this along with "$g->pvs" and "$g->pvuuid" calls to
7529 associate physical volumes and volume groups.
7530 See also "$g->vglvuuids".
7532 $g->vgremove ($vgname);
7534 Remove an LVM volume group "vgname", (for example "VG").
7535 This also forcibly removes all logical volumes in the volume group
7537 (if any).
7538 This function depends on the feature "lvm2". See also
7540 "$g->feature-available".
7541 $g->vgrename ($volgroup, $newvolgroup);
7543 Rename a volume group "volgroup" with the new name "newvolgroup".
7544 @volgroups = $g->vgs ();
7546 List all the volumes groups detected. This is the equivalent of
7547 the vgs(8) command.
7548 This returns a list of just the volume group names that were
7550 detected (eg. "VolGroup00").
7551 See also "$g->vgs_full".
7553 This function depends on the feature "lvm2". See also
7555 "$g->feature-available".
7556 @volgroups = $g->vgs_full ();
7558 List all the volumes groups detected. This is the equivalent of
7559 the vgs(8) command. The "full" version includes all fields.
7560 This function depends on the feature "lvm2". See also
7562 "$g->feature-available".
7563 $g->vgscan ();
7565 This rescans all block devices and rebuilds the list of LVM
7566 physical volumes, volume groups and logical volumes.
7567 This function is deprecated. In new code, use the "lvm_scan" call
7569 instead.
7570 Deprecated functions will not be removed from the API, but the fact
7572 that they are deprecated indicates that there are problems with
7573 correct use of these functions.
7574 $uuid = $g->vguuid ($vgname);
7576 This command returns the UUID of the LVM VG named "vgname".
7577 $g->wait_ready ();
7579 This function is a no op.
7580 In versions of the API < 1.0.71 you had to call this function just
7582 after calling "$g->launch" to wait for the launch to complete.
7583 However this is no longer necessary because "$g->launch" now does
7584 the waiting.
7585 If you see any calls to this function in code then you can just
7587 remove them, unless you want to retain compatibility with older
7588 versions of the API.
7589 This function is deprecated. There is no replacement. Consult the
7591 API documentation in guestfs(3) for further information.
7592 Deprecated functions will not be removed from the API, but the fact
7594 that they are deprecated indicates that there are problems with
7595 correct use of these functions.
7596 $chars = $g->wc_c ($path);
7598 This command counts the characters in a file, using the "wc -c"
7599 external command.
7600 $lines = $g->wc_l ($path);
7602 This command counts the lines in a file, using the "wc -l" external
7603 command.
7604 $words = $g->wc_w ($path);
7606 This command counts the words in a file, using the "wc -w" external
7607 command.
7608 $g->wipefs ($device);
7610 This command erases filesystem or RAID signatures from the
7611 specified "device" to make the filesystem invisible to libblkid.
7612 This does not erase the filesystem itself nor any other data from
7614 the "device".
7615 Compare with "$g->zero" which zeroes the first few blocks of a
7617 device.
7618 This function depends on the feature "wipefs". See also
7620 "$g->feature-available".
7621 $g->write ($path, $content);
7623 This call creates a file called "path". The content of the file is
7624 the string "content" (which can contain any 8 bit data).
7625 See also "$g->write_append".
7627 $g->write_append ($path, $content);
7629 This call appends "content" to the end of file "path". If "path"
7630 does not exist, then a new file is created.
7631 See also "$g->write".
7633 $g->write_file ($path, $content, $size);
7635 This call creates a file called "path". The contents of the file
7636 is the string "content" (which can contain any 8 bit data), with
7637 length "size".
7638 As a special case, if "size" is 0 then the length is calculated
7640 using "strlen" (so in this case the content cannot contain embedded
7641 ASCII NULs).
7642 NB. Owing to a bug, writing content containing ASCII NUL characters
7644 does not work, even if the length is specified.
7645 Because of the message protocol, there is a transfer limit of
7647 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7648 guestfs(3).
7649 This function is deprecated. In new code, use the "write" call
7651 instead.
7652 Deprecated functions will not be removed from the API, but the fact
7654 that they are deprecated indicates that there are problems with
7655 correct use of these functions.
7656 $g->xfs_admin ($device [, extunwritten => $extunwritten] [, imgfile =>
7658 $imgfile] [, v2log => $v2log] [, projid32bit => $projid32bit] [,
7659 lazycounter => $lazycounter] [, label => $label] [, uuid => $uuid]);
7660 Change the parameters of the XFS filesystem on "device".
7661 Devices that are mounted cannot be modified. Administrators must
7663 unmount filesystems before this call can modify parameters.
7664 Some of the parameters of a mounted filesystem can be examined and
7666 modified using the "$g->xfs_info" and "$g->xfs_growfs" calls.
7667 Beginning with XFS version 5, it is no longer possible to modify
7669 the lazy-counters setting (ie. "lazycounter" parameter has no
7670 effect).
7671 This function depends on the feature "xfs". See also
7673 "$g->feature-available".
7674 $g->xfs_growfs ($path [, datasec => $datasec] [, logsec => $logsec] [,
7676 rtsec => $rtsec] [, datasize => $datasize] [, logsize => $logsize] [,
7677 rtsize => $rtsize] [, rtextsize => $rtextsize] [, maxpct => $maxpct]);
7678 Grow the XFS filesystem mounted at "path".
7679 The returned struct contains geometry information. Missing fields
7681 are returned as -1 (for numeric fields) or empty string.
7682 This function depends on the feature "xfs". See also
7684 "$g->feature-available".
7685 %info = $g->xfs_info ($pathordevice);
7687 "pathordevice" is a mounted XFS filesystem or a device containing
7688 an XFS filesystem. This command returns the geometry of the
7689 filesystem.
7690 The returned struct contains geometry information. Missing fields
7692 are returned as -1 (for numeric fields) or empty string.
7693 This function depends on the feature "xfs". See also
7695 "$g->feature-available".
7696 $status = $g->xfs_repair ($device [, forcelogzero => $forcelogzero] [,
7698 nomodify => $nomodify] [, noprefetch => $noprefetch] [, forcegeometry
7699 => $forcegeometry] [, maxmem => $maxmem] [, ihashsize => $ihashsize] [,
7700 bhashsize => $bhashsize] [, agstride => $agstride] [, logdev =>
7701 $logdev] [, rtdev => $rtdev]);
7702 Repair corrupt or damaged XFS filesystem on "device".
7703 The filesystem is specified using the "device" argument which
7705 should be the device name of the disk partition or volume
7706 containing the filesystem. If given the name of a block device,
7707 "xfs_repair" will attempt to find the raw device associated with
7708 the specified block device and will use the raw device instead.
7709 Regardless, the filesystem to be repaired must be unmounted,
7711 otherwise, the resulting filesystem may be inconsistent or corrupt.
7712 The returned status indicates whether filesystem corruption was
7714 detected (returns 1) or was not detected (returns 0).
7715 This function depends on the feature "xfs". See also
7717 "$g->feature-available".
7718 $g->yara_destroy ();
7720 Destroy previously loaded Yara rules in order to free libguestfs
7721 resources.
7722 This function depends on the feature "libyara". See also
7724 "$g->feature-available".
7725 $g->yara_load ($filename);
7727 Upload a set of Yara rules from local file filename.
7728 Yara rules allow to categorize files based on textual or binary
7730 patterns within their content. See "$g->yara_scan" to see how to
7731 scan files with the loaded rules.
7732 Rules can be in binary format, as when compiled with yarac command,
7734 or in source code format. In the latter case, the rules will be
7735 first compiled and then loaded.
7736 Rules in source code format cannot include external files. In such
7738 cases, it is recommended to compile them first.
7739 Previously loaded rules will be destroyed.
7741 This function depends on the feature "libyara". See also
7743 "$g->feature-available".
7744 @detections = $g->yara_scan ($path);
7746 Scan a file with the previously loaded Yara rules.
7747 For each matching rule, a "yara_detection" structure is returned.
7749 The "yara_detection" structure contains the following fields.
7751 "yara_name"
7753 Path of the file matching a Yara rule.
7754 "yara_rule"
7756 Identifier of the Yara rule which matched against the given
7757 file.
7758 This function depends on the feature "libyara". See also
7760 "$g->feature-available".
7761 @lines = $g->zegrep ($regex, $path);
7763 This calls the external "zegrep" program and returns the matching
7764 lines.
7765 Because of the message protocol, there is a transfer limit of
7767 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7768 guestfs(3).
7769 This function is deprecated. In new code, use the "grep" call
7771 instead.
7772 Deprecated functions will not be removed from the API, but the fact
7774 that they are deprecated indicates that there are problems with
7775 correct use of these functions.
7776 @lines = $g->zegrepi ($regex, $path);
7778 This calls the external "zegrep -i" program and returns the
7779 matching lines.
7780 Because of the message protocol, there is a transfer limit of
7782 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7783 guestfs(3).
7784 This function is deprecated. In new code, use the "grep" call
7786 instead.
7787 Deprecated functions will not be removed from the API, but the fact
7789 that they are deprecated indicates that there are problems with
7790 correct use of these functions.
7791 $g->zero ($device);
7793 This command writes zeroes over the first few blocks of "device".
7794 How many blocks are zeroed isn't specified (but it’s not enough to
7796 securely wipe the device). It should be sufficient to remove any
7797 partition tables, filesystem superblocks and so on.
7798 If blocks are already zero, then this command avoids writing
7800 zeroes. This prevents the underlying device from becoming non-
7801 sparse or growing unnecessarily.
7802 See also: "$g->zero_device", "$g->scrub_device",
7804 "$g->is_zero_device"
7805 $g->zero_device ($device);
7807 This command writes zeroes over the entire "device". Compare with
7808 "$g->zero" which just zeroes the first few blocks of a device.
7809 If blocks are already zero, then this command avoids writing
7811 zeroes. This prevents the underlying device from becoming non-
7812 sparse or growing unnecessarily.
7813 $g->zero_free_space ($directory);
7815 Zero the free space in the filesystem mounted on directory. The
7816 filesystem must be mounted read-write.
7817 The filesystem contents are not affected, but any free space in the
7819 filesystem is freed.
7820 Free space is not "trimmed". You may want to call "$g->fstrim"
7822 either as an alternative to this, or after calling this, depending
7823 on your requirements.
7824 $g->zerofree ($device);
7826 This runs the zerofree program on "device". This program claims to
7827 zero unused inodes and disk blocks on an ext2/3 filesystem, thus
7828 making it possible to compress the filesystem more effectively.
7829 You should not run this program if the filesystem is mounted.
7831 It is possible that using this program can damage the filesystem or
7833 data on the filesystem.
7834 This function depends on the feature "zerofree". See also
7836 "$g->feature-available".
7837 @lines = $g->zfgrep ($pattern, $path);
7839 This calls the external "zfgrep" program and returns the matching
7840 lines.
7841 Because of the message protocol, there is a transfer limit of
7843 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7844 guestfs(3).
7845 This function is deprecated. In new code, use the "grep" call
7847 instead.
7848 Deprecated functions will not be removed from the API, but the fact
7850 that they are deprecated indicates that there are problems with
7851 correct use of these functions.
7852 @lines = $g->zfgrepi ($pattern, $path);
7854 This calls the external "zfgrep -i" program and returns the
7855 matching lines.
7856 Because of the message protocol, there is a transfer limit of
7858 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7859 guestfs(3).
7860 This function is deprecated. In new code, use the "grep" call
7862 instead.
7863 Deprecated functions will not be removed from the API, but the fact
7865 that they are deprecated indicates that there are problems with
7866 correct use of these functions.
7867 $description = $g->zfile ($meth, $path);
7869 This command runs file(1) after first decompressing "path" using
7870 "meth".
7871 "meth" must be one of "gzip", "compress" or "bzip2".
7873 Since 1.0.63, use "$g->file" instead which can now process
7875 compressed files.
7876 This function is deprecated. In new code, use the "file" call
7878 instead.
7879 Deprecated functions will not be removed from the API, but the fact
7881 that they are deprecated indicates that there are problems with
7882 correct use of these functions.
7883 @lines = $g->zgrep ($regex, $path);
7885 This calls the external zgrep(1) program and returns the matching
7886 lines.
7887 Because of the message protocol, there is a transfer limit of
7889 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7890 guestfs(3).
7891 This function is deprecated. In new code, use the "grep" call
7893 instead.
7894 Deprecated functions will not be removed from the API, but the fact
7896 that they are deprecated indicates that there are problems with
7897 correct use of these functions.
7898 @lines = $g->zgrepi ($regex, $path);
7900 This calls the external "zgrep -i" program and returns the matching
7901 lines.
7902 Because of the message protocol, there is a transfer limit of
7904 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7905 guestfs(3).
7906 This function is deprecated. In new code, use the "grep" call
7908 instead.
7909 Deprecated functions will not be removed from the API, but the fact
7911 that they are deprecated indicates that there are problems with
7912 correct use of these functions.
7913
7915 From time to time we add new libguestfs APIs. Also some libguestfs
7916 APIs won't be available in all builds of libguestfs (the Fedora build
7917 is full-featured, but other builds may disable features). How do you
7918 test whether the APIs that your Perl program needs are available in the
7919 version of "Sys::Guestfs" that you are using?
7920 To test if a particular function is available in the "Sys::Guestfs"
7922 class, use the ordinary Perl UNIVERSAL method can(METHOD) (see
7923 perlobj(1)). For example:
7924 use Sys::Guestfs;
7926 if (defined (Sys::Guestfs->can ("set_verbose"))) {
7927 print "\$g->set_verbose is available\n";
7928 }
7929 To test if particular features are supported by the current build, use
7931 the "feature_available" method like the example below. Note that the
7932 appliance must be launched first.
7933 $g->feature_available ( ["augeas"] );
7935 For further discussion on this topic, refer to "AVAILABILITY" in
7937 guestfs(3).
7938
7940 The handle returned from "new" is a hash reference. The hash normally
7941 contains some elements:
7942 {
7944 _g => [private data used by libguestfs],
7945 _flags => [flags provided when creating the handle]
7946 }
7947 Callers can add other elements to this hash to store data for their own
7949 purposes. The data lasts for the lifetime of the handle.
7950 Any fields whose names begin with an underscore are reserved for
7952 private use by libguestfs. We may add more in future.
7953 It is recommended that callers prefix the name of their field(s) with
7955 some unique string, to avoid conflicts with other users.
7956
7958 Copyright (C) 2009-2023 Red Hat Inc.
7959
7961 Please see the file COPYING.LIB for the full license.
7962
7964 guestfs(3), guestfish(1), <http://libguestfs.org>.
7965perl v5.36.0 2023-02-21 Sys::Guestfs(3)