1Sys::Guestfs(3) User Contributed Perl Documentation Sys::Guestfs(3)
2
6 Sys::Guestfs - Perl bindings for libguestfs
7
9 use Sys::Guestfs;
10 my $g = Sys::Guestfs->new ();
12 $g->add_drive_opts ('guest.img', format => 'raw');
13 $g->launch ();
14 $g->mount ('/dev/sda1', '/');
15 $g->touch ('/hello');
16 $g->shutdown ();
17 $g->close ();
18
20 The "Sys::Guestfs" module provides a Perl XS binding to the libguestfs
21 API for examining and modifying virtual machine disk images.
22 Amongst the things this is good for: making batch configuration changes
24 to guests, getting disk used/free statistics (see also: virt-df),
25 migrating between virtualization systems (see also: virt-p2v),
26 performing partial backups, performing partial guest clones, cloning
27 guests and changing registry/UUID/hostname info, and much else besides.
28 Libguestfs uses Linux kernel and qemu code, and can access any type of
30 guest filesystem that Linux and qemu can, including but not limited to:
31 ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
32 schemes, qcow, qcow2, vmdk.
33 Libguestfs provides ways to enumerate guest storage (eg. partitions,
35 LVs, what filesystem is in each LV, etc.). It can also run commands in
36 the context of the guest. Also you can access filesystems over FUSE.
37
39 All errors turn into calls to "croak" (see Carp(3)).
40 The error string from libguestfs is directly available from $@. Use
42 the "last_errno" method if you want to get the errno.
43
45 $g = Sys::Guestfs->new ([environment => 0,] [close_on_exit => 0]);
46 Create a new guestfs handle.
47 If the optional argument "environment" is false, then the
49 "GUESTFS_CREATE_NO_ENVIRONMENT" flag is set.
50 If the optional argument "close_on_exit" is false, then the
52 "GUESTFS_CREATE_NO_CLOSE_ON_EXIT" flag is set.
53 $g->close ();
55 Explicitly close the guestfs handle.
56 Note: You should not usually call this function. The handle will
58 be closed implicitly when its reference count goes to zero (eg.
59 when it goes out of scope or the program ends). This call is only
60 required in some exceptional cases, such as where the program may
61 contain cached references to the handle 'somewhere' and you really
62 have to have the close happen right away. After calling "close"
63 the program must not call any method (including "close") on the
64 handle (but the implicit call to "DESTROY" that happens when the
65 final reference is cleaned up is OK).
66 $Sys::Guestfs::EVENT_CLOSE
68 See "GUESTFS_EVENT_CLOSE" in guestfs(3).
69 $Sys::Guestfs::EVENT_SUBPROCESS_QUIT
71 See "GUESTFS_EVENT_SUBPROCESS_QUIT" in guestfs(3).
72 $Sys::Guestfs::EVENT_LAUNCH_DONE
74 See "GUESTFS_EVENT_LAUNCH_DONE" in guestfs(3).
75 $Sys::Guestfs::EVENT_PROGRESS
77 See "GUESTFS_EVENT_PROGRESS" in guestfs(3).
78 $Sys::Guestfs::EVENT_APPLIANCE
80 See "GUESTFS_EVENT_APPLIANCE" in guestfs(3).
81 $Sys::Guestfs::EVENT_LIBRARY
83 See "GUESTFS_EVENT_LIBRARY" in guestfs(3).
84 $Sys::Guestfs::EVENT_TRACE
86 See "GUESTFS_EVENT_TRACE" in guestfs(3).
87 $Sys::Guestfs::EVENT_ENTER
89 See "GUESTFS_EVENT_ENTER" in guestfs(3).
90 $Sys::Guestfs::EVENT_LIBVIRT_AUTH
92 See "GUESTFS_EVENT_LIBVIRT_AUTH" in guestfs(3).
93 $Sys::Guestfs::EVENT_WARNING
95 See "GUESTFS_EVENT_WARNING" in guestfs(3).
96 $Sys::Guestfs::EVENT_ALL
98 See "GUESTFS_EVENT_ALL" in guestfs(3).
99 $event_handle = $g->set_event_callback (\&cb, $event_bitmask);
101 Register "cb" as a callback function for all of the events in
102 $event_bitmask (one or more "$Sys::Guestfs::EVENT_*" flags
103 logically or'd together).
104 This function returns an event handle which can be used to delete
106 the callback using "delete_event_callback".
107 The callback function receives 4 parameters:
109 &cb ($event, $event_handle, $buf, $array)
111 $event
113 The event which happened (equal to one of
114 "$Sys::Guestfs::EVENT_*").
115 $event_handle
117 The event handle.
118 $buf
120 For some event types, this is a message buffer (ie. a string).
121 $array
123 For some event types (notably progress events), this is an
124 array of integers.
125 You should carefully read the documentation for
127 "guestfs_set_event_callback" in guestfs(3) before using this
128 function.
129 $g->delete_event_callback ($event_handle);
131 This removes the callback which was previously registered using
132 "set_event_callback".
133 $str = Sys::Guestfs::event_to_string ($events);
135 $events is either a single event or a bitmask of events. This
136 returns a printable string, useful for debugging.
137 Note that this is a class function, not a method.
139 $errnum = $g->last_errno ();
141 This returns the last error number (errno) that happened on the
142 handle $g.
143 If successful, an errno integer not equal to zero is returned.
145 If no error number is available, this returns 0. See
147 "guestfs_last_errno" in guestfs(3) for more details of why this can
148 happen.
149 You can use the standard Perl module Errno(3) to compare the
151 numeric error returned from this call with symbolic errnos:
152 $g->mkdir ("/foo");
154 if ($g->last_errno() == Errno::EEXIST()) {
155 # mkdir failed because the directory exists already.
156 }
157 $g->acl_delete_def_file ($dir);
159 This function deletes the default POSIX Access Control List (ACL)
160 attached to directory "dir".
161 This function depends on the feature "acl". See also
163 "$g->feature-available".
164 $acl = $g->acl_get_file ($path, $acltype);
166 This function returns the POSIX Access Control List (ACL) attached
167 to "path". The ACL is returned in "long text form" (see acl(5)).
168 The "acltype" parameter may be:
170 "access"
172 Return the ordinary (access) ACL for any file, directory or
173 other filesystem object.
174 "default"
176 Return the default ACL. Normally this only makes sense if
177 "path" is a directory.
178 This function depends on the feature "acl". See also
180 "$g->feature-available".
181 $g->acl_set_file ($path, $acltype, $acl);
183 This function sets the POSIX Access Control List (ACL) attached to
184 "path".
185 The "acltype" parameter may be:
187 "access"
189 Set the ordinary (access) ACL for any file, directory or other
190 filesystem object.
191 "default"
193 Set the default ACL. Normally this only makes sense if "path"
194 is a directory.
195 The "acl" parameter is the new ACL in either "long text form" or
197 "short text form" (see acl(5)). The new ACL completely replaces
198 any previous ACL on the file. The ACL must contain the full Unix
199 permissions (eg. "u::rwx,g::rx,o::rx").
200 If you are specifying individual users or groups, then the mask
202 field is also required (eg. "m::rwx"), followed by the "u:ID:..."
203 and/or "g:ID:..." field(s). A full ACL string might therefore look
204 like this:
205 u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx
207 \ Unix permissions / \mask/ \ ACL /
208 You should use numeric UIDs and GIDs. To map usernames and
210 groupnames to the correct numeric ID in the context of the guest,
211 use the Augeas functions (see "$g->aug_init").
212 This function depends on the feature "acl". See also
214 "$g->feature-available".
215 $g->add_cdrom ($filename);
217 This function adds a virtual CD-ROM disk image to the guest.
218 The image is added as read-only drive, so this function is
220 equivalent of "$g->add_drive_ro".
221 This function is deprecated. In new code, use the "add_drive_ro"
223 call instead.
224 Deprecated functions will not be removed from the API, but the fact
226 that they are deprecated indicates that there are problems with
227 correct use of these functions.
228 $nrdisks = $g->add_domain ($dom [, libvirturi => $libvirturi] [,
230 readonly => $readonly] [, iface => $iface] [, live => $live] [,
231 allowuuid => $allowuuid] [, readonlydisk => $readonlydisk] [, cachemode
232 => $cachemode] [, discard => $discard] [, copyonread => $copyonread]);
233 This function adds the disk(s) attached to the named libvirt domain
234 "dom". It works by connecting to libvirt, requesting the domain
235 and domain XML from libvirt, parsing it for disks, and calling
236 "$g->add_drive_opts" on each one.
237 The number of disks added is returned. This operation is atomic:
239 if an error is returned, then no disks are added.
240 This function does some minimal checks to make sure the libvirt
242 domain is not running (unless "readonly" is true). In a future
243 version we will try to acquire the libvirt lock on each disk.
244 Disks must be accessible locally. This often means that adding
246 disks from a remote libvirt connection (see
247 <https://libvirt.org/remote.html>) will fail unless those disks are
248 accessible via the same device path locally too.
249 The optional "libvirturi" parameter sets the libvirt URI (see
251 <https://libvirt.org/uri.html>). If this is not set then we
252 connect to the default libvirt URI (or one set through an
253 environment variable, see the libvirt documentation for full
254 details).
255 The optional "live" flag controls whether this call will try to
257 connect to a running virtual machine "guestfsd" process if it sees
258 a suitable <channel> element in the libvirt XML definition. The
259 default (if the flag is omitted) is never to try. See "ATTACHING
260 TO RUNNING DAEMONS" in guestfs(3) for more information.
261 If the "allowuuid" flag is true (default is false) then a UUID may
263 be passed instead of the domain name. The "dom" string is treated
264 as a UUID first and looked up, and if that lookup fails then we
265 treat "dom" as a name as usual.
266 The optional "readonlydisk" parameter controls what we do for disks
268 which are marked <readonly/> in the libvirt XML. Possible values
269 are:
270 readonlydisk = "error"
272 If "readonly" is false:
273 The whole call is aborted with an error if any disk with the
275 <readonly/> flag is found.
276 If "readonly" is true:
278 Disks with the <readonly/> flag are added read-only.
280 readonlydisk = "read"
282 If "readonly" is false:
283 Disks with the <readonly/> flag are added read-only. Other
285 disks are added read/write.
286 If "readonly" is true:
288 Disks with the <readonly/> flag are added read-only.
290 readonlydisk = "write" (default)
292 If "readonly" is false:
293 Disks with the <readonly/> flag are added read/write.
295 If "readonly" is true:
297 Disks with the <readonly/> flag are added read-only.
299 readonlydisk = "ignore"
301 If "readonly" is true or false:
302 Disks with the <readonly/> flag are skipped.
304 If present, the value of "logical_block_size" attribute of
306 <blockio/> tag in libvirt XML will be passed as "blocksize"
307 parameter to "$g->add_drive_opts".
308 The other optional parameters are passed directly through to
310 "$g->add_drive_opts".
311 $g->add_drive ($filename [, readonly => $readonly] [, format =>
313 $format] [, iface => $iface] [, name => $name] [, label => $label] [,
314 protocol => $protocol] [, server => $server] [, username => $username]
315 [, secret => $secret] [, cachemode => $cachemode] [, discard =>
316 $discard] [, copyonread => $copyonread] [, blocksize => $blocksize]);
317 This function adds a disk image called filename to the handle.
318 filename may be a regular host file or a host device.
319 When this function is called before "$g->launch" (the usual case)
321 then the first time you call this function, the disk appears in the
322 API as /dev/sda, the second time as /dev/sdb, and so on.
323 In libguestfs X 1.20 you can also call this function after launch
325 (with some restrictions). This is called "hotplugging". When
326 hotplugging, you must specify a "label" so that the new disk gets a
327 predictable name. For more information see "HOTPLUGGING" in
328 guestfs(3).
329 You don't necessarily need to be root when using libguestfs.
331 However you obviously do need sufficient permissions to access the
332 filename for whatever operations you want to perform (ie. read
333 access if you just want to read the image or write access if you
334 want to modify the image).
335 This call checks that filename exists.
337 filename may be the special string "/dev/null". See "NULL DISKS"
339 in guestfs(3).
340 The optional arguments are:
342 "readonly"
344 If true then the image is treated as read-only. Writes are
345 still allowed, but they are stored in a temporary snapshot
346 overlay which is discarded at the end. The disk that you add
347 is not modified.
348 "format"
350 This forces the image format. If you omit this (or use
351 "$g->add_drive" or "$g->add_drive_ro") then the format is
352 automatically detected. Possible formats include "raw" and
353 "qcow2".
354 Automatic detection of the format opens you up to a potential
356 security hole when dealing with untrusted raw-format images.
357 See CVE-2010-3851 and RHBZ#642934. Specifying the format
358 closes this security hole.
359 "iface"
361 This rarely-used option lets you emulate the behaviour of the
362 deprecated "$g->add_drive_with_if" call (q.v.)
363 "name"
365 The name the drive had in the original guest, e.g. /dev/sdb.
366 This is used as a hint to the guest inspection process if it is
367 available.
368 "label"
370 Give the disk a label. The label should be a unique, short
371 string using only ASCII characters "[a-zA-Z]". As well as its
372 usual name in the API (such as /dev/sda), the drive will also
373 be named /dev/disk/guestfs/label.
374 See "DISK LABELS" in guestfs(3).
376 "protocol"
378 The optional protocol argument can be used to select an
379 alternate source protocol.
380 See also: "REMOTE STORAGE" in guestfs(3).
382 "protocol = "file""
384 filename is interpreted as a local file or device. This is
385 the default if the optional protocol parameter is omitted.
386 "protocol = "ftp"|"ftps"|"http"|"https"|"tftp""
388 Connect to a remote FTP, HTTP or TFTP server. The "server"
389 parameter must also be supplied - see below.
390 See also: "FTP, HTTP AND TFTP" in guestfs(3)
392 "protocol = "gluster""
394 Connect to the GlusterFS server. The "server" parameter
395 must also be supplied - see below.
396 See also: "GLUSTER" in guestfs(3)
398 "protocol = "iscsi""
400 Connect to the iSCSI server. The "server" parameter must
401 also be supplied - see below. The "username" parameter may
402 be supplied. See below. The "secret" parameter may be
403 supplied. See below.
404 See also: "ISCSI" in guestfs(3).
406 "protocol = "nbd""
408 Connect to the Network Block Device server. The "server"
409 parameter must also be supplied - see below.
410 See also: "NETWORK BLOCK DEVICE" in guestfs(3).
412 "protocol = "rbd""
414 Connect to the Ceph (librbd/RBD) server. The "server"
415 parameter must also be supplied - see below. The
416 "username" parameter may be supplied. See below. The
417 "secret" parameter may be supplied. See below.
418 See also: "CEPH" in guestfs(3).
420 "protocol = "sheepdog""
422 Connect to the Sheepdog server. The "server" parameter may
423 also be supplied - see below.
424 See also: "SHEEPDOG" in guestfs(3).
426 "protocol = "ssh""
428 Connect to the Secure Shell (ssh) server.
429 The "server" parameter must be supplied. The "username"
431 parameter may be supplied. See below.
432 See also: "SSH" in guestfs(3).
434 "server"
436 For protocols which require access to a remote server, this is
437 a list of server(s).
438 Protocol Number of servers required
440 -------- --------------------------
441 file List must be empty or param not used at all
442 ftp|ftps|http|https|tftp Exactly one
443 gluster Exactly one
444 iscsi Exactly one
445 nbd Exactly one
446 rbd Zero or more
447 sheepdog Zero or more
448 ssh Exactly one
449 Each list element is a string specifying a server. The string
451 must be in one of the following formats:
452 hostname
454 hostname:port
455 tcp:hostname
456 tcp:hostname:port
457 unix:/path/to/socket
458 If the port number is omitted, then the standard port number
460 for the protocol is used (see /etc/services).
461 "username"
463 For the "ftp", "ftps", "http", "https", "iscsi", "rbd", "ssh"
464 and "tftp" protocols, this specifies the remote username.
465 If not given, then the local username is used for "ssh", and no
467 authentication is attempted for ceph. But note this sometimes
468 may give unexpected results, for example if using the libvirt
469 backend and if the libvirt backend is configured to start the
470 qemu appliance as a special user such as "qemu.qemu". If in
471 doubt, specify the remote username you want.
472 "secret"
474 For the "rbd" protocol only, this specifies the XsecretX to use
475 when connecting to the remote device. It must be base64
476 encoded.
477 If not given, then a secret matching the given username will be
479 looked up in the default keychain locations, or if no username
480 is given, then no authentication will be used.
481 "cachemode"
483 Choose whether or not libguestfs will obey sync operations
484 (safe but slow) or not (unsafe but fast). The possible values
485 for this string are:
486 "cachemode = "writeback""
488 This is the default.
489 Write operations in the API do not return until a write(2)
491 call has completed in the host [but note this does not
492 imply that anything gets written to disk].
493 Sync operations in the API, including implicit syncs caused
495 by filesystem journalling, will not return until an
496 fdatasync(2) call has completed in the host, indicating
497 that data has been committed to disk.
498 "cachemode = "unsafe""
500 In this mode, there are no guarantees. Libguestfs may
501 cache anything and ignore sync requests. This is suitable
502 only for scratch or temporary disks.
503 "discard"
505 Enable or disable discard (a.k.a. trim or unmap) support on
506 this drive. If enabled, operations such as "$g->fstrim" will
507 be able to discard / make thin / punch holes in the underlying
508 host file or device.
509 Possible discard settings are:
511 "discard = "disable""
513 Disable discard support. This is the default.
514 "discard = "enable""
516 Enable discard support. Fail if discard is not possible.
517 "discard = "besteffort""
519 Enable discard support if possible, but don't fail if it is
520 not supported.
521 Since not all backends and not all underlying systems
523 support discard, this is a good choice if you want to use
524 discard if possible, but don't mind if it doesn't work.
525 "copyonread"
527 The boolean parameter "copyonread" enables copy-on-read
528 support. This only affects disk formats which have backing
529 files, and causes reads to be stored in the overlay layer,
530 speeding up multiple reads of the same area of disk.
531 The default is false.
533 "blocksize"
535 This parameter sets the sector size of the disk. Possible
536 values are 512 (the default if the parameter is omitted) or
537 4096. Use 4096 when handling an "Advanced Format" disk that
538 uses 4K sector size
539 (<https://en.wikipedia.org/wiki/Advanced_Format>).
540 Only a subset of the backends support this parameter (currently
542 only the libvirt and direct backends do).
543 $g->add_drive_opts ($filename [, readonly => $readonly] [, format =>
545 $format] [, iface => $iface] [, name => $name] [, label => $label] [,
546 protocol => $protocol] [, server => $server] [, username => $username]
547 [, secret => $secret] [, cachemode => $cachemode] [, discard =>
548 $discard] [, copyonread => $copyonread] [, blocksize => $blocksize]);
549 This is an alias of "add_drive".
550 $g->add_drive_ro ($filename);
552 This function is the equivalent of calling "$g->add_drive_opts"
553 with the optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set
554 to 1, so the disk is added read-only, with the format being
555 detected automatically.
556 $g->add_drive_ro_with_if ($filename, $iface);
558 This is the same as "$g->add_drive_ro" but it allows you to specify
559 the QEMU interface emulation to use at run time.
560 This function is deprecated. In new code, use the "add_drive" call
562 instead.
563 Deprecated functions will not be removed from the API, but the fact
565 that they are deprecated indicates that there are problems with
566 correct use of these functions.
567 $g->add_drive_scratch ($size [, name => $name] [, label => $label] [,
569 blocksize => $blocksize]);
570 This command adds a temporary scratch drive to the handle. The
571 "size" parameter is the virtual size (in bytes). The scratch drive
572 is blank initially (all reads return zeroes until you start writing
573 to it). The drive is deleted when the handle is closed.
574 The optional arguments "name", "label" and "blocksize" are passed
576 through to "$g->add_drive_opts".
577 $g->add_drive_with_if ($filename, $iface);
579 This is the same as "$g->add_drive" but it allows you to specify
580 the QEMU interface emulation to use at run time.
581 This function is deprecated. In new code, use the "add_drive" call
583 instead.
584 Deprecated functions will not be removed from the API, but the fact
586 that they are deprecated indicates that there are problems with
587 correct use of these functions.
588 $nrdisks = $g->add_libvirt_dom ($dom [, readonly => $readonly] [, iface
590 => $iface] [, live => $live] [, readonlydisk => $readonlydisk] [,
591 cachemode => $cachemode] [, discard => $discard] [, copyonread =>
592 $copyonread]);
593 This function adds the disk(s) attached to the libvirt domain
594 "dom". It works by requesting the domain XML from libvirt, parsing
595 it for disks, and calling "$g->add_drive_opts" on each one.
596 In the C API we declare "void *dom", but really it has type
598 "virDomainPtr dom". This is so we don't need <libvirt.h>.
599 The number of disks added is returned. This operation is atomic:
601 if an error is returned, then no disks are added.
602 This function does some minimal checks to make sure the libvirt
604 domain is not running (unless "readonly" is true). In a future
605 version we will try to acquire the libvirt lock on each disk.
606 Disks must be accessible locally. This often means that adding
608 disks from a remote libvirt connection (see
609 <https://libvirt.org/remote.html>) will fail unless those disks are
610 accessible via the same device path locally too.
611 The optional "live" flag controls whether this call will try to
613 connect to a running virtual machine "guestfsd" process if it sees
614 a suitable <channel> element in the libvirt XML definition. The
615 default (if the flag is omitted) is never to try. See "ATTACHING
616 TO RUNNING DAEMONS" in guestfs(3) for more information.
617 The optional "readonlydisk" parameter controls what we do for disks
619 which are marked <readonly/> in the libvirt XML. See
620 "$g->add_domain" for possible values.
621 If present, the value of "logical_block_size" attribute of
623 <blockio/> tag in libvirt XML will be passed as "blocksize"
624 parameter to "$g->add_drive_opts".
625 The other optional parameters are passed directly through to
627 "$g->add_drive_opts".
628 $g->aug_clear ($augpath);
630 Set the value associated with "path" to "NULL". This is the same
631 as the augtool(1) "clear" command.
632 $g->aug_close ();
634 Close the current Augeas handle and free up any resources used by
635 it. After calling this, you have to call "$g->aug_init" again
636 before you can use any other Augeas functions.
637 %nrnodescreated = $g->aug_defnode ($name, $expr, $val);
639 Defines a variable "name" whose value is the result of evaluating
640 "expr".
641 If "expr" evaluates to an empty nodeset, a node is created,
643 equivalent to calling "$g->aug_set" "expr", "val". "name" will be
644 the nodeset containing that single node.
645 On success this returns a pair containing the number of nodes in
647 the nodeset, and a boolean flag if a node was created.
648 $nrnodes = $g->aug_defvar ($name, $expr);
650 Defines an Augeas variable "name" whose value is the result of
651 evaluating "expr". If "expr" is NULL, then "name" is undefined.
652 On success this returns the number of nodes in "expr", or 0 if
654 "expr" evaluates to something which is not a nodeset.
655 $val = $g->aug_get ($augpath);
657 Look up the value associated with "path". If "path" matches
658 exactly one node, the "value" is returned.
659 $g->aug_init ($root, $flags);
661 Create a new Augeas handle for editing configuration files. If
662 there was any previous Augeas handle associated with this guestfs
663 session, then it is closed.
664 You must call this before using any other "$g->aug_*" commands.
666 "root" is the filesystem root. "root" must not be NULL, use /
668 instead.
669 The flags are the same as the flags defined in <augeas.h>, the
671 logical or of the following integers:
672 "AUG_SAVE_BACKUP" = 1
674 Keep the original file with a ".augsave" extension.
675 "AUG_SAVE_NEWFILE" = 2
677 Save changes into a file with extension ".augnew", and do not
678 overwrite original. Overrides "AUG_SAVE_BACKUP".
679 "AUG_TYPE_CHECK" = 4
681 Typecheck lenses.
682 This option is only useful when debugging Augeas lenses. Use
684 of this option may require additional memory for the libguestfs
685 appliance. You may need to set the "LIBGUESTFS_MEMSIZE"
686 environment variable or call "$g->set_memsize".
687 "AUG_NO_STDINC" = 8
689 Do not use standard load path for modules.
690 "AUG_SAVE_NOOP" = 16
692 Make save a no-op, just record what would have been changed.
693 "AUG_NO_LOAD" = 32
695 Do not load the tree in "$g->aug_init".
696 To close the handle, you can call "$g->aug_close".
698 To find out more about Augeas, see <http://augeas.net/>.
700 $g->aug_insert ($augpath, $label, $before);
702 Create a new sibling "label" for "path", inserting it into the tree
703 before or after "path" (depending on the boolean flag "before").
704 "path" must match exactly one existing node in the tree, and
706 "label" must be a label, ie. not contain /, "*" or end with a
707 bracketed index "[N]".
708 $label = $g->aug_label ($augpath);
710 The label (name of the last element) of the Augeas path expression
711 "augpath" is returned. "augpath" must match exactly one node, else
712 this function returns an error.
713 $g->aug_load ();
715 Load files into the tree.
716 See "aug_load" in the Augeas documentation for the full gory
718 details.
719 @matches = $g->aug_ls ($augpath);
721 This is just a shortcut for listing "$g->aug_match" "path/*" and
722 sorting the resulting nodes into alphabetical order.
723 @matches = $g->aug_match ($augpath);
725 Returns a list of paths which match the path expression "path".
726 The returned paths are sufficiently qualified so that they match
727 exactly one node in the current tree.
728 $g->aug_mv ($src, $dest);
730 Move the node "src" to "dest". "src" must match exactly one node.
731 "dest" is overwritten if it exists.
732 $nrnodes = $g->aug_rm ($augpath);
734 Remove "path" and all of its children.
735 On success this returns the number of entries which were removed.
737 $g->aug_save ();
739 This writes all pending changes to disk.
740 The flags which were passed to "$g->aug_init" affect exactly how
742 files are saved.
743 $g->aug_set ($augpath, $val);
745 Set the value associated with "augpath" to "val".
746 In the Augeas API, it is possible to clear a node by setting the
748 value to NULL. Due to an oversight in the libguestfs API you
749 cannot do that with this call. Instead you must use the
750 "$g->aug_clear" call.
751 $nodes = $g->aug_setm ($base, $sub, $val);
753 Change multiple Augeas nodes in a single operation. "base" is an
754 expression matching multiple nodes. "sub" is a path expression
755 relative to "base". All nodes matching "base" are found, and then
756 for each node, "sub" is changed to "val". "sub" may also be "NULL"
757 in which case the "base" nodes are modified.
758 This returns the number of nodes modified.
760 $g->aug_transform ($lens, $file [, remove => $remove]);
762 Add an Augeas transformation for the specified "lens" so it can
763 handle "file".
764 If "remove" is true ("false" by default), then the transformation
766 is removed.
767 $g->available (\@groups);
769 This command is used to check the availability of some groups of
770 functionality in the appliance, which not all builds of the
771 libguestfs appliance will be able to provide.
772 The libguestfs groups, and the functions that those groups
774 correspond to, are listed in "AVAILABILITY" in guestfs(3). You can
775 also fetch this list at runtime by calling
776 "$g->available_all_groups".
777 The argument "groups" is a list of group names, eg: "["inotify",
779 "augeas"]" would check for the availability of the Linux inotify
780 functions and Augeas (configuration file editing) functions.
781 The command returns no error if all requested groups are available.
783 It fails with an error if one or more of the requested groups is
785 unavailable in the appliance.
786 If an unknown group name is included in the list of groups then an
788 error is always returned.
789 Notes:
791 · "$g->feature_available" is the same as this call, but with a
793 slightly simpler to use API: that call returns a boolean
794 true/false instead of throwing an error.
795 · You must call "$g->launch" before calling this function.
797 The reason is because we don't know what groups are supported
799 by the appliance/daemon until it is running and can be queried.
800 · If a group of functions is available, this does not necessarily
802 mean that they will work. You still have to check for errors
803 when calling individual API functions even if they are
804 available.
805 · It is usually the job of distro packagers to build complete
807 functionality into the libguestfs appliance. Upstream
808 libguestfs, if built from source with all requirements
809 satisfied, will support everything.
810 · This call was added in version 1.0.80. In previous versions of
812 libguestfs all you could do would be to speculatively execute a
813 command to find out if the daemon implemented it. See also
814 "$g->version".
815 See also "$g->filesystem_available".
817 @groups = $g->available_all_groups ();
819 This command returns a list of all optional groups that this daemon
820 knows about. Note this returns both supported and unsupported
821 groups. To find out which ones the daemon can actually support you
822 have to call "$g->available" / "$g->feature_available" on each
823 member of the returned list.
824 See also "$g->available", "$g->feature_available" and
826 "AVAILABILITY" in guestfs(3).
827 $g->base64_in ($base64file, $filename);
829 This command uploads base64-encoded data from "base64file" to
830 filename.
831 $g->base64_out ($filename, $base64file);
833 This command downloads the contents of filename, writing it out to
834 local file "base64file" encoded as base64.
835 $g->blkdiscard ($device);
837 This discards all blocks on the block device "device", giving the
838 free space back to the host.
839 This operation requires support in libguestfs, the host filesystem,
841 qemu and the host kernel. If this support isn't present it may
842 give an error or even appear to run but do nothing. You must also
843 set the "discard" attribute on the underlying drive (see
844 "$g->add_drive_opts").
845 This function depends on the feature "blkdiscard". See also
847 "$g->feature-available".
848 $zeroes = $g->blkdiscardzeroes ($device);
850 This call returns true if blocks on "device" that have been
851 discarded by a call to "$g->blkdiscard" are returned as blocks of
852 zero bytes when read the next time.
853 If it returns false, then it may be that discarded blocks are read
855 as stale or random data.
856 This function depends on the feature "blkdiscardzeroes". See also
858 "$g->feature-available".
859 %info = $g->blkid ($device);
861 This command returns block device attributes for "device". The
862 following fields are usually present in the returned hash. Other
863 fields may also be present.
864 "UUID"
866 The uuid of this device.
867 "LABEL"
869 The label of this device.
870 "VERSION"
872 The version of blkid command.
873 "TYPE"
875 The filesystem type or RAID of this device.
876 "USAGE"
878 The usage of this device, for example "filesystem" or "raid".
879 $g->blockdev_flushbufs ($device);
881 This tells the kernel to flush internal buffers associated with
882 "device".
883 This uses the blockdev(8) command.
885 $blocksize = $g->blockdev_getbsz ($device);
887 This returns the block size of a device.
888 Note: this is different from both size in blocks and filesystem
890 block size. Also this setting is not really used by anything. You
891 should probably not use it for anything. Filesystems have their
892 own idea about what block size to choose.
893 This uses the blockdev(8) command.
895 $ro = $g->blockdev_getro ($device);
897 Returns a boolean indicating if the block device is read-only (true
898 if read-only, false if not).
899 This uses the blockdev(8) command.
901 $sizeinbytes = $g->blockdev_getsize64 ($device);
903 This returns the size of the device in bytes.
904 See also "$g->blockdev_getsz".
906 This uses the blockdev(8) command.
908 $sectorsize = $g->blockdev_getss ($device);
910 This returns the size of sectors on a block device. Usually 512,
911 but can be larger for modern devices.
912 (Note, this is not the size in sectors, use "$g->blockdev_getsz"
914 for that).
915 This uses the blockdev(8) command.
917 $sizeinsectors = $g->blockdev_getsz ($device);
919 This returns the size of the device in units of 512-byte sectors
920 (even if the sectorsize isn't 512 bytes ... weird).
921 See also "$g->blockdev_getss" for the real sector size of the
923 device, and "$g->blockdev_getsize64" for the more useful size in
924 bytes.
925 This uses the blockdev(8) command.
927 $g->blockdev_rereadpt ($device);
929 Reread the partition table on "device".
930 This uses the blockdev(8) command.
932 $g->blockdev_setbsz ($device, $blocksize);
934 This call does nothing and has never done anything because of a bug
935 in blockdev. Do not use it.
936 If you need to set the filesystem block size, use the "blocksize"
938 option of "$g->mkfs".
939 This function is deprecated. There is no replacement. Consult the
941 API documentation in guestfs(3) for further information.
942 Deprecated functions will not be removed from the API, but the fact
944 that they are deprecated indicates that there are problems with
945 correct use of these functions.
946 $g->blockdev_setra ($device, $sectors);
948 Set readahead (in 512-byte sectors) for the device.
949 This uses the blockdev(8) command.
951 $g->blockdev_setro ($device);
953 Sets the block device named "device" to read-only.
954 This uses the blockdev(8) command.
956 $g->blockdev_setrw ($device);
958 Sets the block device named "device" to read-write.
959 This uses the blockdev(8) command.
961 $g->btrfs_balance_cancel ($path);
963 Cancel a running balance on a btrfs filesystem.
964 This function depends on the feature "btrfs". See also
966 "$g->feature-available".
967 $g->btrfs_balance_pause ($path);
969 Pause a running balance on a btrfs filesystem.
970 This function depends on the feature "btrfs". See also
972 "$g->feature-available".
973 $g->btrfs_balance_resume ($path);
975 Resume a paused balance on a btrfs filesystem.
976 This function depends on the feature "btrfs". See also
978 "$g->feature-available".
979 %status = $g->btrfs_balance_status ($path);
981 Show the status of a running or paused balance on a btrfs
982 filesystem.
983 This function depends on the feature "btrfs". See also
985 "$g->feature-available".
986 $g->btrfs_device_add (\@devices, $fs);
988 Add the list of device(s) in "devices" to the btrfs filesystem
989 mounted at "fs". If "devices" is an empty list, this does nothing.
990 This function depends on the feature "btrfs". See also
992 "$g->feature-available".
993 $g->btrfs_device_delete (\@devices, $fs);
995 Remove the "devices" from the btrfs filesystem mounted at "fs". If
996 "devices" is an empty list, this does nothing.
997 This function depends on the feature "btrfs". See also
999 "$g->feature-available".
1000 $g->btrfs_filesystem_balance ($fs);
1002 Balance the chunks in the btrfs filesystem mounted at "fs" across
1003 the underlying devices.
1004 This function depends on the feature "btrfs". See also
1006 "$g->feature-available".
1007 $g->btrfs_filesystem_defragment ($path [, flush => $flush] [, compress
1009 => $compress]);
1010 Defragment a file or directory on a btrfs filesystem. compress is
1011 one of zlib or lzo.
1012 This function depends on the feature "btrfs". See also
1014 "$g->feature-available".
1015 $g->btrfs_filesystem_resize ($mountpoint [, size => $size]);
1017 This command resizes a btrfs filesystem.
1018 Note that unlike other resize calls, the filesystem has to be
1020 mounted and the parameter is the mountpoint not the device (this is
1021 a requirement of btrfs itself).
1022 The optional parameters are:
1024 "size"
1026 The new size (in bytes) of the filesystem. If omitted, the
1027 filesystem is resized to the maximum size.
1028 See also btrfs(8).
1030 This function depends on the feature "btrfs". See also
1032 "$g->feature-available".
1033 @devices = $g->btrfs_filesystem_show ($device);
1035 Show all the devices where the filesystems in "device" is spanned
1036 over.
1037 If not all the devices for the filesystems are present, then this
1039 function fails and the "errno" is set to "ENODEV".
1040 This function depends on the feature "btrfs". See also
1042 "$g->feature-available".
1043 $g->btrfs_filesystem_sync ($fs);
1045 Force sync on the btrfs filesystem mounted at "fs".
1046 This function depends on the feature "btrfs". See also
1048 "$g->feature-available".
1049 $g->btrfs_fsck ($device [, superblock => $superblock] [, repair =>
1051 $repair]);
1052 Used to check a btrfs filesystem, "device" is the device file where
1053 the filesystem is stored.
1054 This function depends on the feature "btrfs". See also
1056 "$g->feature-available".
1057 $g->btrfs_image (\@source, $image [, compresslevel => $compresslevel]);
1059 This is used to create an image of a btrfs filesystem. All data
1060 will be zeroed, but metadata and the like is preserved.
1061 This function depends on the feature "btrfs". See also
1063 "$g->feature-available".
1064 $g->btrfs_qgroup_assign ($src, $dst, $path);
1066 Add qgroup "src" to parent qgroup "dst". This command can group
1067 several qgroups into a parent qgroup to share common limit.
1068 This function depends on the feature "btrfs". See also
1070 "$g->feature-available".
1071 $g->btrfs_qgroup_create ($qgroupid, $subvolume);
1073 Create a quota group (qgroup) for subvolume at "subvolume".
1074 This function depends on the feature "btrfs". See also
1076 "$g->feature-available".
1077 $g->btrfs_qgroup_destroy ($qgroupid, $subvolume);
1079 Destroy a quota group.
1080 This function depends on the feature "btrfs". See also
1082 "$g->feature-available".
1083 $g->btrfs_qgroup_limit ($subvolume, $size);
1085 Limit the size of the subvolume with path "subvolume".
1086 This function depends on the feature "btrfs". See also
1088 "$g->feature-available".
1089 $g->btrfs_qgroup_remove ($src, $dst, $path);
1091 Remove qgroup "src" from the parent qgroup "dst".
1092 This function depends on the feature "btrfs". See also
1094 "$g->feature-available".
1095 @qgroups = $g->btrfs_qgroup_show ($path);
1097 Show all subvolume quota groups in a btrfs filesystem, including
1098 their usages.
1099 This function depends on the feature "btrfs". See also
1101 "$g->feature-available".
1102 $g->btrfs_quota_enable ($fs, $enable);
1104 Enable or disable subvolume quota support for filesystem which
1105 contains "path".
1106 This function depends on the feature "btrfs". See also
1108 "$g->feature-available".
1109 $g->btrfs_quota_rescan ($fs);
1111 Trash all qgroup numbers and scan the metadata again with the
1112 current config.
1113 This function depends on the feature "btrfs". See also
1115 "$g->feature-available".
1116 $g->btrfs_replace ($srcdev, $targetdev, $mntpoint);
1118 Replace device of a btrfs filesystem. On a live filesystem,
1119 duplicate the data to the target device which is currently stored
1120 on the source device. After completion of the operation, the
1121 source device is wiped out and removed from the filesystem.
1122 The "targetdev" needs to be same size or larger than the "srcdev".
1124 Devices which are currently mounted are never allowed to be used as
1125 the "targetdev".
1126 This function depends on the feature "btrfs". See also
1128 "$g->feature-available".
1129 $g->btrfs_rescue_chunk_recover ($device);
1131 Recover the chunk tree of btrfs filesystem by scanning the devices
1132 one by one.
1133 This function depends on the feature "btrfs". See also
1135 "$g->feature-available".
1136 $g->btrfs_rescue_super_recover ($device);
1138 Recover bad superblocks from good copies.
1139 This function depends on the feature "btrfs". See also
1141 "$g->feature-available".
1142 $g->btrfs_scrub_cancel ($path);
1144 Cancel a running scrub on a btrfs filesystem.
1145 This function depends on the feature "btrfs". See also
1147 "$g->feature-available".
1148 $g->btrfs_scrub_resume ($path);
1150 Resume a previously canceled or interrupted scrub on a btrfs
1151 filesystem.
1152 This function depends on the feature "btrfs". See also
1154 "$g->feature-available".
1155 $g->btrfs_scrub_start ($path);
1157 Reads all the data and metadata on the filesystem, and uses
1158 checksums and the duplicate copies from RAID storage to identify
1159 and repair any corrupt data.
1160 This function depends on the feature "btrfs". See also
1162 "$g->feature-available".
1163 %status = $g->btrfs_scrub_status ($path);
1165 Show status of running or finished scrub on a btrfs filesystem.
1166 This function depends on the feature "btrfs". See also
1168 "$g->feature-available".
1169 $g->btrfs_set_seeding ($device, $seeding);
1171 Enable or disable the seeding feature of a device that contains a
1172 btrfs filesystem.
1173 This function depends on the feature "btrfs". See also
1175 "$g->feature-available".
1176 $g->btrfs_subvolume_create ($dest [, qgroupid => $qgroupid]);
1178 Create a btrfs subvolume. The "dest" argument is the destination
1179 directory and the name of the subvolume, in the form
1180 /path/to/dest/name. The optional parameter "qgroupid" represents
1181 the qgroup which the newly created subvolume will be added to.
1182 This function depends on the feature "btrfs". See also
1184 "$g->feature-available".
1185 $g->btrfs_subvolume_create_opts ($dest [, qgroupid => $qgroupid]);
1187 This is an alias of "btrfs_subvolume_create".
1188 $g->btrfs_subvolume_delete ($subvolume);
1190 Delete the named btrfs subvolume or snapshot.
1191 This function depends on the feature "btrfs". See also
1193 "$g->feature-available".
1194 $id = $g->btrfs_subvolume_get_default ($fs);
1196 Get the default subvolume or snapshot of a filesystem mounted at
1197 "mountpoint".
1198 This function depends on the feature "btrfs". See also
1200 "$g->feature-available".
1201 @subvolumes = $g->btrfs_subvolume_list ($fs);
1203 List the btrfs snapshots and subvolumes of the btrfs filesystem
1204 which is mounted at "fs".
1205 This function depends on the feature "btrfs". See also
1207 "$g->feature-available".
1208 $g->btrfs_subvolume_set_default ($id, $fs);
1210 Set the subvolume of the btrfs filesystem "fs" which will be
1211 mounted by default. See "$g->btrfs_subvolume_list" to get a list
1212 of subvolumes.
1213 This function depends on the feature "btrfs". See also
1215 "$g->feature-available".
1216 %btrfssubvolumeinfo = $g->btrfs_subvolume_show ($subvolume);
1218 Return detailed information of the subvolume.
1219 This function depends on the feature "btrfs". See also
1221 "$g->feature-available".
1222 $g->btrfs_subvolume_snapshot ($source, $dest [, ro => $ro] [, qgroupid
1224 => $qgroupid]);
1225 Create a snapshot of the btrfs subvolume "source". The "dest"
1226 argument is the destination directory and the name of the snapshot,
1227 in the form /path/to/dest/name. By default the newly created
1228 snapshot is writable, if the value of optional parameter "ro" is
1229 true, then a readonly snapshot is created. The optional parameter
1230 "qgroupid" represents the qgroup which the newly created snapshot
1231 will be added to.
1232 This function depends on the feature "btrfs". See also
1234 "$g->feature-available".
1235 $g->btrfs_subvolume_snapshot_opts ($source, $dest [, ro => $ro] [,
1237 qgroupid => $qgroupid]);
1238 This is an alias of "btrfs_subvolume_snapshot".
1239 $g->btrfstune_enable_extended_inode_refs ($device);
1241 This will Enable extended inode refs.
1242 This function depends on the feature "btrfs". See also
1244 "$g->feature-available".
1245 $g->btrfstune_enable_skinny_metadata_extent_refs ($device);
1247 This enable skinny metadata extent refs.
1248 This function depends on the feature "btrfs". See also
1250 "$g->feature-available".
1251 $g->btrfstune_seeding ($device, $seeding);
1253 Enable seeding of a btrfs device, this will force a fs readonly so
1254 that you can use it to build other filesystems.
1255 This function depends on the feature "btrfs". See also
1257 "$g->feature-available".
1258 $ptr = $g->c_pointer ();
1260 In non-C language bindings, this allows you to retrieve the
1261 underlying C pointer to the handle (ie. "$g->h *"). The purpose of
1262 this is to allow other libraries to interwork with libguestfs.
1263 $canonical = $g->canonical_device_name ($device);
1265 This utility function is useful when displaying device names to the
1266 user. It takes a number of irregular device names and returns them
1267 in a consistent format:
1268 /dev/hdX
1270 /dev/vdX
1271 These are returned as /dev/sdX. Note this works for device
1272 names and partition names. This is approximately the reverse
1273 of the algorithm described in "BLOCK DEVICE NAMING" in
1274 guestfs(3).
1275 /dev/mapper/VG-LV
1277 /dev/dm-N
1278 Converted to /dev/VG/LV form using "$g->lvm_canonical_lv_name".
1279 Other strings are returned unmodified.
1281 $cap = $g->cap_get_file ($path);
1283 This function returns the Linux capabilities attached to "path".
1284 The capabilities set is returned in text form (see cap_to_text(3)).
1285 If no capabilities are attached to a file, an empty string is
1287 returned.
1288 This function depends on the feature "linuxcaps". See also
1290 "$g->feature-available".
1291 $g->cap_set_file ($path, $cap);
1293 This function sets the Linux capabilities attached to "path". The
1294 capabilities set "cap" should be passed in text form (see
1295 cap_from_text(3)).
1296 This function depends on the feature "linuxcaps". See also
1298 "$g->feature-available".
1299 $rpath = $g->case_sensitive_path ($path);
1301 This can be used to resolve case insensitive paths on a filesystem
1302 which is case sensitive. The use case is to resolve paths which
1303 you have read from Windows configuration files or the Windows
1304 Registry, to the true path.
1305 The command handles a peculiarity of the Linux ntfs-3g filesystem
1307 driver (and probably others), which is that although the underlying
1308 filesystem is case-insensitive, the driver exports the filesystem
1309 to Linux as case-sensitive.
1310 One consequence of this is that special directories such as
1312 C:\windows may appear as /WINDOWS or /windows (or other things)
1313 depending on the precise details of how they were created. In
1314 Windows itself this would not be a problem.
1315 Bug or feature? You decide:
1317 <https://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1>
1318 "$g->case_sensitive_path" attempts to resolve the true case of each
1320 element in the path. It will return a resolved path if either the
1321 full path or its parent directory exists. If the parent directory
1322 exists but the full path does not, the case of the parent directory
1323 will be correctly resolved, and the remainder appended unmodified.
1324 For example, if the file "/Windows/System32/netkvm.sys" exists:
1325 "$g->case_sensitive_path" ("/windows/system32/netkvm.sys")
1327 "Windows/System32/netkvm.sys"
1328 "$g->case_sensitive_path" ("/windows/system32/NoSuchFile")
1330 "Windows/System32/NoSuchFile"
1331 "$g->case_sensitive_path" ("/windows/system33/netkvm.sys")
1333 ERROR
1334 Note: Because of the above behaviour, "$g->case_sensitive_path"
1336 cannot be used to check for the existence of a file.
1337 Note: This function does not handle drive names, backslashes etc.
1339 See also "$g->realpath".
1341 $content = $g->cat ($path);
1343 Return the contents of the file named "path".
1344 Because, in C, this function returns a "char *", there is no way to
1346 differentiate between a "\0" character in a file and end of string.
1347 To handle binary files, use the "$g->read_file" or "$g->download"
1348 functions.
1349 $checksum = $g->checksum ($csumtype, $path);
1351 This call computes the MD5, SHAx or CRC checksum of the file named
1352 "path".
1353 The type of checksum to compute is given by the "csumtype"
1355 parameter which must have one of the following values:
1356 "crc"
1358 Compute the cyclic redundancy check (CRC) specified by POSIX
1359 for the "cksum" command.
1360 "md5"
1362 Compute the MD5 hash (using the md5sum(1) program).
1363 "sha1"
1365 Compute the SHA1 hash (using the sha1sum(1) program).
1366 "sha224"
1368 Compute the SHA224 hash (using the sha224sum(1) program).
1369 "sha256"
1371 Compute the SHA256 hash (using the sha256sum(1) program).
1372 "sha384"
1374 Compute the SHA384 hash (using the sha384sum(1) program).
1375 "sha512"
1377 Compute the SHA512 hash (using the sha512sum(1) program).
1378 The checksum is returned as a printable string.
1380 To get the checksum for a device, use "$g->checksum_device".
1382 To get the checksums for many files, use "$g->checksums_out".
1384 $checksum = $g->checksum_device ($csumtype, $device);
1386 This call computes the MD5, SHAx or CRC checksum of the contents of
1387 the device named "device". For the types of checksums supported
1388 see the "$g->checksum" command.
1389 $g->checksums_out ($csumtype, $directory, $sumsfile);
1391 This command computes the checksums of all regular files in
1392 directory and then emits a list of those checksums to the local
1393 output file "sumsfile".
1394 This can be used for verifying the integrity of a virtual machine.
1396 However to be properly secure you should pay attention to the
1397 output of the checksum command (it uses the ones from GNU
1398 coreutils). In particular when the filename is not printable,
1399 coreutils uses a special backslash syntax. For more information,
1400 see the GNU coreutils info file.
1401 $g->chmod ($mode, $path);
1403 Change the mode (permissions) of "path" to "mode". Only numeric
1404 modes are supported.
1405 Note: When using this command from guestfish, "mode" by default
1407 would be decimal, unless you prefix it with 0 to get octal, ie. use
1408 0700 not 700.
1409 The mode actually set is affected by the umask.
1411 $g->chown ($owner, $group, $path);
1413 Change the file owner to "owner" and group to "group".
1414 Only numeric uid and gid are supported. If you want to use names,
1416 you will need to locate and parse the password file yourself
1417 (Augeas support makes this relatively easy).
1418 $count = $g->clear_backend_setting ($name);
1420 If there is a backend setting string matching "name" or beginning
1421 with "name=", then that string is removed from the backend
1422 settings.
1423 This call returns the number of strings which were removed (which
1425 may be 0, 1 or greater than 1).
1426 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
1428 $output = $g->command (\@arguments);
1430 This call runs a command from the guest filesystem. The filesystem
1431 must be mounted, and must contain a compatible operating system
1432 (ie. something Linux, with the same or compatible processor
1433 architecture).
1434 The single parameter is an argv-style list of arguments. The first
1436 element is the name of the program to run. Subsequent elements are
1437 parameters. The list must be non-empty (ie. must contain a program
1438 name). Note that the command runs directly, and is not invoked via
1439 the shell (see "$g->sh").
1440 The return value is anything printed to stdout by the command.
1442 If the command returns a non-zero exit status, then this function
1444 returns an error message. The error message string is the content
1445 of stderr from the command.
1446 The $PATH environment variable will contain at least /usr/bin and
1448 /bin. If you require a program from another location, you should
1449 provide the full path in the first parameter.
1450 Shared libraries and data files required by the program must be
1452 available on filesystems which are mounted in the correct places.
1453 It is the callerXs responsibility to ensure all filesystems that
1454 are needed are mounted at the right locations.
1455 Because of the message protocol, there is a transfer limit of
1457 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1458 guestfs(3).
1459 @lines = $g->command_lines (\@arguments);
1461 This is the same as "$g->command", but splits the result into a
1462 list of lines.
1463 See also: "$g->sh_lines"
1465 Because of the message protocol, there is a transfer limit of
1467 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1468 guestfs(3).
1469 $g->compress_device_out ($ctype, $device, $zdevice [, level =>
1471 $level]);
1472 This command compresses "device" and writes it out to the local
1473 file "zdevice".
1474 The "ctype" and optional "level" parameters have the same meaning
1476 as in "$g->compress_out".
1477 $g->compress_out ($ctype, $file, $zfile [, level => $level]);
1479 This command compresses file and writes it out to the local file
1480 zfile.
1481 The compression program used is controlled by the "ctype"
1483 parameter. Currently this includes: "compress", "gzip", "bzip2",
1484 "xz" or "lzop". Some compression types may not be supported by
1485 particular builds of libguestfs, in which case you will get an
1486 error containing the substring "not supported".
1487 The optional "level" parameter controls compression level. The
1489 meaning and default for this parameter depends on the compression
1490 program being used.
1491 $g->config ($hvparam, $hvvalue);
1493 This can be used to add arbitrary hypervisor parameters of the form
1494 -param value. Actually itXs not quite arbitrary - we prevent you
1495 from setting some parameters which would interfere with parameters
1496 that we use.
1497 The first character of "hvparam" string must be a "-" (dash).
1499 "hvvalue" can be NULL.
1501 $g->copy_attributes ($src, $dest [, all => $all] [, mode => $mode] [,
1503 xattributes => $xattributes] [, ownership => $ownership]);
1504 Copy the attributes of a path (which can be a file or a directory)
1505 to another path.
1506 By default no attribute is copied, so make sure to specify any (or
1508 "all" to copy everything).
1509 The optional arguments specify which attributes can be copied:
1511 "mode"
1513 Copy part of the file mode from "source" to "destination". Only
1514 the UNIX permissions and the sticky/setuid/setgid bits can be
1515 copied.
1516 "xattributes"
1518 Copy the Linux extended attributes (xattrs) from "source" to
1519 "destination". This flag does nothing if the linuxxattrs
1520 feature is not available (see "$g->feature_available").
1521 "ownership"
1523 Copy the owner uid and the group gid of "source" to
1524 "destination".
1525 "all"
1527 Copy all the attributes from "source" to "destination".
1528 Enabling it enables all the other flags, if they are not
1529 specified already.
1530 $g->copy_device_to_device ($src, $dest [, srcoffset => $srcoffset] [,
1532 destoffset => $destoffset] [, size => $size] [, sparse => $sparse] [,
1533 append => $append]);
1534 The four calls "$g->copy_device_to_device",
1535 "$g->copy_device_to_file", "$g->copy_file_to_device", and
1536 "$g->copy_file_to_file" let you copy from a source (device|file) to
1537 a destination (device|file).
1538 Partial copies can be made since you can specify optionally the
1540 source offset, destination offset and size to copy. These values
1541 are all specified in bytes. If not given, the offsets both default
1542 to zero, and the size defaults to copying as much as possible until
1543 we hit the end of the source.
1544 The source and destination may be the same object. However
1546 overlapping regions may not be copied correctly.
1547 If the destination is a file, it is created if required. If the
1549 destination file is not large enough, it is extended.
1550 If the destination is a file and the "append" flag is not set, then
1552 the destination file is truncated. If the "append" flag is set,
1553 then the copy appends to the destination file. The "append" flag
1554 currently cannot be set for devices.
1555 If the "sparse" flag is true then the call avoids writing blocks
1557 that contain only zeroes, which can help in some situations where
1558 the backing disk is thin-provisioned. Note that unless the target
1559 is already zeroed, using this option will result in incorrect
1560 copying.
1561 $g->copy_device_to_file ($src, $dest [, srcoffset => $srcoffset] [,
1563 destoffset => $destoffset] [, size => $size] [, sparse => $sparse] [,
1564 append => $append]);
1565 See "$g->copy_device_to_device" for a general overview of this
1566 call.
1567 $g->copy_file_to_device ($src, $dest [, srcoffset => $srcoffset] [,
1569 destoffset => $destoffset] [, size => $size] [, sparse => $sparse] [,
1570 append => $append]);
1571 See "$g->copy_device_to_device" for a general overview of this
1572 call.
1573 $g->copy_file_to_file ($src, $dest [, srcoffset => $srcoffset] [,
1575 destoffset => $destoffset] [, size => $size] [, sparse => $sparse] [,
1576 append => $append]);
1577 See "$g->copy_device_to_device" for a general overview of this
1578 call.
1579 This is not the function you want for copying files. This is for
1581 copying blocks within existing files. See "$g->cp", "$g->cp_a" and
1582 "$g->mv" for general file copying and moving functions.
1583 $g->copy_in ($localpath, $remotedir);
1585 "$g->copy_in" copies local files or directories recursively into
1586 the disk image, placing them in the directory called "remotedir"
1587 (which must exist).
1588 Wildcards cannot be used.
1590 $g->copy_out ($remotepath, $localdir);
1592 "$g->copy_out" copies remote files or directories recursively out
1593 of the disk image, placing them on the host disk in a local
1594 directory called "localdir" (which must exist).
1595 To download to the current directory, use "." as in:
1597 C<$g-E<gt>copy_out> /home .
1599 Wildcards cannot be used.
1601 $g->copy_size ($src, $dest, $size);
1603 This command copies exactly "size" bytes from one source device or
1604 file "src" to another destination device or file "dest".
1605 Note this will fail if the source is too short or if the
1607 destination is not large enough.
1608 This function is deprecated. In new code, use the
1610 "copy_device_to_device" call instead.
1611 Deprecated functions will not be removed from the API, but the fact
1613 that they are deprecated indicates that there are problems with
1614 correct use of these functions.
1615 $g->cp ($src, $dest);
1617 This copies a file from "src" to "dest" where "dest" is either a
1618 destination filename or destination directory.
1619 $g->cp_a ($src, $dest);
1621 This copies a file or directory from "src" to "dest" recursively
1622 using the "cp -a" command.
1623 $g->cp_r ($src, $dest);
1625 This copies a file or directory from "src" to "dest" recursively
1626 using the "cp -rP" command.
1627 Most users should use "$g->cp_a" instead. This command is useful
1629 when you don't want to preserve permissions, because the target
1630 filesystem does not support it (primarily when writing to DOS FAT
1631 filesystems).
1632 $g->cpio_out ($directory, $cpiofile [, format => $format]);
1634 This command packs the contents of directory and downloads it to
1635 local file "cpiofile".
1636 The optional "format" parameter can be used to select the format.
1638 Only the following formats are currently permitted:
1639 "newc"
1641 New (SVR4) portable format. This format happens to be
1642 compatible with the cpio-like format used by the Linux kernel
1643 for initramfs.
1644 This is the default format.
1646 "crc"
1648 New (SVR4) portable format with a checksum.
1649 $g->dd ($src, $dest);
1651 This command copies from one source device or file "src" to another
1652 destination device or file "dest". Normally you would use this to
1653 copy to or from a device or partition, for example to duplicate a
1654 filesystem.
1655 If the destination is a device, it must be as large or larger than
1657 the source file or device, otherwise the copy will fail. This
1658 command cannot do partial copies (see "$g->copy_device_to_device").
1659 This function is deprecated. In new code, use the
1661 "copy_device_to_device" call instead.
1662 Deprecated functions will not be removed from the API, but the fact
1664 that they are deprecated indicates that there are problems with
1665 correct use of these functions.
1666 $index = $g->device_index ($device);
1668 This function takes a device name (eg. "/dev/sdb") and returns the
1669 index of the device in the list of devices.
1670 Index numbers start from 0. The named device must exist, for
1672 example as a string returned from "$g->list_devices".
1673 See also "$g->list_devices", "$g->part_to_dev".
1675 $output = $g->df ();
1677 This command runs the df(1) command to report disk space used.
1678 This command is mostly useful for interactive sessions. It is not
1680 intended that you try to parse the output string. Use
1681 "$g->statvfs" from programs.
1682 $output = $g->df_h ();
1684 This command runs the "df -h" command to report disk space used in
1685 human-readable format.
1686 This command is mostly useful for interactive sessions. It is not
1688 intended that you try to parse the output string. Use
1689 "$g->statvfs" from programs.
1690 $g->disk_create ($filename, $format, $size [, backingfile =>
1692 $backingfile] [, backingformat => $backingformat] [, preallocation =>
1693 $preallocation] [, compat => $compat] [, clustersize => $clustersize]);
1694 Create a blank disk image called filename (a host file) with format
1695 "format" (usually "raw" or "qcow2"). The size is "size" bytes.
1696 If used with the optional "backingfile" parameter, then a snapshot
1698 is created on top of the backing file. In this case, "size" must
1699 be passed as "-1". The size of the snapshot is the same as the
1700 size of the backing file, which is discovered automatically. You
1701 are encouraged to also pass "backingformat" to describe the format
1702 of "backingfile".
1703 If filename refers to a block device, then the device is formatted.
1705 The "size" is ignored since block devices have an intrinsic size.
1706 The other optional parameters are:
1708 "preallocation"
1710 If format is "raw", then this can be either "off" (or "sparse")
1711 or "full" to create a sparse or fully allocated file
1712 respectively. The default is "off".
1713 If format is "qcow2", then this can be "off" (or "sparse"),
1715 "metadata" or "full". Preallocating metadata can be faster
1716 when doing lots of writes, but uses more space. The default is
1717 "off".
1718 "compat"
1720 "qcow2" only: Pass the string 1.1 to use the advanced qcow2
1721 format supported by qemu X 1.1.
1722 "clustersize"
1724 "qcow2" only: Change the qcow2 cluster size. The default is
1725 65536 (bytes) and this setting may be any power of two between
1726 512 and 2097152.
1727 Note that this call does not add the new disk to the handle. You
1729 may need to call "$g->add_drive_opts" separately.
1730 $format = $g->disk_format ($filename);
1732 Detect and return the format of the disk image called filename.
1733 filename can also be a host device, etc. If the format of the
1734 image could not be detected, then "unknown" is returned.
1735 Note that detecting the disk format can be insecure under some
1737 circumstances. See "CVE-2010-3851" in guestfs(3).
1738 See also: "DISK IMAGE FORMATS" in guestfs(3)
1740 $backingfile = $g->disk_has_backing_file ($filename);
1742 Detect and return whether the disk image filename has a backing
1743 file.
1744 Note that detecting disk features can be insecure under some
1746 circumstances. See "CVE-2010-3851" in guestfs(3).
1747 $size = $g->disk_virtual_size ($filename);
1749 Detect and return the virtual size in bytes of the disk image
1750 called filename.
1751 Note that detecting disk features can be insecure under some
1753 circumstances. See "CVE-2010-3851" in guestfs(3).
1754 $kmsgs = $g->dmesg ();
1756 This returns the kernel messages (dmesg(1) output) from the guest
1757 kernel. This is sometimes useful for extended debugging of
1758 problems.
1759 Another way to get the same information is to enable verbose
1761 messages with "$g->set_verbose" or by setting the environment
1762 variable "LIBGUESTFS_DEBUG=1" before running the program.
1763 $g->download ($remotefilename, $filename);
1765 Download file remotefilename and save it as filename on the local
1766 machine.
1767 filename can also be a named pipe.
1769 See also "$g->upload", "$g->cat".
1771 $g->download_blocks ($device, $start, $stop, $filename [, unallocated
1773 => $unallocated]);
1774 Download the data units from start address to stop from the disk
1775 partition (eg. /dev/sda1) and save them as filename on the local
1776 machine.
1777 The use of this API on sparse disk image formats such as QCOW, may
1779 result in large zero-filled files downloaded on the host.
1780 The size of a data unit varies across filesystem implementations.
1782 On NTFS filesystems data units are referred as clusters while on
1783 ExtX ones they are referred as fragments.
1784 If the optional "unallocated" flag is true (default is false), only
1786 the unallocated blocks will be extracted. This is useful to detect
1787 hidden data or to retrieve deleted files which data units have not
1788 been overwritten yet.
1789 This function depends on the feature "sleuthkit". See also
1791 "$g->feature-available".
1792 $g->download_inode ($device, $inode, $filename);
1794 Download a file given its inode from the disk partition (eg.
1795 /dev/sda1) and save it as filename on the local machine.
1796 It is not required to mount the disk to run this command.
1798 The command is capable of downloading deleted or inaccessible
1800 files.
1801 This function depends on the feature "sleuthkit". See also
1803 "$g->feature-available".
1804 $g->download_offset ($remotefilename, $filename, $offset, $size);
1806 Download file remotefilename and save it as filename on the local
1807 machine.
1808 remotefilename is read for "size" bytes starting at "offset" (this
1810 region must be within the file or device).
1811 Note that there is no limit on the amount of data that can be
1813 downloaded with this call, unlike with "$g->pread", and this call
1814 always reads the full amount unless an error occurs.
1815 See also "$g->download", "$g->pread".
1817 $g->drop_caches ($whattodrop);
1819 This instructs the guest kernel to drop its page cache, and/or
1820 dentries and inode caches. The parameter "whattodrop" tells the
1821 kernel what precisely to drop, see
1822 <https://linux-mm.org/Drop_Caches>
1823 Setting "whattodrop" to 3 should drop everything.
1825 This automatically calls sync(2) before the operation, so that the
1827 maximum guest memory is freed.
1828 $sizekb = $g->du ($path);
1830 This command runs the "du -s" command to estimate file space usage
1831 for "path".
1832 "path" can be a file or a directory. If "path" is a directory then
1834 the estimate includes the contents of the directory and all
1835 subdirectories (recursively).
1836 The result is the estimated size in kilobytes (ie. units of 1024
1838 bytes).
1839 $g->e2fsck ($device [, correct => $correct] [, forceall => $forceall]);
1841 This runs the ext2/ext3 filesystem checker on "device". It can
1842 take the following optional arguments:
1843 "correct"
1845 Automatically repair the file system. This option will cause
1846 e2fsck to automatically fix any filesystem problems that can be
1847 safely fixed without human intervention.
1848 This option may not be specified at the same time as the
1850 "forceall" option.
1851 "forceall"
1853 Assume an answer of XyesX to all questions; allows e2fsck to be
1854 used non-interactively.
1855 This option may not be specified at the same time as the
1857 "correct" option.
1858 $g->e2fsck_f ($device);
1860 This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
1861 checker on "device", noninteractively (-p), even if the filesystem
1862 appears to be clean (-f).
1863 This function is deprecated. In new code, use the "e2fsck" call
1865 instead.
1866 Deprecated functions will not be removed from the API, but the fact
1868 that they are deprecated indicates that there are problems with
1869 correct use of these functions.
1870 $output = $g->echo_daemon (\@words);
1872 This command concatenates the list of "words" passed with single
1873 spaces between them and returns the resulting string.
1874 You can use this command to test the connection through to the
1876 daemon.
1877 See also "$g->ping_daemon".
1879 @lines = $g->egrep ($regex, $path);
1881 This calls the external egrep(1) program and returns the matching
1882 lines.
1883 Because of the message protocol, there is a transfer limit of
1885 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1886 guestfs(3).
1887 This function is deprecated. In new code, use the "grep" call
1889 instead.
1890 Deprecated functions will not be removed from the API, but the fact
1892 that they are deprecated indicates that there are problems with
1893 correct use of these functions.
1894 @lines = $g->egrepi ($regex, $path);
1896 This calls the external "egrep -i" program and returns the matching
1897 lines.
1898 Because of the message protocol, there is a transfer limit of
1900 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1901 guestfs(3).
1902 This function is deprecated. In new code, use the "grep" call
1904 instead.
1905 Deprecated functions will not be removed from the API, but the fact
1907 that they are deprecated indicates that there are problems with
1908 correct use of these functions.
1909 $equality = $g->equal ($file1, $file2);
1911 This compares the two files file1 and file2 and returns true if
1912 their content is exactly equal, or false otherwise.
1913 The external cmp(1) program is used for the comparison.
1915 $existsflag = $g->exists ($path);
1917 This returns "true" if and only if there is a file, directory (or
1918 anything) with the given "path" name.
1919 See also "$g->is_file", "$g->is_dir", "$g->stat".
1921 $g->extlinux ($directory);
1923 Install the SYSLINUX bootloader on the device mounted at directory.
1924 Unlike "$g->syslinux" which requires a FAT filesystem, this can be
1925 used on an ext2/3/4 or btrfs filesystem.
1926 The directory parameter can be either a mountpoint, or a directory
1928 within the mountpoint.
1929 You also have to mark the partition as "active"
1931 ("$g->part_set_bootable") and a Master Boot Record must be
1932 installed (eg. using "$g->pwrite_device") on the first sector of
1933 the whole disk. The SYSLINUX package comes with some suitable
1934 Master Boot Records. See the extlinux(1) man page for further
1935 information.
1936 Additional configuration can be supplied to SYSLINUX by placing a
1938 file called extlinux.conf on the filesystem under directory. For
1939 further information about the contents of this file, see
1940 extlinux(1).
1941 See also "$g->syslinux".
1943 This function depends on the feature "extlinux". See also
1945 "$g->feature-available".
1946 $g->f2fs_expand ($device);
1948 This expands a f2fs filesystem to match the size of the underlying
1949 device.
1950 This function depends on the feature "f2fs". See also
1952 "$g->feature-available".
1953 $g->fallocate ($path, $len);
1955 This command preallocates a file (containing zero bytes) named
1956 "path" of size "len" bytes. If the file exists already, it is
1957 overwritten.
1958 Do not confuse this with the guestfish-specific "alloc" command
1960 which allocates a file in the host and attaches it as a device.
1961 This function is deprecated. In new code, use the "fallocate64"
1963 call instead.
1964 Deprecated functions will not be removed from the API, but the fact
1966 that they are deprecated indicates that there are problems with
1967 correct use of these functions.
1968 $g->fallocate64 ($path, $len);
1970 This command preallocates a file (containing zero bytes) named
1971 "path" of size "len" bytes. If the file exists already, it is
1972 overwritten.
1973 Note that this call allocates disk blocks for the file. To create
1975 a sparse file use "$g->truncate_size" instead.
1976 The deprecated call "$g->fallocate" does the same, but owing to an
1978 oversight it only allowed 30 bit lengths to be specified,
1979 effectively limiting the maximum size of files created through that
1980 call to 1GB.
1981 Do not confuse this with the guestfish-specific "alloc" and
1983 "sparse" commands which create a file in the host and attach it as
1984 a device.
1985 $isavailable = $g->feature_available (\@groups);
1987 This is the same as "$g->available", but unlike that call it
1988 returns a simple true/false boolean result, instead of throwing an
1989 exception if a feature is not found. For other documentation see
1990 "$g->available".
1991 @lines = $g->fgrep ($pattern, $path);
1993 This calls the external fgrep(1) program and returns the matching
1994 lines.
1995 Because of the message protocol, there is a transfer limit of
1997 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1998 guestfs(3).
1999 This function is deprecated. In new code, use the "grep" call
2001 instead.
2002 Deprecated functions will not be removed from the API, but the fact
2004 that they are deprecated indicates that there are problems with
2005 correct use of these functions.
2006 @lines = $g->fgrepi ($pattern, $path);
2008 This calls the external "fgrep -i" program and returns the matching
2009 lines.
2010 Because of the message protocol, there is a transfer limit of
2012 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2013 guestfs(3).
2014 This function is deprecated. In new code, use the "grep" call
2016 instead.
2017 Deprecated functions will not be removed from the API, but the fact
2019 that they are deprecated indicates that there are problems with
2020 correct use of these functions.
2021 $description = $g->file ($path);
2023 This call uses the standard file(1) command to determine the type
2024 or contents of the file.
2025 This call will also transparently look inside various types of
2027 compressed file.
2028 The exact command which runs is "file -zb path". Note in
2030 particular that the filename is not prepended to the output (the -b
2031 option).
2032 The output depends on the output of the underlying file(1) command
2034 and it can change in future in ways beyond our control. In other
2035 words, the output is not guaranteed by the ABI.
2036 See also: file(1), "$g->vfs_type", "$g->lstat", "$g->is_file",
2038 "$g->is_blockdev" (etc), "$g->is_zero".
2039 $arch = $g->file_architecture ($filename);
2041 This detects the architecture of the binary filename, and returns
2042 it if known.
2043 Currently defined architectures are:
2045 "aarch64"
2047 64 bit ARM.
2048 "arm"
2050 32 bit ARM.
2051 "i386"
2053 This string is returned for all 32 bit i386, i486, i586, i686
2054 binaries irrespective of the precise processor requirements of
2055 the binary.
2056 "ia64"
2058 Intel Itanium.
2059 "ppc"
2061 32 bit Power PC.
2062 "ppc64"
2064 64 bit Power PC (big endian).
2065 "ppc64le"
2067 64 bit Power PC (little endian).
2068 "riscv32"
2070 "riscv64"
2071 "riscv128"
2072 RISC-V 32-, 64- or 128-bit variants.
2073 "s390"
2075 31 bit IBM S/390.
2076 "s390x"
2078 64 bit IBM S/390.
2079 "sparc"
2081 32 bit SPARC.
2082 "sparc64"
2084 64 bit SPARC V9 and above.
2085 "x86_64"
2087 64 bit x86-64.
2088 Libguestfs may return other architecture strings in future.
2090 The function works on at least the following types of files:
2092 · many types of Un*x and Linux binary
2094 · many types of Un*x and Linux shared library
2096 · Windows Win32 and Win64 binaries
2098 · Windows Win32 and Win64 DLLs
2100 Win32 binaries and DLLs return "i386".
2102 Win64 binaries and DLLs return "x86_64".
2104 · Linux kernel modules
2106 · Linux new-style initrd images
2108 · some non-x86 Linux vmlinuz kernels
2110 What it can't do currently:
2112 · static libraries (libfoo.a)
2114 · Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
2116 · x86 Linux vmlinuz kernels
2118 x86 vmlinuz images (bzImage format) consist of a mix of 16-,
2120 32- and compressed code, and are horribly hard to unpack. If
2121 you want to find the architecture of a kernel, use the
2122 architecture of the associated initrd or kernel module(s)
2123 instead.
2124 $size = $g->filesize ($file);
2126 This command returns the size of file in bytes.
2127 To get other stats about a file, use "$g->stat", "$g->lstat",
2129 "$g->is_dir", "$g->is_file" etc. To get the size of block devices,
2130 use "$g->blockdev_getsize64".
2131 $fsavail = $g->filesystem_available ($filesystem);
2133 Check whether libguestfs supports the named filesystem. The
2134 argument "filesystem" is a filesystem name, such as "ext3".
2135 You must call "$g->launch" before using this command.
2137 This is mainly useful as a negative test. If this returns true, it
2139 doesn't mean that a particular filesystem can be created or
2140 mounted, since filesystems can fail for other reasons such as it
2141 being a later version of the filesystem, or having incompatible
2142 features, or lacking the right mkfs.<fs> tool.
2143 See also "$g->available", "$g->feature_available", "AVAILABILITY"
2145 in guestfs(3).
2146 @dirents = $g->filesystem_walk ($device);
2148 Walk through the internal structures of a disk partition (eg.
2149 /dev/sda1) in order to return a list of all the files and
2150 directories stored within.
2151 It is not necessary to mount the disk partition to run this
2153 command.
2154 All entries in the filesystem are returned. This function can list
2156 deleted or unaccessible files. The entries are not sorted.
2157 The "tsk_dirent" structure contains the following fields.
2159 "tsk_inode"
2161 Filesystem reference number of the node. It might be 0 if the
2162 node has been deleted.
2163 "tsk_type"
2165 Basic file type information. See below for a detailed list of
2166 values.
2167 "tsk_size"
2169 File size in bytes. It might be "-1" if the node has been
2170 deleted.
2171 "tsk_name"
2173 The file path relative to its directory.
2174 "tsk_flags"
2176 Bitfield containing extra information regarding the entry. It
2177 contains the logical OR of the following values:
2178 0x0001
2180 If set to 1, the file is allocated and visible within the
2181 filesystem. Otherwise, the file has been deleted. Under
2182 certain circumstances, the function "download_inode" can be
2183 used to recover deleted files.
2184 0x0002
2186 Filesystem such as NTFS and Ext2 or greater, separate the
2187 file name from the metadata structure. The bit is set to 1
2188 when the file name is in an unallocated state and the
2189 metadata structure is in an allocated one. This generally
2190 implies the metadata has been reallocated to a new file.
2191 Therefore, information such as file type, file size,
2192 timestamps, number of links and symlink target might not
2193 correspond with the ones of the original deleted entry.
2194 0x0004
2196 The bit is set to 1 when the file is compressed using
2197 filesystem native compression support (NTFS). The API is
2198 not able to detect application level compression.
2199 "tsk_atime_sec"
2201 "tsk_atime_nsec"
2202 "tsk_mtime_sec"
2203 "tsk_mtime_nsec"
2204 "tsk_ctime_sec"
2205 "tsk_ctime_nsec"
2206 "tsk_crtime_sec"
2207 "tsk_crtime_nsec"
2208 Respectively, access, modification, last status change and
2209 creation time in Unix format in seconds and nanoseconds.
2210 "tsk_nlink"
2212 Number of file names pointing to this entry.
2213 "tsk_link"
2215 If the entry is a symbolic link, this field will contain the
2216 path to the target file.
2217 The "tsk_type" field will contain one of the following characters:
2219 'b' Block special
2221 'c' Char special
2223 'd' Directory
2225 'f' FIFO (named pipe)
2227 'l' Symbolic link
2229 'r' Regular file
2231 's' Socket
2233 'h' Shadow inode (Solaris)
2235 'w' Whiteout inode (BSD)
2237 'u' Unknown file type
2239 This function depends on the feature "libtsk". See also
2241 "$g->feature-available".
2242 $g->fill ($c, $len, $path);
2244 This command creates a new file called "path". The initial content
2245 of the file is "len" octets of "c", where "c" must be a number in
2246 the range "[0..255]".
2247 To fill a file with zero bytes (sparsely), it is much more
2249 efficient to use "$g->truncate_size". To create a file with a
2250 pattern of repeating bytes use "$g->fill_pattern".
2251 $g->fill_dir ($dir, $nr);
2253 This function, useful for testing filesystems, creates "nr" empty
2254 files in the directory "dir" with names 00000000 through "nr-1"
2255 (ie. each file name is 8 digits long padded with zeroes).
2256 $g->fill_pattern ($pattern, $len, $path);
2258 This function is like "$g->fill" except that it creates a new file
2259 of length "len" containing the repeating pattern of bytes in
2260 "pattern". The pattern is truncated if necessary to ensure the
2261 length of the file is exactly "len" bytes.
2262 @names = $g->find ($directory);
2264 This command lists out all files and directories, recursively,
2265 starting at directory. It is essentially equivalent to running the
2266 shell command "find directory -print" but some post-processing
2267 happens on the output, described below.
2268 This returns a list of strings without any prefix. Thus if the
2270 directory structure was:
2271 /tmp/a
2273 /tmp/b
2274 /tmp/c/d
2275 then the returned list from "$g->find" /tmp would be 4 elements:
2277 a
2279 b
2280 c
2281 c/d
2282 If directory is not a directory, then this command returns an
2284 error.
2285 The returned list is sorted.
2287 $g->find0 ($directory, $files);
2289 This command lists out all files and directories, recursively,
2290 starting at directory, placing the resulting list in the external
2291 file called files.
2292 This command works the same way as "$g->find" with the following
2294 exceptions:
2295 · The resulting list is written to an external file.
2297 · Items (filenames) in the result are separated by "\0"
2299 characters. See find(1) option -print0.
2300 · The result list is not sorted.
2302 @dirents = $g->find_inode ($device, $inode);
2304 Searches all the entries associated with the given inode.
2305 For each entry, a "tsk_dirent" structure is returned. See
2307 "filesystem_walk" for more information about "tsk_dirent"
2308 structures.
2309 This function depends on the feature "libtsk". See also
2311 "$g->feature-available".
2312 $device = $g->findfs_label ($label);
2314 This command searches the filesystems and returns the one which has
2315 the given label. An error is returned if no such filesystem can be
2316 found.
2317 To find the label of a filesystem, use "$g->vfs_label".
2319 $device = $g->findfs_uuid ($uuid);
2321 This command searches the filesystems and returns the one which has
2322 the given UUID. An error is returned if no such filesystem can be
2323 found.
2324 To find the UUID of a filesystem, use "$g->vfs_uuid".
2326 $status = $g->fsck ($fstype, $device);
2328 This runs the filesystem checker (fsck) on "device" which should
2329 have filesystem type "fstype".
2330 The returned integer is the status. See fsck(8) for the list of
2332 status codes from "fsck".
2333 Notes:
2335 · Multiple status codes can be summed together.
2337 · A non-zero return code can mean "success", for example if
2339 errors have been corrected on the filesystem.
2340 · Checking or repairing NTFS volumes is not supported (by linux-
2342 ntfs).
2343 This command is entirely equivalent to running "fsck -a -t fstype
2345 device".
2346 $g->fstrim ($mountpoint [, offset => $offset] [, length => $length] [,
2348 minimumfreeextent => $minimumfreeextent]);
2349 Trim the free space in the filesystem mounted on "mountpoint". The
2350 filesystem must be mounted read-write.
2351 The filesystem contents are not affected, but any free space in the
2353 filesystem is "trimmed", that is, given back to the host device,
2354 thus making disk images more sparse, allowing unused space in qcow2
2355 files to be reused, etc.
2356 This operation requires support in libguestfs, the mounted
2358 filesystem, the host filesystem, qemu and the host kernel. If this
2359 support isn't present it may give an error or even appear to run
2360 but do nothing.
2361 In the case where the kernel vfs driver does not support trimming,
2363 this call will fail with errno set to "ENOTSUP". Currently this
2364 happens when trying to trim FAT filesystems.
2365 See also "$g->zero_free_space". That is a slightly different
2367 operation that turns free space in the filesystem into zeroes. It
2368 is valid to call "$g->fstrim" either instead of, or after calling
2369 "$g->zero_free_space".
2370 This function depends on the feature "fstrim". See also
2372 "$g->feature-available".
2373 $append = $g->get_append ();
2375 Return the additional kernel options which are added to the
2376 libguestfs appliance kernel command line.
2377 If "NULL" then no options are added.
2379 $backend = $g->get_attach_method ();
2381 Return the current backend.
2382 See "$g->set_backend" and "BACKEND" in guestfs(3).
2384 This function is deprecated. In new code, use the "get_backend"
2386 call instead.
2387 Deprecated functions will not be removed from the API, but the fact
2389 that they are deprecated indicates that there are problems with
2390 correct use of these functions.
2391 $autosync = $g->get_autosync ();
2393 Get the autosync flag.
2394 $backend = $g->get_backend ();
2396 Return the current backend.
2397 This handle property was previously called the "attach method".
2399 See "$g->set_backend" and "BACKEND" in guestfs(3).
2401 $val = $g->get_backend_setting ($name);
2403 Find a backend setting string which is either "name" or begins with
2404 "name=". If "name", this returns the string "1". If "name=", this
2405 returns the part after the equals sign (which may be an empty
2406 string).
2407 If no such setting is found, this function throws an error. The
2409 errno (see "$g->last_errno") will be "ESRCH" in this case.
2410 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
2412 @settings = $g->get_backend_settings ();
2414 Return the current backend settings.
2415 This call returns all backend settings strings. If you want to
2417 find a single backend setting, see "$g->get_backend_setting".
2418 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
2420 $cachedir = $g->get_cachedir ();
2422 Get the directory used by the handle to store the appliance cache.
2423 $direct = $g->get_direct ();
2425 Return the direct appliance mode flag.
2426 This function is deprecated. In new code, use the
2428 "internal_get_console_socket" call instead.
2429 Deprecated functions will not be removed from the API, but the fact
2431 that they are deprecated indicates that there are problems with
2432 correct use of these functions.
2433 $attrs = $g->get_e2attrs ($file);
2435 This returns the file attributes associated with file.
2436 The attributes are a set of bits associated with each inode which
2438 affect the behaviour of the file. The attributes are returned as a
2439 string of letters (described below). The string may be empty,
2440 indicating that no file attributes are set for this file.
2441 These attributes are only present when the file is located on an
2443 ext2/3/4 filesystem. Using this call on other filesystem types
2444 will result in an error.
2445 The characters (file attributes) in the returned string are
2447 currently:
2448 'A' When the file is accessed, its atime is not modified.
2450 'a' The file is append-only.
2452 'c' The file is compressed on-disk.
2454 'D' (Directories only.) Changes to this directory are written
2456 synchronously to disk.
2457 'd' The file is not a candidate for backup (see dump(8)).
2459 'E' The file has compression errors.
2461 'e' The file is using extents.
2463 'h' The file is storing its blocks in units of the filesystem
2465 blocksize instead of sectors.
2466 'I' (Directories only.) The directory is using hashed trees.
2468 'i' The file is immutable. It cannot be modified, deleted or
2470 renamed. No link can be created to this file.
2471 'j' The file is data-journaled.
2473 's' When the file is deleted, all its blocks will be zeroed.
2475 'S' Changes to this file are written synchronously to disk.
2477 'T' (Directories only.) This is a hint to the block allocator that
2479 subdirectories contained in this directory should be spread
2480 across blocks. If not present, the block allocator will try to
2481 group subdirectories together.
2482 't' For a file, this disables tail-merging. (Not used by upstream
2484 implementations of ext2.)
2485 'u' When the file is deleted, its blocks will be saved, allowing
2487 the file to be undeleted.
2488 'X' The raw contents of the compressed file may be accessed.
2490 'Z' The compressed file is dirty.
2492 More file attributes may be added to this list later. Not all file
2494 attributes may be set for all kinds of files. For detailed
2495 information, consult the chattr(1) man page.
2496 See also "$g->set_e2attrs".
2498 Don't confuse these attributes with extended attributes (see
2500 "$g->getxattr").
2501 $generation = $g->get_e2generation ($file);
2503 This returns the ext2 file generation of a file. The generation
2504 (which used to be called the "version") is a number associated with
2505 an inode. This is most commonly used by NFS servers.
2506 The generation is only present when the file is located on an
2508 ext2/3/4 filesystem. Using this call on other filesystem types
2509 will result in an error.
2510 See "$g->set_e2generation".
2512 $label = $g->get_e2label ($device);
2514 This returns the ext2/3/4 filesystem label of the filesystem on
2515 "device".
2516 This function is deprecated. In new code, use the "vfs_label" call
2518 instead.
2519 Deprecated functions will not be removed from the API, but the fact
2521 that they are deprecated indicates that there are problems with
2522 correct use of these functions.
2523 $uuid = $g->get_e2uuid ($device);
2525 This returns the ext2/3/4 filesystem UUID of the filesystem on
2526 "device".
2527 This function is deprecated. In new code, use the "vfs_uuid" call
2529 instead.
2530 Deprecated functions will not be removed from the API, but the fact
2532 that they are deprecated indicates that there are problems with
2533 correct use of these functions.
2534 $hv = $g->get_hv ();
2536 Return the current hypervisor binary.
2537 This is always non-NULL. If it wasn't set already, then this will
2539 return the default qemu binary name.
2540 $identifier = $g->get_identifier ();
2542 Get the handle identifier. See "$g->set_identifier".
2543 $challenge = $g->get_libvirt_requested_credential_challenge ($index);
2545 Get the challenge (provided by libvirt) for the "index"'th
2546 requested credential. If libvirt did not provide a challenge, this
2547 returns the empty string "".
2548 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2550 example code.
2551 $defresult = $g->get_libvirt_requested_credential_defresult ($index);
2553 Get the default result (provided by libvirt) for the "index"'th
2554 requested credential. If libvirt did not provide a default result,
2555 this returns the empty string "".
2556 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2558 example code.
2559 $prompt = $g->get_libvirt_requested_credential_prompt ($index);
2561 Get the prompt (provided by libvirt) for the "index"'th requested
2562 credential. If libvirt did not provide a prompt, this returns the
2563 empty string "".
2564 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2566 example code.
2567 @creds = $g->get_libvirt_requested_credentials ();
2569 This should only be called during the event callback for events of
2570 type "GUESTFS_EVENT_LIBVIRT_AUTH".
2571 Return the list of credentials requested by libvirt. Possible
2573 values are a subset of the strings provided when you called
2574 "$g->set_libvirt_supported_credentials".
2575 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2577 example code.
2578 $memsize = $g->get_memsize ();
2580 This gets the memory size in megabytes allocated to the hypervisor.
2581 If "$g->set_memsize" was not called on this handle, and if
2583 "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
2584 default value for memsize.
2585 For more information on the architecture of libguestfs, see
2587 guestfs(3).
2588 $network = $g->get_network ();
2590 This returns the enable network flag.
2591 $path = $g->get_path ();
2593 Return the current search path.
2594 This is always non-NULL. If it wasn't set already, then this will
2596 return the default path.
2597 $pgroup = $g->get_pgroup ();
2599 This returns the process group flag.
2600 $pid = $g->get_pid ();
2602 Return the process ID of the hypervisor. If there is no hypervisor
2603 running, then this will return an error.
2604 This is an internal call used for debugging and testing.
2606 $program = $g->get_program ();
2608 Get the program name. See "$g->set_program".
2609 $hv = $g->get_qemu ();
2611 Return the current hypervisor binary (usually qemu).
2612 This is always non-NULL. If it wasn't set already, then this will
2614 return the default qemu binary name.
2615 This function is deprecated. In new code, use the "get_hv" call
2617 instead.
2618 Deprecated functions will not be removed from the API, but the fact
2620 that they are deprecated indicates that there are problems with
2621 correct use of these functions.
2622 $recoveryproc = $g->get_recovery_proc ();
2624 Return the recovery process enabled flag.
2625 $selinux = $g->get_selinux ();
2627 This returns the current setting of the selinux flag which is
2628 passed to the appliance at boot time. See "$g->set_selinux".
2629 For more information on the architecture of libguestfs, see
2631 guestfs(3).
2632 This function is deprecated. In new code, use the
2634 "selinux_relabel" call instead.
2635 Deprecated functions will not be removed from the API, but the fact
2637 that they are deprecated indicates that there are problems with
2638 correct use of these functions.
2639 $smp = $g->get_smp ();
2641 This returns the number of virtual CPUs assigned to the appliance.
2642 $sockdir = $g->get_sockdir ();
2644 Get the directory used by the handle to store temporary socket
2645 files.
2646 This is different from "$g->get_tmpdir", as we need shorter paths
2648 for sockets (due to the limited buffers of filenames for UNIX
2649 sockets), and "$g->get_tmpdir" may be too long for them.
2650 The environment variable "XDG_RUNTIME_DIR" controls the default
2652 value: If "XDG_RUNTIME_DIR" is set, then that is the default. Else
2653 /tmp is the default.
2654 $state = $g->get_state ();
2656 This returns the current state as an opaque integer. This is only
2657 useful for printing debug and internal error messages.
2658 For more information on states, see guestfs(3).
2660 $tmpdir = $g->get_tmpdir ();
2662 Get the directory used by the handle to store temporary files.
2663 $trace = $g->get_trace ();
2665 Return the command trace flag.
2666 $mask = $g->get_umask ();
2668 Return the current umask. By default the umask is 022 unless it
2669 has been set by calling "$g->umask".
2670 $verbose = $g->get_verbose ();
2672 This returns the verbose messages flag.
2673 $context = $g->getcon ();
2675 This gets the SELinux security context of the daemon.
2676 See the documentation about SELINUX in guestfs(3), and "$g->setcon"
2678 This function depends on the feature "selinux". See also
2680 "$g->feature-available".
2681 This function is deprecated. In new code, use the
2683 "selinux_relabel" call instead.
2684 Deprecated functions will not be removed from the API, but the fact
2686 that they are deprecated indicates that there are problems with
2687 correct use of these functions.
2688 $xattr = $g->getxattr ($path, $name);
2690 Get a single extended attribute from file "path" named "name".
2691 This call follows symlinks. If you want to lookup an extended
2692 attribute for the symlink itself, use "$g->lgetxattr".
2693 Normally it is better to get all extended attributes from a file in
2695 one go by calling "$g->getxattrs". However some Linux filesystem
2696 implementations are buggy and do not provide a way to list out
2697 attributes. For these filesystems (notably ntfs-3g) you have to
2698 know the names of the extended attributes you want in advance and
2699 call this function.
2700 Extended attribute values are blobs of binary data. If there is no
2702 extended attribute named "name", this returns an error.
2703 See also: "$g->getxattrs", "$g->lgetxattr", attr(5).
2705 This function depends on the feature "linuxxattrs". See also
2707 "$g->feature-available".
2708 @xattrs = $g->getxattrs ($path);
2710 This call lists the extended attributes of the file or directory
2711 "path".
2712 At the system call level, this is a combination of the listxattr(2)
2714 and getxattr(2) calls.
2715 See also: "$g->lgetxattrs", attr(5).
2717 This function depends on the feature "linuxxattrs". See also
2719 "$g->feature-available".
2720 @paths = $g->glob_expand ($pattern [, directoryslash =>
2722 $directoryslash]);
2723 This command searches for all the pathnames matching "pattern"
2724 according to the wildcard expansion rules used by the shell.
2725 If no paths match, then this returns an empty list (note: not an
2727 error).
2728 It is just a wrapper around the C glob(3) function with flags
2730 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
2731 "directoryslash" controls whether use the "GLOB_MARK" flag for
2733 glob(3), and it defaults to true. It can be explicitly set as off
2734 to return no trailing slashes in filenames of directories.
2735 Notice that there is no equivalent command for expanding a device
2737 name (eg. /dev/sd*). Use "$g->list_devices", "$g->list_partitions"
2738 etc functions instead.
2739 @paths = $g->glob_expand_opts ($pattern [, directoryslash =>
2741 $directoryslash]);
2742 This is an alias of "glob_expand".
2743 @lines = $g->grep ($regex, $path [, extended => $extended] [, fixed =>
2745 $fixed] [, insensitive => $insensitive] [, compressed => $compressed]);
2746 This calls the external grep(1) program and returns the matching
2747 lines.
2748 The optional flags are:
2750 "extended"
2752 Use extended regular expressions. This is the same as using
2753 the -E flag.
2754 "fixed"
2756 Match fixed (don't use regular expressions). This is the same
2757 as using the -F flag.
2758 "insensitive"
2760 Match case-insensitive. This is the same as using the -i flag.
2761 "compressed"
2763 Use zgrep(1) instead of grep(1). This allows the input to be
2764 compress- or gzip-compressed.
2765 Because of the message protocol, there is a transfer limit of
2767 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2768 guestfs(3).
2769 @lines = $g->grep_opts ($regex, $path [, extended => $extended] [,
2771 fixed => $fixed] [, insensitive => $insensitive] [, compressed =>
2772 $compressed]);
2773 This is an alias of "grep".
2774 @lines = $g->grepi ($regex, $path);
2776 This calls the external "grep -i" program and returns the matching
2777 lines.
2778 Because of the message protocol, there is a transfer limit of
2780 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2781 guestfs(3).
2782 This function is deprecated. In new code, use the "grep" call
2784 instead.
2785 Deprecated functions will not be removed from the API, but the fact
2787 that they are deprecated indicates that there are problems with
2788 correct use of these functions.
2789 $g->grub_install ($root, $device);
2791 This command installs GRUB 1 (the Grand Unified Bootloader) on
2792 "device", with the root directory being "root".
2793 Notes:
2795 · There is currently no way in the API to install grub2, which is
2797 used by most modern Linux guests. It is possible to run the
2798 grub2 command from the guest, although see the caveats in
2799 "RUNNING COMMANDS" in guestfs(3).
2800 · This uses grub-install(8) from the host. Unfortunately grub is
2802 not always compatible with itself, so this only works in rather
2803 narrow circumstances. Careful testing with each guest version
2804 is advisable.
2805 · If grub-install reports the error "No suitable drive was found
2807 in the generated device map." it may be that you need to
2808 create a /boot/grub/device.map file first that contains the
2809 mapping between grub device names and Linux device names. It
2810 is usually sufficient to create a file containing:
2811 (hd0) /dev/vda
2813 replacing /dev/vda with the name of the installation device.
2815 This function depends on the feature "grub". See also
2817 "$g->feature-available".
2818 @lines = $g->head ($path);
2820 This command returns up to the first 10 lines of a file as a list
2821 of strings.
2822 Because of the message protocol, there is a transfer limit of
2824 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2825 guestfs(3).
2826 @lines = $g->head_n ($nrlines, $path);
2828 If the parameter "nrlines" is a positive number, this returns the
2829 first "nrlines" lines of the file "path".
2830 If the parameter "nrlines" is a negative number, this returns lines
2832 from the file "path", excluding the last "nrlines" lines.
2833 If the parameter "nrlines" is zero, this returns an empty list.
2835 Because of the message protocol, there is a transfer limit of
2837 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2838 guestfs(3).
2839 $dump = $g->hexdump ($path);
2841 This runs "hexdump -C" on the given "path". The result is the
2842 human-readable, canonical hex dump of the file.
2843 Because of the message protocol, there is a transfer limit of
2845 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2846 guestfs(3).
2847 $g->hivex_close ();
2849 Close the current hivex handle.
2850 This is a wrapper around the hivex(3) call of the same name.
2852 This function depends on the feature "hivex". See also
2854 "$g->feature-available".
2855 $g->hivex_commit ($filename);
2857 Commit (write) changes to the hive.
2858 If the optional filename parameter is null, then the changes are
2860 written back to the same hive that was opened. If this is not null
2861 then they are written to the alternate filename given and the
2862 original hive is left untouched.
2863 This is a wrapper around the hivex(3) call of the same name.
2865 This function depends on the feature "hivex". See also
2867 "$g->feature-available".
2868 $nodeh = $g->hivex_node_add_child ($parent, $name);
2870 Add a child node to "parent" named "name".
2871 This is a wrapper around the hivex(3) call of the same name.
2873 This function depends on the feature "hivex". See also
2875 "$g->feature-available".
2876 @nodehs = $g->hivex_node_children ($nodeh);
2878 Return the list of nodes which are subkeys of "nodeh".
2879 This is a wrapper around the hivex(3) call of the same name.
2881 This function depends on the feature "hivex". See also
2883 "$g->feature-available".
2884 $g->hivex_node_delete_child ($nodeh);
2886 Delete "nodeh", recursively if necessary.
2887 This is a wrapper around the hivex(3) call of the same name.
2889 This function depends on the feature "hivex". See also
2891 "$g->feature-available".
2892 $child = $g->hivex_node_get_child ($nodeh, $name);
2894 Return the child of "nodeh" with the name "name", if it exists.
2895 This can return 0 meaning the name was not found.
2896 This is a wrapper around the hivex(3) call of the same name.
2898 This function depends on the feature "hivex". See also
2900 "$g->feature-available".
2901 $valueh = $g->hivex_node_get_value ($nodeh, $key);
2903 Return the value attached to "nodeh" which has the name "key", if
2904 it exists. This can return 0 meaning the key was not found.
2905 This is a wrapper around the hivex(3) call of the same name.
2907 This function depends on the feature "hivex". See also
2909 "$g->feature-available".
2910 $name = $g->hivex_node_name ($nodeh);
2912 Return the name of "nodeh".
2913 This is a wrapper around the hivex(3) call of the same name.
2915 This function depends on the feature "hivex". See also
2917 "$g->feature-available".
2918 $parent = $g->hivex_node_parent ($nodeh);
2920 Return the parent node of "nodeh".
2921 This is a wrapper around the hivex(3) call of the same name.
2923 This function depends on the feature "hivex". See also
2925 "$g->feature-available".
2926 $g->hivex_node_set_value ($nodeh, $key, $t, $val);
2928 Set or replace a single value under the node "nodeh". The "key" is
2929 the name, "t" is the type, and "val" is the data.
2930 This is a wrapper around the hivex(3) call of the same name.
2932 This function depends on the feature "hivex". See also
2934 "$g->feature-available".
2935 @valuehs = $g->hivex_node_values ($nodeh);
2937 Return the array of (key, datatype, data) tuples attached to
2938 "nodeh".
2939 This is a wrapper around the hivex(3) call of the same name.
2941 This function depends on the feature "hivex". See also
2943 "$g->feature-available".
2944 $g->hivex_open ($filename [, verbose => $verbose] [, debug => $debug]
2946 [, write => $write] [, unsafe => $unsafe]);
2947 Open the Windows Registry hive file named filename. If there was
2948 any previous hivex handle associated with this guestfs session,
2949 then it is closed.
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 $nodeh = $g->hivex_root ();
2957 Return the root node of the hive.
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 $key = $g->hivex_value_key ($valueh);
2965 Return the key (name) field of a (key, datatype, data) tuple.
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 $databuf = $g->hivex_value_string ($valueh);
2973 This calls "$g->hivex_value_value" (which returns the data field
2974 from a hivex value tuple). It then assumes that the field is a
2975 UTF-16LE string and converts the result to UTF-8 (or if this is not
2976 possible, it returns an error).
2977 This is useful for reading strings out of the Windows registry.
2979 However it is not foolproof because the registry is not strongly-
2980 typed and fields can contain arbitrary or unexpected data.
2981 This function depends on the feature "hivex". See also
2983 "$g->feature-available".
2984 $datatype = $g->hivex_value_type ($valueh);
2986 Return the data type field from a (key, datatype, data) tuple.
2987 This is a wrapper around the hivex(3) call of the same name.
2989 This function depends on the feature "hivex". See also
2991 "$g->feature-available".
2992 $databuf = $g->hivex_value_utf8 ($valueh);
2994 This calls "$g->hivex_value_value" (which returns the data field
2995 from a hivex value tuple). It then assumes that the field is a
2996 UTF-16LE string and converts the result to UTF-8 (or if this is not
2997 possible, it returns an error).
2998 This is useful for reading strings out of the Windows registry.
3000 However it is not foolproof because the registry is not strongly-
3001 typed and fields can contain arbitrary or unexpected data.
3002 This function depends on the feature "hivex". See also
3004 "$g->feature-available".
3005 This function is deprecated. In new code, use the
3007 "hivex_value_string" call instead.
3008 Deprecated functions will not be removed from the API, but the fact
3010 that they are deprecated indicates that there are problems with
3011 correct use of these functions.
3012 $databuf = $g->hivex_value_value ($valueh);
3014 Return the data field of a (key, datatype, data) tuple.
3015 This is a wrapper around the hivex(3) call of the same name.
3017 See also: "$g->hivex_value_utf8".
3019 This function depends on the feature "hivex". See also
3021 "$g->feature-available".
3022 $content = $g->initrd_cat ($initrdpath, $filename);
3024 This command unpacks the file filename from the initrd file called
3025 initrdpath. The filename must be given without the initial /
3026 character.
3027 For example, in guestfish you could use the following command to
3029 examine the boot script (usually called /init) contained in a Linux
3030 initrd or initramfs image:
3031 initrd-cat /boot/initrd-<version>.img init
3033 See also "$g->initrd_list".
3035 Because of the message protocol, there is a transfer limit of
3037 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
3038 guestfs(3).
3039 @filenames = $g->initrd_list ($path);
3041 This command lists out files contained in an initrd.
3042 The files are listed without any initial / character. The files
3044 are listed in the order they appear (not necessarily alphabetical).
3045 Directory names are listed as separate items.
3046 Old Linux kernels (2.4 and earlier) used a compressed ext2
3048 filesystem as initrd. We only support the newer initramfs format
3049 (compressed cpio files).
3050 $wd = $g->inotify_add_watch ($path, $mask);
3052 Watch "path" for the events listed in "mask".
3053 Note that if "path" is a directory then events within that
3055 directory are watched, but this does not happen recursively (in
3056 subdirectories).
3057 Note for non-C or non-Linux callers: the inotify events are defined
3059 by the Linux kernel ABI and are listed in
3060 /usr/include/sys/inotify.h.
3061 This function depends on the feature "inotify". See also
3063 "$g->feature-available".
3064 $g->inotify_close ();
3066 This closes the inotify handle which was previously opened by
3067 inotify_init. It removes all watches, throws away any pending
3068 events, and deallocates all resources.
3069 This function depends on the feature "inotify". See also
3071 "$g->feature-available".
3072 @paths = $g->inotify_files ();
3074 This function is a helpful wrapper around "$g->inotify_read" which
3075 just returns a list of pathnames of objects that were touched. The
3076 returned pathnames are sorted and deduplicated.
3077 This function depends on the feature "inotify". See also
3079 "$g->feature-available".
3080 $g->inotify_init ($maxevents);
3082 This command creates a new inotify handle. The inotify subsystem
3083 can be used to notify events which happen to objects in the guest
3084 filesystem.
3085 "maxevents" is the maximum number of events which will be queued up
3087 between calls to "$g->inotify_read" or "$g->inotify_files". If
3088 this is passed as 0, then the kernel (or previously set) default is
3089 used. For Linux 2.6.29 the default was 16384 events. Beyond this
3090 limit, the kernel throws away events, but records the fact that it
3091 threw them away by setting a flag "IN_Q_OVERFLOW" in the returned
3092 structure list (see "$g->inotify_read").
3093 Before any events are generated, you have to add some watches to
3095 the internal watch list. See: "$g->inotify_add_watch" and
3096 "$g->inotify_rm_watch".
3097 Queued up events should be read periodically by calling
3099 "$g->inotify_read" (or "$g->inotify_files" which is just a helpful
3100 wrapper around "$g->inotify_read"). If you don't read the events
3101 out often enough then you risk the internal queue overflowing.
3102 The handle should be closed after use by calling
3104 "$g->inotify_close". This also removes any watches automatically.
3105 See also inotify(7) for an overview of the inotify interface as
3107 exposed by the Linux kernel, which is roughly what we expose via
3108 libguestfs. Note that there is one global inotify handle per
3109 libguestfs instance.
3110 This function depends on the feature "inotify". See also
3112 "$g->feature-available".
3113 @events = $g->inotify_read ();
3115 Return the complete queue of events that have happened since the
3116 previous read call.
3117 If no events have happened, this returns an empty list.
3119 Note: In order to make sure that all events have been read, you
3121 must call this function repeatedly until it returns an empty list.
3122 The reason is that the call will read events up to the maximum
3123 appliance-to-host message size and leave remaining events in the
3124 queue.
3125 This function depends on the feature "inotify". See also
3127 "$g->feature-available".
3128 $g->inotify_rm_watch ($wd);
3130 Remove a previously defined inotify watch. See
3131 "$g->inotify_add_watch".
3132 This function depends on the feature "inotify". See also
3134 "$g->feature-available".
3135 $arch = $g->inspect_get_arch ($root);
3137 This returns the architecture of the inspected operating system.
3138 The possible return values are listed under
3139 "$g->file_architecture".
3140 If the architecture could not be determined, then the string
3142 "unknown" is returned.
3143 Please read "INSPECTION" in guestfs(3) for more details.
3145 $distro = $g->inspect_get_distro ($root);
3147 This returns the distro (distribution) of the inspected operating
3148 system.
3149 Currently defined distros are:
3151 "alpinelinux"
3153 Alpine Linux.
3154 "altlinux"
3156 ALT Linux.
3157 "archlinux"
3159 Arch Linux.
3160 "buildroot"
3162 Buildroot-derived distro, but not one we specifically
3163 recognize.
3164 "centos"
3166 CentOS.
3167 "cirros"
3169 Cirros.
3170 "coreos"
3172 CoreOS.
3173 "debian"
3175 Debian.
3176 "fedora"
3178 Fedora.
3179 "freebsd"
3181 FreeBSD.
3182 "freedos"
3184 FreeDOS.
3185 "frugalware"
3187 Frugalware.
3188 "gentoo"
3190 Gentoo.
3191 "kalilinux"
3193 Kali Linux.
3194 "linuxmint"
3196 Linux Mint.
3197 "mageia"
3199 Mageia.
3200 "mandriva"
3202 Mandriva.
3203 "meego"
3205 MeeGo.
3206 "msdos"
3208 Microsoft DOS.
3209 "neokylin"
3211 NeoKylin.
3212 "netbsd"
3214 NetBSD.
3215 "openbsd"
3217 OpenBSD.
3218 "openmandriva"
3220 OpenMandriva Lx.
3221 "opensuse"
3223 OpenSUSE.
3224 "oraclelinux"
3226 Oracle Linux.
3227 "pardus"
3229 Pardus.
3230 "pldlinux"
3232 PLD Linux.
3233 "redhat-based"
3235 Some Red Hat-derived distro.
3236 "rhel"
3238 Red Hat Enterprise Linux.
3239 "scientificlinux"
3241 Scientific Linux.
3242 "slackware"
3244 Slackware.
3245 "sles"
3247 SuSE Linux Enterprise Server or Desktop.
3248 "suse-based"
3250 Some openSuSE-derived distro.
3251 "ttylinux"
3253 ttylinux.
3254 "ubuntu"
3256 Ubuntu.
3257 "unknown"
3259 The distro could not be determined.
3260 "voidlinux"
3262 Void Linux.
3263 "windows"
3265 Windows does not have distributions. This string is returned
3266 if the OS type is Windows.
3267 Future versions of libguestfs may return other strings here. The
3269 caller should be prepared to handle any string.
3270 Please read "INSPECTION" in guestfs(3) for more details.
3272 %drives = $g->inspect_get_drive_mappings ($root);
3274 This call is useful for Windows which uses a primitive system of
3275 assigning drive letters (like C:\) to partitions. This inspection
3276 API examines the Windows Registry to find out how disks/partitions
3277 are mapped to drive letters, and returns a hash table as in the
3278 example below:
3279 C => /dev/vda2
3281 E => /dev/vdb1
3282 F => /dev/vdc1
3283 Note that keys are drive letters. For Windows, the key is case
3285 insensitive and just contains the drive letter, without the
3286 customary colon separator character.
3287 In future we may support other operating systems that also used
3289 drive letters, but the keys for those might not be case insensitive
3290 and might be longer than 1 character. For example in OS-9, hard
3291 drives were named "h0", "h1" etc.
3292 For Windows guests, currently only hard drive mappings are
3294 returned. Removable disks (eg. DVD-ROMs) are ignored.
3295 For guests that do not use drive mappings, or if the drive mappings
3297 could not be determined, this returns an empty hash table.
3298 Please read "INSPECTION" in guestfs(3) for more details. See also
3300 "$g->inspect_get_mountpoints", "$g->inspect_get_filesystems".
3301 @filesystems = $g->inspect_get_filesystems ($root);
3303 This returns a list of all the filesystems that we think are
3304 associated with this operating system. This includes the root
3305 filesystem, other ordinary filesystems, and non-mounted devices
3306 like swap partitions.
3307 In the case of a multi-boot virtual machine, it is possible for a
3309 filesystem to be shared between operating systems.
3310 Please read "INSPECTION" in guestfs(3) for more details. See also
3312 "$g->inspect_get_mountpoints".
3313 $format = $g->inspect_get_format ($root);
3315 Before libguestfs 1.38, there was some unreliable support for
3316 detecting installer CDs. This API would return:
3317 "installed"
3319 This is an installed operating system.
3320 "installer"
3322 The disk image being inspected is not an installed operating
3323 system, but a bootable install disk, live CD, or similar.
3324 "unknown"
3326 The format of this disk image is not known.
3327 In libguestfs X 1.38, this only returns "installed". Use libosinfo
3329 directly to detect installer CDs.
3330 Please read "INSPECTION" in guestfs(3) for more details.
3332 This function is deprecated. There is no replacement. Consult the
3334 API documentation in guestfs(3) for further information.
3335 Deprecated functions will not be removed from the API, but the fact
3337 that they are deprecated indicates that there are problems with
3338 correct use of these functions.
3339 $hostname = $g->inspect_get_hostname ($root);
3341 This function returns the hostname of the operating system as found
3342 by inspection of the guestXs configuration files.
3343 If the hostname could not be determined, then the string "unknown"
3345 is returned.
3346 Please read "INSPECTION" in guestfs(3) for more details.
3348 $icon = $g->inspect_get_icon ($root [, favicon => $favicon] [,
3350 highquality => $highquality]);
3351 This function returns an icon corresponding to the inspected
3352 operating system. The icon is returned as a buffer containing a
3353 PNG image (re-encoded to PNG if necessary).
3354 If it was not possible to get an icon this function returns a zero-
3356 length (non-NULL) buffer. Callers must check for this case.
3357 Libguestfs will start by looking for a file called /etc/favicon.png
3359 or C:\etc\favicon.png and if it has the correct format, the
3360 contents of this file will be returned. You can disable favicons
3361 by passing the optional "favicon" boolean as false (default is
3362 true).
3363 If finding the favicon fails, then we look in other places in the
3365 guest for a suitable icon.
3366 If the optional "highquality" boolean is true then only high
3368 quality icons are returned, which means only icons of high
3369 resolution with an alpha channel. The default (false) is to return
3370 any icon we can, even if it is of substandard quality.
3371 Notes:
3373 · Unlike most other inspection API calls, the guestXs disks must
3375 be mounted up before you call this, since it needs to read
3376 information from the guest filesystem during the call.
3377 · Security: The icon data comes from the untrusted guest, and
3379 should be treated with caution. PNG files have been known to
3380 contain exploits. Ensure that libpng (or other relevant
3381 libraries) are fully up to date before trying to process or
3382 display the icon.
3383 · The PNG image returned can be any size. It might not be
3385 square. Libguestfs tries to return the largest, highest
3386 quality icon available. The application must scale the icon to
3387 the required size.
3388 · Extracting icons from Windows guests requires the external
3390 wrestool(1) program from the "icoutils" package, and several
3391 programs (bmptopnm(1), pnmtopng(1), pamcut(1)) from the
3392 "netpbm" package. These must be installed separately.
3393 · Operating system icons are usually trademarks. Seek legal
3395 advice before using trademarks in applications.
3396 $major = $g->inspect_get_major_version ($root);
3398 This returns the major version number of the inspected operating
3399 system.
3400 Windows uses a consistent versioning scheme which is not reflected
3402 in the popular public names used by the operating system. Notably
3403 the operating system known as "Windows 7" is really version 6.1
3404 (ie. major = 6, minor = 1). You can find out the real versions
3405 corresponding to releases of Windows by consulting Wikipedia or
3406 MSDN.
3407 If the version could not be determined, then 0 is returned.
3409 Please read "INSPECTION" in guestfs(3) for more details.
3411 $minor = $g->inspect_get_minor_version ($root);
3413 This returns the minor version number of the inspected operating
3414 system.
3415 If the version could not be determined, then 0 is returned.
3417 Please read "INSPECTION" in guestfs(3) for more details. See also
3419 "$g->inspect_get_major_version".
3420 %mountpoints = $g->inspect_get_mountpoints ($root);
3422 This returns a hash of where we think the filesystems associated
3423 with this operating system should be mounted. Callers should note
3424 that this is at best an educated guess made by reading
3425 configuration files such as /etc/fstab. In particular note that
3426 this may return filesystems which are non-existent or not mountable
3427 and callers should be prepared to handle or ignore failures if they
3428 try to mount them.
3429 Each element in the returned hashtable has a key which is the path
3431 of the mountpoint (eg. /boot) and a value which is the filesystem
3432 that would be mounted there (eg. /dev/sda1).
3433 Non-mounted devices such as swap devices are not returned in this
3435 list.
3436 For operating systems like Windows which still use drive letters,
3438 this call will only return an entry for the first drive "mounted
3439 on" /. For information about the mapping of drive letters to
3440 partitions, see "$g->inspect_get_drive_mappings".
3441 Please read "INSPECTION" in guestfs(3) for more details. See also
3443 "$g->inspect_get_filesystems".
3444 $id = $g->inspect_get_osinfo ($root);
3446 This function returns a possible short ID for libosinfo
3447 corresponding to the guest.
3448 Note: The returned ID is only a guess by libguestfs, and nothing
3450 ensures that it actually exists in osinfo-db.
3451 If no ID could not be determined, then the string "unknown" is
3453 returned.
3454 $packageformat = $g->inspect_get_package_format ($root);
3456 This function and "$g->inspect_get_package_management" return the
3457 package format and package management tool used by the inspected
3458 operating system. For example for Fedora these functions would
3459 return "rpm" (package format), and "yum" or "dnf" (package
3460 management).
3461 This returns the string "unknown" if we could not determine the
3463 package format or if the operating system does not have a real
3464 packaging system (eg. Windows).
3465 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
3467 "pkgsrc", "apk", "xbps". Future versions of libguestfs may return
3468 other strings.
3469 Please read "INSPECTION" in guestfs(3) for more details.
3471 $packagemanagement = $g->inspect_get_package_management ($root);
3473 "$g->inspect_get_package_format" and this function return the
3474 package format and package management tool used by the inspected
3475 operating system. For example for Fedora these functions would
3476 return "rpm" (package format), and "yum" or "dnf" (package
3477 management).
3478 This returns the string "unknown" if we could not determine the
3480 package management tool or if the operating system does not have a
3481 real packaging system (eg. Windows).
3482 Possible strings include: "yum", "dnf", "up2date", "apt" (for all
3484 Debian derivatives), "portage", "pisi", "pacman", "urpmi",
3485 "zypper", "apk", "xbps". Future versions of libguestfs may return
3486 other strings.
3487 Please read "INSPECTION" in guestfs(3) for more details.
3489 $product = $g->inspect_get_product_name ($root);
3491 This returns the product name of the inspected operating system.
3492 The product name is generally some freeform string which can be
3493 displayed to the user, but should not be parsed by programs.
3494 If the product name could not be determined, then the string
3496 "unknown" is returned.
3497 Please read "INSPECTION" in guestfs(3) for more details.
3499 $variant = $g->inspect_get_product_variant ($root);
3501 This returns the product variant of the inspected operating system.
3502 For Windows guests, this returns the contents of the Registry key
3504 "HKLM\Software\Microsoft\Windows NT\CurrentVersion"
3505 "InstallationType" which is usually a string such as "Client" or
3506 "Server" (other values are possible). This can be used to
3507 distinguish consumer and enterprise versions of Windows that have
3508 the same version number (for example, Windows 7 and Windows 2008
3509 Server are both version 6.1, but the former is "Client" and the
3510 latter is "Server").
3511 For enterprise Linux guests, in future we intend this to return the
3513 product variant such as "Desktop", "Server" and so on. But this is
3514 not implemented at present.
3515 If the product variant could not be determined, then the string
3517 "unknown" is returned.
3518 Please read "INSPECTION" in guestfs(3) for more details. See also
3520 "$g->inspect_get_product_name", "$g->inspect_get_major_version".
3521 @roots = $g->inspect_get_roots ();
3523 This function is a convenient way to get the list of root devices,
3524 as returned from a previous call to "$g->inspect_os", but without
3525 redoing the whole inspection process.
3526 This returns an empty list if either no root devices were found or
3528 the caller has not called "$g->inspect_os".
3529 Please read "INSPECTION" in guestfs(3) for more details.
3531 $name = $g->inspect_get_type ($root);
3533 This returns the type of the inspected operating system. Currently
3534 defined types are:
3535 "linux"
3537 Any Linux-based operating system.
3538 "windows"
3540 Any Microsoft Windows operating system.
3541 "freebsd"
3543 FreeBSD.
3544 "netbsd"
3546 NetBSD.
3547 "openbsd"
3549 OpenBSD.
3550 "hurd"
3552 GNU/Hurd.
3553 "dos"
3555 MS-DOS, FreeDOS and others.
3556 "minix"
3558 MINIX.
3559 "unknown"
3561 The operating system type could not be determined.
3562 Future versions of libguestfs may return other strings here. The
3564 caller should be prepared to handle any string.
3565 Please read "INSPECTION" in guestfs(3) for more details.
3567 $controlset = $g->inspect_get_windows_current_control_set ($root);
3569 This returns the Windows CurrentControlSet of the inspected guest.
3570 The CurrentControlSet is a registry key name such as
3571 "ControlSet001".
3572 This call assumes that the guest is Windows and that the Registry
3574 could be examined by inspection. If this is not the case then an
3575 error is returned.
3576 Please read "INSPECTION" in guestfs(3) for more details.
3578 $path = $g->inspect_get_windows_software_hive ($root);
3580 This returns the path to the hive (binary Windows Registry file)
3581 corresponding to HKLM\SOFTWARE.
3582 This call assumes that the guest is Windows and that the guest has
3584 a software hive file with the right name. If this is not the case
3585 then an error is returned. This call does not check that the hive
3586 is a valid Windows Registry hive.
3587 You can use "$g->hivex_open" to read or write to the hive.
3589 Please read "INSPECTION" in guestfs(3) for more details.
3591 $path = $g->inspect_get_windows_system_hive ($root);
3593 This returns the path to the hive (binary Windows Registry file)
3594 corresponding to HKLM\SYSTEM.
3595 This call assumes that the guest is Windows and that the guest has
3597 a system hive file with the right name. If this is not the case
3598 then an error is returned. This call does not check that the hive
3599 is a valid Windows Registry hive.
3600 You can use "$g->hivex_open" to read or write to the hive.
3602 Please read "INSPECTION" in guestfs(3) for more details.
3604 $systemroot = $g->inspect_get_windows_systemroot ($root);
3606 This returns the Windows systemroot of the inspected guest. The
3607 systemroot is a directory path such as /WINDOWS.
3608 This call assumes that the guest is Windows and that the systemroot
3610 could be determined by inspection. If this is not the case then an
3611 error is returned.
3612 Please read "INSPECTION" in guestfs(3) for more details.
3614 $live = $g->inspect_is_live ($root);
3616 This is deprecated and always returns "false".
3617 Please read "INSPECTION" in guestfs(3) for more details.
3619 This function is deprecated. There is no replacement. Consult the
3621 API documentation in guestfs(3) for further information.
3622 Deprecated functions will not be removed from the API, but the fact
3624 that they are deprecated indicates that there are problems with
3625 correct use of these functions.
3626 $multipart = $g->inspect_is_multipart ($root);
3628 This is deprecated and always returns "false".
3629 Please read "INSPECTION" in guestfs(3) for more details.
3631 This function is deprecated. There is no replacement. Consult the
3633 API documentation in guestfs(3) for further information.
3634 Deprecated functions will not be removed from the API, but the fact
3636 that they are deprecated indicates that there are problems with
3637 correct use of these functions.
3638 $netinst = $g->inspect_is_netinst ($root);
3640 This is deprecated and always returns "false".
3641 Please read "INSPECTION" in guestfs(3) for more details.
3643 This function is deprecated. There is no replacement. Consult the
3645 API documentation in guestfs(3) for further information.
3646 Deprecated functions will not be removed from the API, but the fact
3648 that they are deprecated indicates that there are problems with
3649 correct use of these functions.
3650 @applications = $g->inspect_list_applications ($root);
3652 Return the list of applications installed in the operating system.
3653 Note: This call works differently from other parts of the
3655 inspection API. You have to call "$g->inspect_os", then
3656 "$g->inspect_get_mountpoints", then mount up the disks, before
3657 calling this. Listing applications is a significantly more
3658 difficult operation which requires access to the full filesystem.
3659 Also note that unlike the other "$g->inspect_get_*" calls which are
3660 just returning data cached in the libguestfs handle, this call
3661 actually reads parts of the mounted filesystems during the call.
3662 This returns an empty list if the inspection code was not able to
3664 determine the list of applications.
3665 The application structure contains the following fields:
3667 "app_name"
3669 The name of the application. For Linux guests, this is the
3670 package name.
3671 "app_display_name"
3673 The display name of the application, sometimes localized to the
3674 install language of the guest operating system.
3675 If unavailable this is returned as an empty string "". Callers
3677 needing to display something can use "app_name" instead.
3678 "app_epoch"
3680 For package managers which use epochs, this contains the epoch
3681 of the package (an integer). If unavailable, this is returned
3682 as 0.
3683 "app_version"
3685 The version string of the application or package. If
3686 unavailable this is returned as an empty string "".
3687 "app_release"
3689 The release string of the application or package, for package
3690 managers that use this. If unavailable this is returned as an
3691 empty string "".
3692 "app_install_path"
3694 The installation path of the application (on operating systems
3695 such as Windows which use installation paths). This path is in
3696 the format used by the guest operating system, it is not a
3697 libguestfs path.
3698 If unavailable this is returned as an empty string "".
3700 "app_trans_path"
3702 The install path translated into a libguestfs path. If
3703 unavailable this is returned as an empty string "".
3704 "app_publisher"
3706 The name of the publisher of the application, for package
3707 managers that use this. If unavailable this is returned as an
3708 empty string "".
3709 "app_url"
3711 The URL (eg. upstream URL) of the application. If unavailable
3712 this is returned as an empty string "".
3713 "app_source_package"
3715 For packaging systems which support this, the name of the
3716 source package. If unavailable this is returned as an empty
3717 string "".
3718 "app_summary"
3720 A short (usually one line) description of the application or
3721 package. If unavailable this is returned as an empty string
3722 "".
3723 "app_description"
3725 A longer description of the application or package. If
3726 unavailable this is returned as an empty string "".
3727 Please read "INSPECTION" in guestfs(3) for more details.
3729 This function is deprecated. In new code, use the
3731 "inspect_list_applications2" call instead.
3732 Deprecated functions will not be removed from the API, but the fact
3734 that they are deprecated indicates that there are problems with
3735 correct use of these functions.
3736 @applications2 = $g->inspect_list_applications2 ($root);
3738 Return the list of applications installed in the operating system.
3739 Note: This call works differently from other parts of the
3741 inspection API. You have to call "$g->inspect_os", then
3742 "$g->inspect_get_mountpoints", then mount up the disks, before
3743 calling this. Listing applications is a significantly more
3744 difficult operation which requires access to the full filesystem.
3745 Also note that unlike the other "$g->inspect_get_*" calls which are
3746 just returning data cached in the libguestfs handle, this call
3747 actually reads parts of the mounted filesystems during the call.
3748 This returns an empty list if the inspection code was not able to
3750 determine the list of applications.
3751 The application structure contains the following fields:
3753 "app2_name"
3755 The name of the application. For Linux guests, this is the
3756 package name.
3757 "app2_display_name"
3759 The display name of the application, sometimes localized to the
3760 install language of the guest operating system.
3761 If unavailable this is returned as an empty string "". Callers
3763 needing to display something can use "app2_name" instead.
3764 "app2_epoch"
3766 For package managers which use epochs, this contains the epoch
3767 of the package (an integer). If unavailable, this is returned
3768 as 0.
3769 "app2_version"
3771 The version string of the application or package. If
3772 unavailable this is returned as an empty string "".
3773 "app2_release"
3775 The release string of the application or package, for package
3776 managers that use this. If unavailable this is returned as an
3777 empty string "".
3778 "app2_arch"
3780 The architecture string of the application or package, for
3781 package managers that use this. If unavailable this is
3782 returned as an empty string "".
3783 "app2_install_path"
3785 The installation path of the application (on operating systems
3786 such as Windows which use installation paths). This path is in
3787 the format used by the guest operating system, it is not a
3788 libguestfs path.
3789 If unavailable this is returned as an empty string "".
3791 "app2_trans_path"
3793 The install path translated into a libguestfs path. If
3794 unavailable this is returned as an empty string "".
3795 "app2_publisher"
3797 The name of the publisher of the application, for package
3798 managers that use this. If unavailable this is returned as an
3799 empty string "".
3800 "app2_url"
3802 The URL (eg. upstream URL) of the application. If unavailable
3803 this is returned as an empty string "".
3804 "app2_source_package"
3806 For packaging systems which support this, the name of the
3807 source package. If unavailable this is returned as an empty
3808 string "".
3809 "app2_summary"
3811 A short (usually one line) description of the application or
3812 package. If unavailable this is returned as an empty string
3813 "".
3814 "app2_description"
3816 A longer description of the application or package. If
3817 unavailable this is returned as an empty string "".
3818 Please read "INSPECTION" in guestfs(3) for more details.
3820 @roots = $g->inspect_os ();
3822 This function uses other libguestfs functions and certain
3823 heuristics to inspect the disk(s) (usually disks belonging to a
3824 virtual machine), looking for operating systems.
3825 The list returned is empty if no operating systems were found.
3827 If one operating system was found, then this returns a list with a
3829 single element, which is the name of the root filesystem of this
3830 operating system. It is also possible for this function to return
3831 a list containing more than one element, indicating a dual-boot or
3832 multi-boot virtual machine, with each element being the root
3833 filesystem of one of the operating systems.
3834 You can pass the root string(s) returned to other
3836 "$g->inspect_get_*" functions in order to query further information
3837 about each operating system, such as the name and version.
3838 This function uses other libguestfs features such as "$g->mount_ro"
3840 and "$g->umount_all" in order to mount and unmount filesystems and
3841 look at the contents. This should be called with no disks
3842 currently mounted. The function may also use Augeas, so any
3843 existing Augeas handle will be closed.
3844 This function cannot decrypt encrypted disks. The caller must do
3846 that first (supplying the necessary keys) if the disk is encrypted.
3847 Please read "INSPECTION" in guestfs(3) for more details.
3849 See also "$g->list_filesystems".
3851 $flag = $g->is_blockdev ($path [, followsymlinks => $followsymlinks]);
3853 This returns "true" if and only if there is a block device with the
3854 given "path" name.
3855 If the optional flag "followsymlinks" is true, then a symlink (or
3857 chain of symlinks) that ends with a block device also causes the
3858 function to return true.
3859 This call only looks at files within the guest filesystem.
3861 Libguestfs partitions and block devices (eg. /dev/sda) cannot be
3862 used as the "path" parameter of this call.
3863 See also "$g->stat".
3865 $flag = $g->is_blockdev_opts ($path [, followsymlinks =>
3867 $followsymlinks]);
3868 This is an alias of "is_blockdev".
3869 $busy = $g->is_busy ();
3871 This always returns false. This function is deprecated with no
3872 replacement. Do not use this function.
3873 For more information on states, see guestfs(3).
3875 $flag = $g->is_chardev ($path [, followsymlinks => $followsymlinks]);
3877 This returns "true" if and only if there is a character device with
3878 the given "path" name.
3879 If the optional flag "followsymlinks" is true, then a symlink (or
3881 chain of symlinks) that ends with a chardev also causes the
3882 function to return true.
3883 See also "$g->stat".
3885 $flag = $g->is_chardev_opts ($path [, followsymlinks =>
3887 $followsymlinks]);
3888 This is an alias of "is_chardev".
3889 $config = $g->is_config ();
3891 This returns true iff this handle is being configured (in the
3892 "CONFIG" state).
3893 For more information on states, see guestfs(3).
3895 $dirflag = $g->is_dir ($path [, followsymlinks => $followsymlinks]);
3897 This returns "true" if and only if there is a directory with the
3898 given "path" name. Note that it returns false for other objects
3899 like files.
3900 If the optional flag "followsymlinks" is true, then a symlink (or
3902 chain of symlinks) that ends with a directory also causes the
3903 function to return true.
3904 See also "$g->stat".
3906 $dirflag = $g->is_dir_opts ($path [, followsymlinks =>
3908 $followsymlinks]);
3909 This is an alias of "is_dir".
3910 $flag = $g->is_fifo ($path [, followsymlinks => $followsymlinks]);
3912 This returns "true" if and only if there is a FIFO (named pipe)
3913 with the given "path" name.
3914 If the optional flag "followsymlinks" is true, then a symlink (or
3916 chain of symlinks) that ends with a FIFO also causes the function
3917 to return true.
3918 See also "$g->stat".
3920 $flag = $g->is_fifo_opts ($path [, followsymlinks => $followsymlinks]);
3922 This is an alias of "is_fifo".
3923 $fileflag = $g->is_file ($path [, followsymlinks => $followsymlinks]);
3925 This returns "true" if and only if there is a regular file with the
3926 given "path" name. Note that it returns false for other objects
3927 like directories.
3928 If the optional flag "followsymlinks" is true, then a symlink (or
3930 chain of symlinks) that ends with a file also causes the function
3931 to return true.
3932 See also "$g->stat".
3934 $fileflag = $g->is_file_opts ($path [, followsymlinks =>
3936 $followsymlinks]);
3937 This is an alias of "is_file".
3938 $launching = $g->is_launching ();
3940 This returns true iff this handle is launching the subprocess (in
3941 the "LAUNCHING" state).
3942 For more information on states, see guestfs(3).
3944 $lvflag = $g->is_lv ($mountable);
3946 This command tests whether "mountable" is a logical volume, and
3947 returns true iff this is the case.
3948 $ready = $g->is_ready ();
3950 This returns true iff this handle is ready to accept commands (in
3951 the "READY" state).
3952 For more information on states, see guestfs(3).
3954 $flag = $g->is_socket ($path [, followsymlinks => $followsymlinks]);
3956 This returns "true" if and only if there is a Unix domain socket
3957 with the given "path" name.
3958 If the optional flag "followsymlinks" is true, then a symlink (or
3960 chain of symlinks) that ends with a socket also causes the function
3961 to return true.
3962 See also "$g->stat".
3964 $flag = $g->is_socket_opts ($path [, followsymlinks =>
3966 $followsymlinks]);
3967 This is an alias of "is_socket".
3968 $flag = $g->is_symlink ($path);
3970 This returns "true" if and only if there is a symbolic link with
3971 the given "path" name.
3972 See also "$g->stat".
3974 $flag = $g->is_whole_device ($device);
3976 This returns "true" if and only if "device" refers to a whole block
3977 device. That is, not a partition or a logical device.
3978 $zeroflag = $g->is_zero ($path);
3980 This returns true iff the file exists and the file is empty or it
3981 contains all zero bytes.
3982 $zeroflag = $g->is_zero_device ($device);
3984 This returns true iff the device exists and contains all zero
3985 bytes.
3986 Note that for large devices this can take a long time to run.
3988 %isodata = $g->isoinfo ($isofile);
3990 This is the same as "$g->isoinfo_device" except that it works for
3991 an ISO file located inside some other mounted filesystem. Note
3992 that in the common case where you have added an ISO file as a
3993 libguestfs device, you would not call this. Instead you would call
3994 "$g->isoinfo_device".
3995 %isodata = $g->isoinfo_device ($device);
3997 "device" is an ISO device. This returns a struct of information
3998 read from the primary volume descriptor (the ISO equivalent of the
3999 superblock) of the device.
4000 Usually it is more efficient to use the isoinfo(1) command with the
4002 -d option on the host to analyze ISO files, instead of going
4003 through libguestfs.
4004 For information on the primary volume descriptor fields, see
4006 <https://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor>
4007 $g->journal_close ();
4009 Close the journal handle.
4010 This function depends on the feature "journal". See also
4012 "$g->feature-available".
4013 @fields = $g->journal_get ();
4015 Read the current journal entry. This returns all the fields in the
4016 journal as a set of "(attrname, attrval)" pairs. The "attrname" is
4017 the field name (a string).
4018 The "attrval" is the field value (a binary blob, often but not
4020 always a string). Please note that "attrval" is a byte array, not
4021 a \0-terminated C string.
4022 The length of data may be truncated to the data threshold (see:
4024 "$g->journal_set_data_threshold",
4025 "$g->journal_get_data_threshold").
4026 If you set the data threshold to unlimited (0) then this call can
4028 read a journal entry of any size, ie. it is not limited by the
4029 libguestfs protocol.
4030 This function depends on the feature "journal". See also
4032 "$g->feature-available".
4033 $threshold = $g->journal_get_data_threshold ();
4035 Get the current data threshold for reading journal entries. This
4036 is a hint to the journal that it may truncate data fields to this
4037 size when reading them (note also that it may not truncate them).
4038 If this returns 0, then the threshold is unlimited.
4039 See also "$g->journal_set_data_threshold".
4041 This function depends on the feature "journal". See also
4043 "$g->feature-available".
4044 $usec = $g->journal_get_realtime_usec ();
4046 Get the realtime (wallclock) timestamp of the current journal
4047 entry.
4048 This function depends on the feature "journal". See also
4050 "$g->feature-available".
4051 $more = $g->journal_next ();
4053 Move to the next journal entry. You have to call this at least
4054 once after opening the handle before you are able to read data.
4055 The returned boolean tells you if there are any more journal
4057 records to read. "true" means you can read the next record (eg.
4058 using "$g->journal_get"), and "false" means you have reached the
4059 end of the journal.
4060 This function depends on the feature "journal". See also
4062 "$g->feature-available".
4063 $g->journal_open ($directory);
4065 Open the systemd journal located in directory. Any previously
4066 opened journal handle is closed.
4067 The contents of the journal can be read using "$g->journal_next"
4069 and "$g->journal_get".
4070 After you have finished using the journal, you should close the
4072 handle by calling "$g->journal_close".
4073 This function depends on the feature "journal". See also
4075 "$g->feature-available".
4076 $g->journal_set_data_threshold ($threshold);
4078 Set the data threshold for reading journal entries. This is a hint
4079 to the journal that it may truncate data fields to this size when
4080 reading them (note also that it may not truncate them). If you set
4081 this to 0, then the threshold is unlimited.
4082 See also "$g->journal_get_data_threshold".
4084 This function depends on the feature "journal". See also
4086 "$g->feature-available".
4087 $rskip = $g->journal_skip ($skip);
4089 Skip forwards ("skip X 0") or backwards ("skip < 0") in the
4090 journal.
4091 The number of entries actually skipped is returned (note
4093 "rskip X 0"). If this is not the same as the absolute value of the
4094 skip parameter ("|skip|") you passed in then it means you have
4095 reached the end or the start of the journal.
4096 This function depends on the feature "journal". See also
4098 "$g->feature-available".
4099 $g->kill_subprocess ();
4101 This kills the hypervisor.
4102 Do not call this. See: "$g->shutdown" instead.
4104 This function is deprecated. In new code, use the "shutdown" call
4106 instead.
4107 Deprecated functions will not be removed from the API, but the fact
4109 that they are deprecated indicates that there are problems with
4110 correct use of these functions.
4111 $g->launch ();
4113 You should call this after configuring the handle (eg. adding
4114 drives) but before performing any actions.
4115 Do not call "$g->launch" twice on the same handle. Although it
4117 will not give an error (for historical reasons), the precise
4118 behaviour when you do this is not well defined. Handles are very
4119 cheap to create, so create a new one for each launch.
4120 $g->lchown ($owner, $group, $path);
4122 Change the file owner to "owner" and group to "group". This is
4123 like "$g->chown" but if "path" is a symlink then the link itself is
4124 changed, not the target.
4125 Only numeric uid and gid are supported. If you want to use names,
4127 you will need to locate and parse the password file yourself
4128 (Augeas support makes this relatively easy).
4129 $g->ldmtool_create_all ();
4131 This function scans all block devices looking for Windows dynamic
4132 disk volumes and partitions, and creates devices for any that were
4133 found.
4134 Call "$g->list_ldm_volumes" and "$g->list_ldm_partitions" to return
4136 all devices.
4137 Note that you don't normally need to call this explicitly, since it
4139 is done automatically at "$g->launch" time. However you might want
4140 to call this function if you have hotplugged disks or have just
4141 created a Windows dynamic disk.
4142 This function depends on the feature "ldm". See also
4144 "$g->feature-available".
4145 @disks = $g->ldmtool_diskgroup_disks ($diskgroup);
4147 Return the disks in a Windows dynamic disk group. The "diskgroup"
4148 parameter should be the GUID of a disk group, one element from the
4149 list returned by "$g->ldmtool_scan".
4150 This function depends on the feature "ldm". See also
4152 "$g->feature-available".
4153 $name = $g->ldmtool_diskgroup_name ($diskgroup);
4155 Return the name of a Windows dynamic disk group. The "diskgroup"
4156 parameter should be the GUID of a disk group, one element from the
4157 list returned by "$g->ldmtool_scan".
4158 This function depends on the feature "ldm". See also
4160 "$g->feature-available".
4161 @volumes = $g->ldmtool_diskgroup_volumes ($diskgroup);
4163 Return the volumes in a Windows dynamic disk group. The
4164 "diskgroup" parameter should be the GUID of a disk group, one
4165 element from the list returned by "$g->ldmtool_scan".
4166 This function depends on the feature "ldm". See also
4168 "$g->feature-available".
4169 $g->ldmtool_remove_all ();
4171 This is essentially the opposite of "$g->ldmtool_create_all". It
4172 removes the device mapper mappings for all Windows dynamic disk
4173 volumes
4174 This function depends on the feature "ldm". See also
4176 "$g->feature-available".
4177 @guids = $g->ldmtool_scan ();
4179 This function scans for Windows dynamic disks. It returns a list
4180 of identifiers (GUIDs) for all disk groups that were found. These
4181 identifiers can be passed to other "$g->ldmtool_*" functions.
4182 This function scans all block devices. To scan a subset of block
4184 devices, call "$g->ldmtool_scan_devices" instead.
4185 This function depends on the feature "ldm". See also
4187 "$g->feature-available".
4188 @guids = $g->ldmtool_scan_devices (\@devices);
4190 This function scans for Windows dynamic disks. It returns a list
4191 of identifiers (GUIDs) for all disk groups that were found. These
4192 identifiers can be passed to other "$g->ldmtool_*" functions.
4193 The parameter "devices" is a list of block devices which are
4195 scanned. If this list is empty, all block devices are scanned.
4196 This function depends on the feature "ldm". See also
4198 "$g->feature-available".
4199 $hint = $g->ldmtool_volume_hint ($diskgroup, $volume);
4201 Return the hint field of the volume named "volume" in the disk
4202 group with GUID "diskgroup". This may not be defined, in which
4203 case the empty string is returned. The hint field is often, though
4204 not always, the name of a Windows drive, eg. "E:".
4205 This function depends on the feature "ldm". See also
4207 "$g->feature-available".
4208 @partitions = $g->ldmtool_volume_partitions ($diskgroup, $volume);
4210 Return the list of partitions in the volume named "volume" in the
4211 disk group with GUID "diskgroup".
4212 This function depends on the feature "ldm". See also
4214 "$g->feature-available".
4215 $voltype = $g->ldmtool_volume_type ($diskgroup, $volume);
4217 Return the type of the volume named "volume" in the disk group with
4218 GUID "diskgroup".
4219 Possible volume types that can be returned here include: "simple",
4221 "spanned", "striped", "mirrored", "raid5". Other types may also be
4222 returned.
4223 This function depends on the feature "ldm". See also
4225 "$g->feature-available".
4226 $xattr = $g->lgetxattr ($path, $name);
4228 Get a single extended attribute from file "path" named "name". If
4229 "path" is a symlink, then this call returns an extended attribute
4230 from the symlink.
4231 Normally it is better to get all extended attributes from a file in
4233 one go by calling "$g->getxattrs". However some Linux filesystem
4234 implementations are buggy and do not provide a way to list out
4235 attributes. For these filesystems (notably ntfs-3g) you have to
4236 know the names of the extended attributes you want in advance and
4237 call this function.
4238 Extended attribute values are blobs of binary data. If there is no
4240 extended attribute named "name", this returns an error.
4241 See also: "$g->lgetxattrs", "$g->getxattr", attr(5).
4243 This function depends on the feature "linuxxattrs". See also
4245 "$g->feature-available".
4246 @xattrs = $g->lgetxattrs ($path);
4248 This is the same as "$g->getxattrs", but if "path" is a symbolic
4249 link, then it returns the extended attributes of the link itself.
4250 This function depends on the feature "linuxxattrs". See also
4252 "$g->feature-available".
4253 @mounttags = $g->list_9p ();
4255 List all 9p filesystems attached to the guest. A list of mount
4256 tags is returned.
4257 @devices = $g->list_devices ();
4259 List all the block devices.
4260 The full block device names are returned, eg. /dev/sda.
4262 See also "$g->list_filesystems".
4264 %labels = $g->list_disk_labels ();
4266 If you add drives using the optional "label" parameter of
4267 "$g->add_drive_opts", you can use this call to map between disk
4268 labels, and raw block device and partition names (like /dev/sda and
4269 /dev/sda1).
4270 This returns a hashtable, where keys are the disk labels (without
4272 the /dev/disk/guestfs prefix), and the values are the full raw
4273 block device and partition names (eg. /dev/sda and /dev/sda1).
4274 @devices = $g->list_dm_devices ();
4276 List all device mapper devices.
4277 The returned list contains /dev/mapper/* devices, eg. ones created
4279 by a previous call to "$g->luks_open".
4280 Device mapper devices which correspond to logical volumes are not
4282 returned in this list. Call "$g->lvs" if you want to list logical
4283 volumes.
4284 %fses = $g->list_filesystems ();
4286 This inspection command looks for filesystems on partitions, block
4287 devices and logical volumes, returning a list of "mountables"
4288 containing filesystems and their type.
4289 The return value is a hash, where the keys are the devices
4291 containing filesystems, and the values are the filesystem types.
4292 For example:
4293 "/dev/sda1" => "ntfs"
4295 "/dev/sda2" => "ext2"
4296 "/dev/vg_guest/lv_root" => "ext4"
4297 "/dev/vg_guest/lv_swap" => "swap"
4298 The key is not necessarily a block device. It may also be an opaque
4300 XmountableX string which can be passed to "$g->mount".
4301 The value can have the special value "unknown", meaning the content
4303 of the device is undetermined or empty. "swap" means a Linux swap
4304 partition.
4305 In libguestfs X 1.36 this command ran other libguestfs commands,
4307 which might have included "$g->mount" and "$g->umount", and
4308 therefore you had to use this soon after launch and only when
4309 nothing else was mounted. This restriction is removed in
4310 libguestfs X 1.38.
4311 Not all of the filesystems returned will be mountable. In
4313 particular, swap partitions are returned in the list. Also this
4314 command does not check that each filesystem found is valid and
4315 mountable, and some filesystems might be mountable but require
4316 special options. Filesystems may not all belong to a single
4317 logical operating system (use "$g->inspect_os" to look for OSes).
4318 @devices = $g->list_ldm_partitions ();
4320 This function returns all Windows dynamic disk partitions that were
4321 found at launch time. It returns a list of device names.
4322 This function depends on the feature "ldm". See also
4324 "$g->feature-available".
4325 @devices = $g->list_ldm_volumes ();
4327 This function returns all Windows dynamic disk volumes that were
4328 found at launch time. It returns a list of device names.
4329 This function depends on the feature "ldm". See also
4331 "$g->feature-available".
4332 @devices = $g->list_md_devices ();
4334 List all Linux md devices.
4335 @partitions = $g->list_partitions ();
4337 List all the partitions detected on all block devices.
4338 The full partition device names are returned, eg. /dev/sda1
4340 This does not return logical volumes. For that you will need to
4342 call "$g->lvs".
4343 See also "$g->list_filesystems".
4345 $listing = $g->ll ($directory);
4347 List the files in directory (relative to the root directory, there
4348 is no cwd) in the format of "ls -la".
4349 This command is mostly useful for interactive sessions. It is not
4351 intended that you try to parse the output string.
4352 $listing = $g->llz ($directory);
4354 List the files in directory in the format of "ls -laZ".
4355 This command is mostly useful for interactive sessions. It is not
4357 intended that you try to parse the output string.
4358 This function is deprecated. In new code, use the "lgetxattrs"
4360 call instead.
4361 Deprecated functions will not be removed from the API, but the fact
4363 that they are deprecated indicates that there are problems with
4364 correct use of these functions.
4365 $g->ln ($target, $linkname);
4367 This command creates a hard link.
4368 $g->ln_f ($target, $linkname);
4370 This command creates a hard link, removing the link "linkname" if
4371 it exists already.
4372 $g->ln_s ($target, $linkname);
4374 This command creates a symbolic link using the "ln -s" command.
4375 $g->ln_sf ($target, $linkname);
4377 This command creates a symbolic link using the "ln -sf" command,
4378 The -f option removes the link ("linkname") if it exists already.
4379 $g->lremovexattr ($xattr, $path);
4381 This is the same as "$g->removexattr", but if "path" is a symbolic
4382 link, then it removes an extended attribute of the link itself.
4383 This function depends on the feature "linuxxattrs". See also
4385 "$g->feature-available".
4386 @listing = $g->ls ($directory);
4388 List the files in directory (relative to the root directory, there
4389 is no cwd). The "." and ".." entries are not returned, but hidden
4390 files are shown.
4391 $g->ls0 ($dir, $filenames);
4393 This specialized command is used to get a listing of the filenames
4394 in the directory "dir". The list of filenames is written to the
4395 local file filenames (on the host).
4396 In the output file, the filenames are separated by "\0" characters.
4398 "." and ".." are not returned. The filenames are not sorted.
4400 $g->lsetxattr ($xattr, $val, $vallen, $path);
4402 This is the same as "$g->setxattr", but if "path" is a symbolic
4403 link, then it sets an extended attribute of the link itself.
4404 This function depends on the feature "linuxxattrs". See also
4406 "$g->feature-available".
4407 %statbuf = $g->lstat ($path);
4409 Returns file information for the given "path".
4410 This is the same as "$g->stat" except that if "path" is a symbolic
4412 link, then the link is stat-ed, not the file it refers to.
4413 This is the same as the lstat(2) system call.
4415 This function is deprecated. In new code, use the "lstatns" call
4417 instead.
4418 Deprecated functions will not be removed from the API, but the fact
4420 that they are deprecated indicates that there are problems with
4421 correct use of these functions.
4422 @statbufs = $g->lstatlist ($path, \@names);
4424 This call allows you to perform the "$g->lstat" operation on
4425 multiple files, where all files are in the directory "path".
4426 "names" is the list of files from this directory.
4427 On return you get a list of stat structs, with a one-to-one
4429 correspondence to the "names" list. If any name did not exist or
4430 could not be lstat'd, then the "st_ino" field of that structure is
4431 set to "-1".
4432 This call is intended for programs that want to efficiently list a
4434 directory contents without making many round-trips. See also
4435 "$g->lxattrlist" for a similarly efficient call for getting
4436 extended attributes.
4437 This function is deprecated. In new code, use the "lstatnslist"
4439 call instead.
4440 Deprecated functions will not be removed from the API, but the fact
4442 that they are deprecated indicates that there are problems with
4443 correct use of these functions.
4444 %statbuf = $g->lstatns ($path);
4446 Returns file information for the given "path".
4447 This is the same as "$g->statns" except that if "path" is a
4449 symbolic link, then the link is stat-ed, not the file it refers to.
4450 This is the same as the lstat(2) system call.
4452 @statbufs = $g->lstatnslist ($path, \@names);
4454 This call allows you to perform the "$g->lstatns" operation on
4455 multiple files, where all files are in the directory "path".
4456 "names" is the list of files from this directory.
4457 On return you get a list of stat structs, with a one-to-one
4459 correspondence to the "names" list. If any name did not exist or
4460 could not be lstat'd, then the "st_ino" field of that structure is
4461 set to "-1".
4462 This call is intended for programs that want to efficiently list a
4464 directory contents without making many round-trips. See also
4465 "$g->lxattrlist" for a similarly efficient call for getting
4466 extended attributes.
4467 $g->luks_add_key ($device, $key, $newkey, $keyslot);
4469 This command adds a new key on LUKS device "device". "key" is any
4470 existing key, and is used to access the device. "newkey" is the
4471 new key to add. "keyslot" is the key slot that will be replaced.
4472 Note that if "keyslot" already contains a key, then this command
4474 will fail. You have to use "$g->luks_kill_slot" first to remove
4475 that key.
4476 This function depends on the feature "luks". See also
4478 "$g->feature-available".
4479 $g->luks_close ($device);
4481 This closes a LUKS device that was created earlier by
4482 "$g->luks_open" or "$g->luks_open_ro". The "device" parameter must
4483 be the name of the LUKS mapping device (ie. /dev/mapper/mapname)
4484 and not the name of the underlying block device.
4485 This function depends on the feature "luks". See also
4487 "$g->feature-available".
4488 $g->luks_format ($device, $key, $keyslot);
4490 This command erases existing data on "device" and formats the
4491 device as a LUKS encrypted device. "key" is the initial key, which
4492 is added to key slot "keyslot". (LUKS supports 8 key slots,
4493 numbered 0-7).
4494 This function depends on the feature "luks". See also
4496 "$g->feature-available".
4497 $g->luks_format_cipher ($device, $key, $keyslot, $cipher);
4499 This command is the same as "$g->luks_format" but it also allows
4500 you to set the "cipher" used.
4501 This function depends on the feature "luks". See also
4503 "$g->feature-available".
4504 $g->luks_kill_slot ($device, $key, $keyslot);
4506 This command deletes the key in key slot "keyslot" from the
4507 encrypted LUKS device "device". "key" must be one of the other
4508 keys.
4509 This function depends on the feature "luks". See also
4511 "$g->feature-available".
4512 $g->luks_open ($device, $key, $mapname);
4514 This command opens a block device which has been encrypted
4515 according to the Linux Unified Key Setup (LUKS) standard.
4516 "device" is the encrypted block device or partition.
4518 The caller must supply one of the keys associated with the LUKS
4520 block device, in the "key" parameter.
4521 This creates a new block device called /dev/mapper/mapname. Reads
4523 and writes to this block device are decrypted from and encrypted to
4524 the underlying "device" respectively.
4525 If this block device contains LVM volume groups, then calling
4527 "$g->lvm_scan" with the "activate" parameter "true" will make them
4528 visible.
4529 Use "$g->list_dm_devices" to list all device mapper devices.
4531 This function depends on the feature "luks". See also
4533 "$g->feature-available".
4534 $g->luks_open_ro ($device, $key, $mapname);
4536 This is the same as "$g->luks_open" except that a read-only mapping
4537 is created.
4538 This function depends on the feature "luks". See also
4540 "$g->feature-available".
4541 $uuid = $g->luks_uuid ($device);
4543 This returns the UUID of the LUKS device "device".
4544 This function depends on the feature "luks". See also
4546 "$g->feature-available".
4547 $g->lvcreate ($logvol, $volgroup, $mbytes);
4549 This creates an LVM logical volume called "logvol" on the volume
4550 group "volgroup", with "size" megabytes.
4551 This function depends on the feature "lvm2". See also
4553 "$g->feature-available".
4554 $g->lvcreate_free ($logvol, $volgroup, $percent);
4556 Create an LVM logical volume called /dev/volgroup/logvol, using
4557 approximately "percent" % of the free space remaining in the volume
4558 group. Most usefully, when "percent" is 100 this will create the
4559 largest possible LV.
4560 This function depends on the feature "lvm2". See also
4562 "$g->feature-available".
4563 $lv = $g->lvm_canonical_lv_name ($lvname);
4565 This converts alternative naming schemes for LVs that you might
4566 find to the canonical name. For example, /dev/mapper/VG-LV is
4567 converted to /dev/VG/LV.
4568 This command returns an error if the "lvname" parameter does not
4570 refer to a logical volume.
4571 See also "$g->is_lv", "$g->canonical_device_name".
4573 $g->lvm_clear_filter ();
4575 This undoes the effect of "$g->lvm_set_filter". LVM will be able
4576 to see every block device.
4577 This command also clears the LVM cache and performs a volume group
4579 scan.
4580 $g->lvm_remove_all ();
4582 This command removes all LVM logical volumes, volume groups and
4583 physical volumes.
4584 This function depends on the feature "lvm2". See also
4586 "$g->feature-available".
4587 $g->lvm_scan ($activate);
4589 This scans all block devices and rebuilds the list of LVM physical
4590 volumes, volume groups and logical volumes.
4591 If the "activate" parameter is "true" then newly found volume
4593 groups and logical volumes are activated, meaning the LV /dev/VG/LV
4594 devices become visible.
4595 When a libguestfs handle is launched it scans for existing devices,
4597 so you do not normally need to use this API. However it is useful
4598 when you have added a new device or deleted an existing device
4599 (such as when the "$g->luks_open" API is used).
4600 $g->lvm_set_filter (\@devices);
4602 This sets the LVM device filter so that LVM will only be able to
4603 "see" the block devices in the list "devices", and will ignore all
4604 other attached block devices.
4605 Where disk image(s) contain duplicate PVs or VGs, this command is
4607 useful to get LVM to ignore the duplicates, otherwise LVM can get
4608 confused. Note also there are two types of duplication possible:
4609 either cloned PVs/VGs which have identical UUIDs; or VGs that are
4610 not cloned but just happen to have the same name. In normal
4611 operation you cannot create this situation, but you can do it
4612 outside LVM, eg. by cloning disk images or by bit twiddling inside
4613 the LVM metadata.
4614 This command also clears the LVM cache and performs a volume group
4616 scan.
4617 You can filter whole block devices or individual partitions.
4619 You cannot use this if any VG is currently in use (eg. contains a
4621 mounted filesystem), even if you are not filtering out that VG.
4622 This function depends on the feature "lvm2". See also
4624 "$g->feature-available".
4625 $g->lvremove ($device);
4627 Remove an LVM logical volume "device", where "device" is the path
4628 to the LV, such as /dev/VG/LV.
4629 You can also remove all LVs in a volume group by specifying the VG
4631 name, /dev/VG.
4632 This function depends on the feature "lvm2". See also
4634 "$g->feature-available".
4635 $g->lvrename ($logvol, $newlogvol);
4637 Rename a logical volume "logvol" with the new name "newlogvol".
4638 $g->lvresize ($device, $mbytes);
4640 This resizes (expands or shrinks) an existing LVM logical volume to
4641 "mbytes". When reducing, data in the reduced part is lost.
4642 This function depends on the feature "lvm2". See also
4644 "$g->feature-available".
4645 $g->lvresize_free ($lv, $percent);
4647 This expands an existing logical volume "lv" so that it fills "pc"
4648 % of the remaining free space in the volume group. Commonly you
4649 would call this with pc = 100 which expands the logical volume as
4650 much as possible, using all remaining free space in the volume
4651 group.
4652 This function depends on the feature "lvm2". See also
4654 "$g->feature-available".
4655 @logvols = $g->lvs ();
4657 List all the logical volumes detected. This is the equivalent of
4658 the lvs(8) command.
4659 This returns a list of the logical volume device names (eg.
4661 /dev/VolGroup00/LogVol00).
4662 See also "$g->lvs_full", "$g->list_filesystems".
4664 This function depends on the feature "lvm2". See also
4666 "$g->feature-available".
4667 @logvols = $g->lvs_full ();
4669 List all the logical volumes detected. This is the equivalent of
4670 the lvs(8) command. The "full" version includes all fields.
4671 This function depends on the feature "lvm2". See also
4673 "$g->feature-available".
4674 $uuid = $g->lvuuid ($device);
4676 This command returns the UUID of the LVM LV "device".
4677 @xattrs = $g->lxattrlist ($path, \@names);
4679 This call allows you to get the extended attributes of multiple
4680 files, where all files are in the directory "path". "names" is the
4681 list of files from this directory.
4682 On return you get a flat list of xattr structs which must be
4684 interpreted sequentially. The first xattr struct always has a
4685 zero-length "attrname". "attrval" in this struct is zero-length to
4686 indicate there was an error doing "$g->lgetxattr" for this file, or
4687 is a C string which is a decimal number (the number of following
4688 attributes for this file, which could be "0"). Then after the
4689 first xattr struct are the zero or more attributes for the first
4690 named file. This repeats for the second and subsequent files.
4691 This call is intended for programs that want to efficiently list a
4693 directory contents without making many round-trips. See also
4694 "$g->lstatlist" for a similarly efficient call for getting standard
4695 stats.
4696 This function depends on the feature "linuxxattrs". See also
4698 "$g->feature-available".
4699 $disks = $g->max_disks ();
4701 Return the maximum number of disks that may be added to a handle
4702 (eg. by "$g->add_drive_opts" and similar calls).
4703 This function was added in libguestfs 1.19.7. In previous versions
4705 of libguestfs the limit was 25.
4706 See "MAXIMUM NUMBER OF DISKS" in guestfs(3) for additional
4708 information on this topic.
4709 $g->md_create ($name, \@devices [, missingbitmap => $missingbitmap] [,
4711 nrdevices => $nrdevices] [, spare => $spare] [, chunk => $chunk] [,
4712 level => $level]);
4713 Create a Linux md (RAID) device named "name" on the devices in the
4714 list "devices".
4715 The optional parameters are:
4717 "missingbitmap"
4719 A bitmap of missing devices. If a bit is set it means that a
4720 missing device is added to the array. The least significant
4721 bit corresponds to the first device in the array.
4722 As examples:
4724 If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
4726 resulting array would be "[<missing>, "/dev/sda"]".
4727 If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
4729 resulting array would be "["/dev/sda", <missing>]".
4730 This defaults to 0 (no missing devices).
4732 The length of "devices" + the number of bits set in
4734 "missingbitmap" must equal "nrdevices" + "spare".
4735 "nrdevices"
4737 The number of active RAID devices.
4738 If not set, this defaults to the length of "devices" plus the
4740 number of bits set in "missingbitmap".
4741 "spare"
4743 The number of spare devices.
4744 If not set, this defaults to 0.
4746 "chunk"
4748 The chunk size in bytes.
4749 "level"
4751 The RAID level, which can be one of: "linear", "raid0", 0,
4752 "stripe", "raid1", 1, "mirror", "raid4", 4, "raid5", 5,
4753 "raid6", 6, "raid10", 10. Some of these are synonymous, and
4754 more levels may be added in future.
4755 If not set, this defaults to "raid1".
4757 This function depends on the feature "mdadm". See also
4759 "$g->feature-available".
4760 %info = $g->md_detail ($md);
4762 This command exposes the output of "mdadm -DY <md>". The following
4763 fields are usually present in the returned hash. Other fields may
4764 also be present.
4765 "level"
4767 The raid level of the MD device.
4768 "devices"
4770 The number of underlying devices in the MD device.
4771 "metadata"
4773 The metadata version used.
4774 "uuid"
4776 The UUID of the MD device.
4777 "name"
4779 The name of the MD device.
4780 This function depends on the feature "mdadm". See also
4782 "$g->feature-available".
4783 @devices = $g->md_stat ($md);
4785 This call returns a list of the underlying devices which make up
4786 the single software RAID array device "md".
4787 To get a list of software RAID devices, call "$g->list_md_devices".
4789 Each structure returned corresponds to one device along with
4791 additional status information:
4792 "mdstat_device"
4794 The name of the underlying device.
4795 "mdstat_index"
4797 The index of this device within the array.
4798 "mdstat_flags"
4800 Flags associated with this device. This is a string containing
4801 (in no specific order) zero or more of the following flags:
4802 "W" write-mostly
4804 "F" device is faulty
4806 "S" device is a RAID spare
4808 "R" replacement
4810 This function depends on the feature "mdadm". See also
4812 "$g->feature-available".
4813 $g->md_stop ($md);
4815 This command deactivates the MD array named "md". The device is
4816 stopped, but it is not destroyed or zeroed.
4817 This function depends on the feature "mdadm". See also
4819 "$g->feature-available".
4820 $g->mkdir ($path);
4822 Create a directory named "path".
4823 $g->mkdir_mode ($path, $mode);
4825 This command creates a directory, setting the initial permissions
4826 of the directory to "mode".
4827 For common Linux filesystems, the actual mode which is set will be
4829 "mode & ~umask & 01777". Non-native-Linux filesystems may
4830 interpret the mode in other ways.
4831 See also "$g->mkdir", "$g->umask"
4833 $g->mkdir_p ($path);
4835 Create a directory named "path", creating any parent directories as
4836 necessary. This is like the "mkdir -p" shell command.
4837 $dir = $g->mkdtemp ($tmpl);
4839 This command creates a temporary directory. The "tmpl" parameter
4840 should be a full pathname for the temporary directory name with the
4841 final six characters being "XXXXXX".
4842 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the
4844 second one being suitable for Windows filesystems.
4845 The name of the temporary directory that was created is returned.
4847 The temporary directory is created with mode 0700 and is owned by
4849 root.
4850 The caller is responsible for deleting the temporary directory and
4852 its contents after use.
4853 See also: mkdtemp(3)
4855 $g->mke2fs ($device [, blockscount => $blockscount] [, blocksize =>
4857 $blocksize] [, fragsize => $fragsize] [, blockspergroup =>
4858 $blockspergroup] [, numberofgroups => $numberofgroups] [, bytesperinode
4859 => $bytesperinode] [, inodesize => $inodesize] [, journalsize =>
4860 $journalsize] [, numberofinodes => $numberofinodes] [, stridesize =>
4861 $stridesize] [, stripewidth => $stripewidth] [, maxonlineresize =>
4862 $maxonlineresize] [, reservedblockspercentage =>
4863 $reservedblockspercentage] [, mmpupdateinterval => $mmpupdateinterval]
4864 [, journaldevice => $journaldevice] [, label => $label] [,
4865 lastmounteddir => $lastmounteddir] [, creatoros => $creatoros] [,
4866 fstype => $fstype] [, usagetype => $usagetype] [, uuid => $uuid] [,
4867 forcecreate => $forcecreate] [, writesbandgrouponly =>
4868 $writesbandgrouponly] [, lazyitableinit => $lazyitableinit] [,
4869 lazyjournalinit => $lazyjournalinit] [, testfs => $testfs] [, discard
4870 => $discard] [, quotatype => $quotatype] [, extent => $extent] [,
4871 filetype => $filetype] [, flexbg => $flexbg] [, hasjournal =>
4872 $hasjournal] [, journaldev => $journaldev] [, largefile => $largefile]
4873 [, quota => $quota] [, resizeinode => $resizeinode] [, sparsesuper =>
4874 $sparsesuper] [, uninitbg => $uninitbg]);
4875 "mke2fs" is used to create an ext2, ext3, or ext4 filesystem on
4876 "device".
4877 The optional "blockscount" is the size of the filesystem in blocks.
4879 If omitted it defaults to the size of "device". Note if the
4880 filesystem is too small to contain a journal, "mke2fs" will
4881 silently create an ext2 filesystem instead.
4882 $g->mke2fs_J ($fstype, $blocksize, $device, $journal);
4884 This creates an ext2/3/4 filesystem on "device" with an external
4885 journal on "journal". It is equivalent to the command:
4886 mke2fs -t fstype -b blocksize -J device=<journal> <device>
4888 See also "$g->mke2journal".
4890 This function is deprecated. In new code, use the "mke2fs" call
4892 instead.
4893 Deprecated functions will not be removed from the API, but the fact
4895 that they are deprecated indicates that there are problems with
4896 correct use of these functions.
4897 $g->mke2fs_JL ($fstype, $blocksize, $device, $label);
4899 This creates an ext2/3/4 filesystem on "device" with an external
4900 journal on the journal labeled "label".
4901 See also "$g->mke2journal_L".
4903 This function is deprecated. In new code, use the "mke2fs" call
4905 instead.
4906 Deprecated functions will not be removed from the API, but the fact
4908 that they are deprecated indicates that there are problems with
4909 correct use of these functions.
4910 $g->mke2fs_JU ($fstype, $blocksize, $device, $uuid);
4912 This creates an ext2/3/4 filesystem on "device" with an external
4913 journal on the journal with UUID "uuid".
4914 See also "$g->mke2journal_U".
4916 This function depends on the feature "linuxfsuuid". See also
4918 "$g->feature-available".
4919 This function is deprecated. In new code, use the "mke2fs" call
4921 instead.
4922 Deprecated functions will not be removed from the API, but the fact
4924 that they are deprecated indicates that there are problems with
4925 correct use of these functions.
4926 $g->mke2journal ($blocksize, $device);
4928 This creates an ext2 external journal on "device". It is
4929 equivalent to the command:
4930 mke2fs -O journal_dev -b blocksize device
4932 This function is deprecated. In new code, use the "mke2fs" call
4934 instead.
4935 Deprecated functions will not be removed from the API, but the fact
4937 that they are deprecated indicates that there are problems with
4938 correct use of these functions.
4939 $g->mke2journal_L ($blocksize, $label, $device);
4941 This creates an ext2 external journal on "device" with label
4942 "label".
4943 This function is deprecated. In new code, use the "mke2fs" call
4945 instead.
4946 Deprecated functions will not be removed from the API, but the fact
4948 that they are deprecated indicates that there are problems with
4949 correct use of these functions.
4950 $g->mke2journal_U ($blocksize, $uuid, $device);
4952 This creates an ext2 external journal on "device" with UUID "uuid".
4953 This function depends on the feature "linuxfsuuid". See also
4955 "$g->feature-available".
4956 This function is deprecated. In new code, use the "mke2fs" call
4958 instead.
4959 Deprecated functions will not be removed from the API, but the fact
4961 that they are deprecated indicates that there are problems with
4962 correct use of these functions.
4963 $g->mkfifo ($mode, $path);
4965 This call creates a FIFO (named pipe) called "path" with mode
4966 "mode". It is just a convenient wrapper around "$g->mknod".
4967 Unlike with "$g->mknod", "mode" must contain only permissions bits.
4969 The mode actually set is affected by the umask.
4971 This function depends on the feature "mknod". See also
4973 "$g->feature-available".
4974 $g->mkfs ($fstype, $device [, blocksize => $blocksize] [, features =>
4976 $features] [, inode => $inode] [, sectorsize => $sectorsize] [, label
4977 => $label]);
4978 This function creates a filesystem on "device". The filesystem
4979 type is "fstype", for example "ext3".
4980 The optional arguments are:
4982 "blocksize"
4984 The filesystem block size. Supported block sizes depend on the
4985 filesystem type, but typically they are 1024, 2048 or 4096 for
4986 Linux ext2/3 filesystems.
4987 For VFAT and NTFS the "blocksize" parameter is treated as the
4989 requested cluster size.
4990 For UFS block sizes, please see mkfs.ufs(8).
4992 "features"
4994 This passes the -O parameter to the external mkfs program.
4995 For certain filesystem types, this allows extra filesystem
4997 features to be selected. See mke2fs(8) and mkfs.ufs(8) for
4998 more details.
4999 You cannot use this optional parameter with the "gfs" or "gfs2"
5001 filesystem type.
5002 "inode"
5004 This passes the -I parameter to the external mke2fs(8) program
5005 which sets the inode size (only for ext2/3/4 filesystems at
5006 present).
5007 "sectorsize"
5009 This passes the -S parameter to external mkfs.ufs(8) program,
5010 which sets sector size for ufs filesystem.
5011 $g->mkfs_opts ($fstype, $device [, blocksize => $blocksize] [, features
5013 => $features] [, inode => $inode] [, sectorsize => $sectorsize] [,
5014 label => $label]);
5015 This is an alias of "mkfs".
5016 $g->mkfs_b ($fstype, $blocksize, $device);
5018 This call is similar to "$g->mkfs", but it allows you to control
5019 the block size of the resulting filesystem. Supported block sizes
5020 depend on the filesystem type, but typically they are 1024, 2048 or
5021 4096 only.
5022 For VFAT and NTFS the "blocksize" parameter is treated as the
5024 requested cluster size.
5025 This function is deprecated. In new code, use the "mkfs" call
5027 instead.
5028 Deprecated functions will not be removed from the API, but the fact
5030 that they are deprecated indicates that there are problems with
5031 correct use of these functions.
5032 $g->mkfs_btrfs (\@devices [, allocstart => $allocstart] [, bytecount =>
5034 $bytecount] [, datatype => $datatype] [, leafsize => $leafsize] [,
5035 label => $label] [, metadata => $metadata] [, nodesize => $nodesize] [,
5036 sectorsize => $sectorsize]);
5037 Create a btrfs filesystem, allowing all configurables to be set.
5038 For more information on the optional arguments, see mkfs.btrfs(8).
5039 Since btrfs filesystems can span multiple devices, this takes a
5041 non-empty list of devices.
5042 To create general filesystems, use "$g->mkfs".
5044 This function depends on the feature "btrfs". See also
5046 "$g->feature-available".
5047 $g->mklost_and_found ($mountpoint);
5049 Make the "lost+found" directory, normally in the root directory of
5050 an ext2/3/4 filesystem. "mountpoint" is the directory under which
5051 we try to create the "lost+found" directory.
5052 $g->mkmountpoint ($exemptpath);
5054 "$g->mkmountpoint" and "$g->rmmountpoint" are specialized calls
5055 that can be used to create extra mountpoints before mounting the
5056 first filesystem.
5057 These calls are only necessary in some very limited circumstances,
5059 mainly the case where you want to mount a mix of unrelated and/or
5060 read-only filesystems together.
5061 For example, live CDs often contain a "Russian doll" nest of
5063 filesystems, an ISO outer layer, with a squashfs image inside, with
5064 an ext2/3 image inside that. You can unpack this as follows in
5065 guestfish:
5066 add-ro Fedora-11-i686-Live.iso
5068 run
5069 mkmountpoint /cd
5070 mkmountpoint /sqsh
5071 mkmountpoint /ext3fs
5072 mount /dev/sda /cd
5073 mount-loop /cd/LiveOS/squashfs.img /sqsh
5074 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
5075 The inner filesystem is now unpacked under the /ext3fs mountpoint.
5077 "$g->mkmountpoint" is not compatible with "$g->umount_all". You
5079 may get unexpected errors if you try to mix these calls. It is
5080 safest to manually unmount filesystems and remove mountpoints after
5081 use.
5082 "$g->umount_all" unmounts filesystems by sorting the paths longest
5084 first, so for this to work for manual mountpoints, you must ensure
5085 that the innermost mountpoints have the longest pathnames, as in
5086 the example code above.
5087 For more details see
5089 <https://bugzilla.redhat.com/show_bug.cgi?id=599503>
5090 Autosync [see "$g->set_autosync", this is set by default on
5092 handles] can cause "$g->umount_all" to be called when the handle is
5093 closed which can also trigger these issues.
5094 $g->mknod ($mode, $devmajor, $devminor, $path);
5096 This call creates block or character special devices, or named
5097 pipes (FIFOs).
5098 The "mode" parameter should be the mode, using the standard
5100 constants. "devmajor" and "devminor" are the device major and
5101 minor numbers, only used when creating block and character special
5102 devices.
5103 Note that, just like mknod(2), the mode must be bitwise OR'd with
5105 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just
5106 creates a regular file). These constants are available in the
5107 standard Linux header files, or you can use "$g->mknod_b",
5108 "$g->mknod_c" or "$g->mkfifo" which are wrappers around this
5109 command which bitwise OR in the appropriate constant for you.
5110 The mode actually set is affected by the umask.
5112 This function depends on the feature "mknod". See also
5114 "$g->feature-available".
5115 $g->mknod_b ($mode, $devmajor, $devminor, $path);
5117 This call creates a block device node called "path" with mode
5118 "mode" and device major/minor "devmajor" and "devminor". It is
5119 just a convenient wrapper around "$g->mknod".
5120 Unlike with "$g->mknod", "mode" must contain only permissions bits.
5122 The mode actually set is affected by the umask.
5124 This function depends on the feature "mknod". See also
5126 "$g->feature-available".
5127 $g->mknod_c ($mode, $devmajor, $devminor, $path);
5129 This call creates a char device node called "path" with mode "mode"
5130 and device major/minor "devmajor" and "devminor". It is just a
5131 convenient wrapper around "$g->mknod".
5132 Unlike with "$g->mknod", "mode" must contain only permissions bits.
5134 The mode actually set is affected by the umask.
5136 This function depends on the feature "mknod". See also
5138 "$g->feature-available".
5139 $g->mksquashfs ($path, $filename [, compress => $compress] [, excludes
5141 => $excludes]);
5142 Create a squashfs filesystem for the specified "path".
5143 The optional "compress" flag controls compression. If not given,
5145 then the output compressed using "gzip". Otherwise one of the
5146 following strings may be given to select the compression type of
5147 the squashfs: "gzip", "lzma", "lzo", "lz4", "xz".
5148 The other optional arguments are:
5150 "excludes"
5152 A list of wildcards. Files are excluded if they match any of
5153 the wildcards.
5154 Please note that this API may fail when used to compress
5156 directories with large files, such as the resulting squashfs will
5157 be over 3GB big.
5158 This function depends on the feature "squashfs". See also
5160 "$g->feature-available".
5161 $g->mkswap ($device [, label => $label] [, uuid => $uuid]);
5163 Create a Linux swap partition on "device".
5164 The option arguments "label" and "uuid" allow you to set the label
5166 and/or UUID of the new swap partition.
5167 $g->mkswap_opts ($device [, label => $label] [, uuid => $uuid]);
5169 This is an alias of "mkswap".
5170 $g->mkswap_L ($label, $device);
5172 Create a swap partition on "device" with label "label".
5173 Note that you cannot attach a swap label to a block device (eg.
5175 /dev/sda), just to a partition. This appears to be a limitation of
5176 the kernel or swap tools.
5177 This function is deprecated. In new code, use the "mkswap" call
5179 instead.
5180 Deprecated functions will not be removed from the API, but the fact
5182 that they are deprecated indicates that there are problems with
5183 correct use of these functions.
5184 $g->mkswap_U ($uuid, $device);
5186 Create a swap partition on "device" with UUID "uuid".
5187 This function depends on the feature "linuxfsuuid". See also
5189 "$g->feature-available".
5190 This function is deprecated. In new code, use the "mkswap" call
5192 instead.
5193 Deprecated functions will not be removed from the API, but the fact
5195 that they are deprecated indicates that there are problems with
5196 correct use of these functions.
5197 $g->mkswap_file ($path);
5199 Create a swap file.
5200 This command just writes a swap file signature to an existing file.
5202 To create the file itself, use something like "$g->fallocate".
5203 $path = $g->mktemp ($tmpl [, suffix => $suffix]);
5205 This command creates a temporary file. The "tmpl" parameter should
5206 be a full pathname for the temporary directory name with the final
5207 six characters being "XXXXXX".
5208 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the
5210 second one being suitable for Windows filesystems.
5211 The name of the temporary file that was created is returned.
5213 The temporary file is created with mode 0600 and is owned by root.
5215 The caller is responsible for deleting the temporary file after
5217 use.
5218 If the optional "suffix" parameter is given, then the suffix (eg.
5220 ".txt") is appended to the temporary name.
5221 See also: "$g->mkdtemp".
5223 $g->modprobe ($modulename);
5225 This loads a kernel module in the appliance.
5226 This function depends on the feature "linuxmodules". See also
5228 "$g->feature-available".
5229 $g->mount ($mountable, $mountpoint);
5231 Mount a guest disk at a position in the filesystem. Block devices
5232 are named /dev/sda, /dev/sdb and so on, as they were added to the
5233 guest. If those block devices contain partitions, they will have
5234 the usual names (eg. /dev/sda1). Also LVM /dev/VG/LV-style names
5235 can be used, or XmountableX strings returned by
5236 "$g->list_filesystems" or "$g->inspect_get_mountpoints".
5237 The rules are the same as for mount(2): A filesystem must first be
5239 mounted on / before others can be mounted. Other filesystems can
5240 only be mounted on directories which already exist.
5241 The mounted filesystem is writable, if we have sufficient
5243 permissions on the underlying device.
5244 Before libguestfs 1.13.16, this call implicitly added the options
5246 "sync" and "noatime". The "sync" option greatly slowed writes and
5247 caused many problems for users. If your program might need to work
5248 with older versions of libguestfs, use "$g->mount_options" instead
5249 (using an empty string for the first parameter if you don't want
5250 any options).
5251 $g->mount_9p ($mounttag, $mountpoint [, options => $options]);
5253 Mount the virtio-9p filesystem with the tag "mounttag" on the
5254 directory "mountpoint".
5255 If required, "trans=virtio" will be automatically added to the
5257 options. Any other options required can be passed in the optional
5258 "options" parameter.
5259 $g->mount_local ($localmountpoint [, readonly => $readonly] [, options
5261 => $options] [, cachetimeout => $cachetimeout] [, debugcalls =>
5262 $debugcalls]);
5263 This call exports the libguestfs-accessible filesystem to a local
5264 mountpoint (directory) called "localmountpoint". Ordinary reads
5265 and writes to files and directories under "localmountpoint" are
5266 redirected through libguestfs.
5267 If the optional "readonly" flag is set to true, then writes to the
5269 filesystem return error "EROFS".
5270 "options" is a comma-separated list of mount options. See
5272 guestmount(1) for some useful options.
5273 "cachetimeout" sets the timeout (in seconds) for cached directory
5275 entries. The default is 60 seconds. See guestmount(1) for further
5276 information.
5277 If "debugcalls" is set to true, then additional debugging
5279 information is generated for every FUSE call.
5280 When "$g->mount_local" returns, the filesystem is ready, but is not
5282 processing requests (access to it will block). You have to call
5283 "$g->mount_local_run" to run the main loop.
5284 See "MOUNT LOCAL" in guestfs(3) for full documentation.
5286 $g->mount_local_run ();
5288 Run the main loop which translates kernel calls to libguestfs
5289 calls.
5290 This should only be called after "$g->mount_local" returns
5292 successfully. The call will not return until the filesystem is
5293 unmounted.
5294 Note you must not make concurrent libguestfs calls on the same
5296 handle from another thread.
5297 You may call this from a different thread than the one which called
5299 "$g->mount_local", subject to the usual rules for threads and
5300 libguestfs (see "MULTIPLE HANDLES AND MULTIPLE THREADS" in
5301 guestfs(3)).
5302 See "MOUNT LOCAL" in guestfs(3) for full documentation.
5304 $g->mount_loop ($file, $mountpoint);
5306 This command lets you mount file (a filesystem image in a file) on
5307 a mount point. It is entirely equivalent to the command "mount -o
5308 loop file mountpoint".
5309 $g->mount_options ($options, $mountable, $mountpoint);
5311 This is the same as the "$g->mount" command, but it allows you to
5312 set the mount options as for the mount(8) -o flag.
5313 If the "options" parameter is an empty string, then no options are
5315 passed (all options default to whatever the filesystem uses).
5316 $g->mount_ro ($mountable, $mountpoint);
5318 This is the same as the "$g->mount" command, but it mounts the
5319 filesystem with the read-only (-o ro) flag.
5320 $g->mount_vfs ($options, $vfstype, $mountable, $mountpoint);
5322 This is the same as the "$g->mount" command, but it allows you to
5323 set both the mount options and the vfstype as for the mount(8) -o
5324 and -t flags.
5325 $device = $g->mountable_device ($mountable);
5327 Returns the device name of a mountable. In quite a lot of cases,
5328 the mountable is the device name.
5329 However this doesn't apply for btrfs subvolumes, where the
5331 mountable is a combination of both the device name and the
5332 subvolume path (see also "$g->mountable_subvolume" to extract the
5333 subvolume path of the mountable if any).
5334 $subvolume = $g->mountable_subvolume ($mountable);
5336 Returns the subvolume path of a mountable. Btrfs subvolumes
5337 mountables are a combination of both the device name and the
5338 subvolume path (see also "$g->mountable_device" to extract the
5339 device of the mountable).
5340 If the mountable does not represent a btrfs subvolume, then this
5342 function fails and the "errno" is set to "EINVAL".
5343 %mps = $g->mountpoints ();
5345 This call is similar to "$g->mounts". That call returns a list of
5346 devices. This one returns a hash table (map) of device name to
5347 directory where the device is mounted.
5348 @devices = $g->mounts ();
5350 This returns the list of currently mounted filesystems. It returns
5351 the list of devices (eg. /dev/sda1, /dev/VG/LV).
5352 Some internal mounts are not shown.
5354 See also: "$g->mountpoints"
5356 $g->mv ($src, $dest);
5358 This moves a file from "src" to "dest" where "dest" is either a
5359 destination filename or destination directory.
5360 See also: "$g->rename".
5362 $nrdisks = $g->nr_devices ();
5364 This returns the number of whole block devices that were added.
5365 This is the same as the number of devices that would be returned if
5366 you called "$g->list_devices".
5367 To find out the maximum number of devices that could be added, call
5369 "$g->max_disks".
5370 $status = $g->ntfs_3g_probe ($rw, $device);
5372 This command runs the ntfs-3g.probe(8) command which probes an NTFS
5373 "device" for mountability. (Not all NTFS volumes can be mounted
5374 read-write, and some cannot be mounted at all).
5375 "rw" is a boolean flag. Set it to true if you want to test if the
5377 volume can be mounted read-write. Set it to false if you want to
5378 test if the volume can be mounted read-only.
5379 The return value is an integer which 0 if the operation would
5381 succeed, or some non-zero value documented in the ntfs-3g.probe(8)
5382 manual page.
5383 This function depends on the feature "ntfs3g". See also
5385 "$g->feature-available".
5386 $g->ntfscat_i ($device, $inode, $filename);
5388 Download a file given its inode from a NTFS filesystem and save it
5389 as filename on the local machine.
5390 This allows to download some otherwise inaccessible files such as
5392 the ones within the $Extend folder.
5393 The filesystem from which to extract the file must be unmounted,
5395 otherwise the call will fail.
5396 $g->ntfsclone_in ($backupfile, $device);
5398 Restore the "backupfile" (from a previous call to
5399 "$g->ntfsclone_out") to "device", overwriting any existing contents
5400 of this device.
5401 This function depends on the feature "ntfs3g". See also
5403 "$g->feature-available".
5404 $g->ntfsclone_out ($device, $backupfile [, metadataonly =>
5406 $metadataonly] [, rescue => $rescue] [, ignorefscheck =>
5407 $ignorefscheck] [, preservetimestamps => $preservetimestamps] [, force
5408 => $force]);
5409 Stream the NTFS filesystem "device" to the local file "backupfile".
5410 The format used for the backup file is a special format used by the
5411 ntfsclone(8) tool.
5412 If the optional "metadataonly" flag is true, then only the metadata
5414 is saved, losing all the user data (this is useful for diagnosing
5415 some filesystem problems).
5416 The optional "rescue", "ignorefscheck", "preservetimestamps" and
5418 "force" flags have precise meanings detailed in the ntfsclone(8)
5419 man page.
5420 Use "$g->ntfsclone_in" to restore the file back to a libguestfs
5422 device.
5423 This function depends on the feature "ntfs3g". See also
5425 "$g->feature-available".
5426 $g->ntfsfix ($device [, clearbadsectors => $clearbadsectors]);
5428 This command repairs some fundamental NTFS inconsistencies, resets
5429 the NTFS journal file, and schedules an NTFS consistency check for
5430 the first boot into Windows.
5431 This is not an equivalent of Windows "chkdsk". It does not scan
5433 the filesystem for inconsistencies.
5434 The optional "clearbadsectors" flag clears the list of bad sectors.
5436 This is useful after cloning a disk with bad sectors to a new disk.
5437 This function depends on the feature "ntfs3g". See also
5439 "$g->feature-available".
5440 $g->ntfsresize ($device [, size => $size] [, force => $force]);
5442 This command resizes an NTFS filesystem, expanding or shrinking it
5443 to the size of the underlying device.
5444 The optional parameters are:
5446 "size"
5448 The new size (in bytes) of the filesystem. If omitted, the
5449 filesystem is resized to fit the container (eg. partition).
5450 "force"
5452 If this option is true, then force the resize of the filesystem
5453 even if the filesystem is marked as requiring a consistency
5454 check.
5455 After the resize operation, the filesystem is always marked as
5457 requiring a consistency check (for safety). You have to boot
5458 into Windows to perform this check and clear this condition.
5459 If you don't set the "force" option then it is not possible to
5460 call "$g->ntfsresize" multiple times on a single filesystem
5461 without booting into Windows between each resize.
5462 See also ntfsresize(8).
5464 This function depends on the feature "ntfsprogs". See also
5466 "$g->feature-available".
5467 $g->ntfsresize_opts ($device [, size => $size] [, force => $force]);
5469 This is an alias of "ntfsresize".
5470 $g->ntfsresize_size ($device, $size);
5472 This command is the same as "$g->ntfsresize" except that it allows
5473 you to specify the new size (in bytes) explicitly.
5474 This function depends on the feature "ntfsprogs". See also
5476 "$g->feature-available".
5477 This function is deprecated. In new code, use the "ntfsresize"
5479 call instead.
5480 Deprecated functions will not be removed from the API, but the fact
5482 that they are deprecated indicates that there are problems with
5483 correct use of these functions.
5484 $g->parse_environment ();
5486 Parse the programXs environment and set flags in the handle
5487 accordingly. For example if "LIBGUESTFS_DEBUG=1" then the
5488 XverboseX flag is set in the handle.
5489 Most programs do not need to call this. It is done implicitly when
5491 you call "$g->create".
5492 See "ENVIRONMENT VARIABLES" in guestfs(3) for a list of environment
5494 variables that can affect libguestfs handles. See also
5495 "guestfs_create_flags" in guestfs(3), and
5496 "$g->parse_environment_list".
5497 $g->parse_environment_list (\@environment);
5499 Parse the list of strings in the argument "environment" and set
5500 flags in the handle accordingly. For example if
5501 "LIBGUESTFS_DEBUG=1" is a string in the list, then the XverboseX
5502 flag is set in the handle.
5503 This is the same as "$g->parse_environment" except that it parses
5505 an explicit list of strings instead of the program's environment.
5506 $g->part_add ($device, $prlogex, $startsect, $endsect);
5508 This command adds a partition to "device". If there is no
5509 partition table on the device, call "$g->part_init" first.
5510 The "prlogex" parameter is the type of partition. Normally you
5512 should pass "p" or "primary" here, but MBR partition tables also
5513 support "l" (or "logical") and "e" (or "extended") partition types.
5514 "startsect" and "endsect" are the start and end of the partition in
5516 sectors. "endsect" may be negative, which means it counts
5517 backwards from the end of the disk ("-1" is the last sector).
5518 Creating a partition which covers the whole disk is not so easy.
5520 Use "$g->part_disk" to do that.
5521 $g->part_del ($device, $partnum);
5523 This command deletes the partition numbered "partnum" on "device".
5524 Note that in the case of MBR partitioning, deleting an extended
5526 partition also deletes any logical partitions it contains.
5527 $g->part_disk ($device, $parttype);
5529 This command is simply a combination of "$g->part_init" followed by
5530 "$g->part_add" to create a single primary partition covering the
5531 whole disk.
5532 "parttype" is the partition table type, usually "mbr" or "gpt", but
5534 other possible values are described in "$g->part_init".
5535 $g->part_expand_gpt ($device);
5537 Move backup GPT data structures to the end of the disk. This is
5538 useful in case of in-place image expand since disk space after
5539 backup GPT header is not usable. This is equivalent to "sgdisk
5540 -e".
5541 See also sgdisk(8).
5543 This function depends on the feature "gdisk". See also
5545 "$g->feature-available".
5546 $bootable = $g->part_get_bootable ($device, $partnum);
5548 This command returns true if the partition "partnum" on "device"
5549 has the bootable flag set.
5550 See also "$g->part_set_bootable".
5552 $guid = $g->part_get_disk_guid ($device);
5554 Return the disk identifier (GUID) of a GPT-partitioned "device".
5555 Behaviour is undefined for other partition types.
5556 This function depends on the feature "gdisk". See also
5558 "$g->feature-available".
5559 $attributes = $g->part_get_gpt_attributes ($device, $partnum);
5561 Return the attribute flags of numbered GPT partition "partnum". An
5562 error is returned for MBR partitions.
5563 This function depends on the feature "gdisk". See also
5565 "$g->feature-available".
5566 $guid = $g->part_get_gpt_guid ($device, $partnum);
5568 Return the GUID of numbered GPT partition "partnum".
5569 This function depends on the feature "gdisk". See also
5571 "$g->feature-available".
5572 $guid = $g->part_get_gpt_type ($device, $partnum);
5574 Return the type GUID of numbered GPT partition "partnum". For MBR
5575 partitions, return an appropriate GUID corresponding to the MBR
5576 type. Behaviour is undefined for other partition types.
5577 This function depends on the feature "gdisk". See also
5579 "$g->feature-available".
5580 $idbyte = $g->part_get_mbr_id ($device, $partnum);
5582 Returns the MBR type byte (also known as the ID byte) from the
5583 numbered partition "partnum".
5584 Note that only MBR (old DOS-style) partitions have type bytes. You
5586 will get undefined results for other partition table types (see
5587 "$g->part_get_parttype").
5588 $partitiontype = $g->part_get_mbr_part_type ($device, $partnum);
5590 This returns the partition type of an MBR partition numbered
5591 "partnum" on device "device".
5592 It returns "primary", "logical", or "extended".
5594 $name = $g->part_get_name ($device, $partnum);
5596 This gets the partition name on partition numbered "partnum" on
5597 device "device". Note that partitions are numbered from 1.
5598 The partition name can only be read on certain types of partition
5600 table. This works on "gpt" but not on "mbr" partitions.
5601 $parttype = $g->part_get_parttype ($device);
5603 This command examines the partition table on "device" and returns
5604 the partition table type (format) being used.
5605 Common return values include: "msdos" (a DOS/Windows style MBR
5607 partition table), "gpt" (a GPT/EFI-style partition table). Other
5608 values are possible, although unusual. See "$g->part_init" for a
5609 full list.
5610 $g->part_init ($device, $parttype);
5612 This creates an empty partition table on "device" of one of the
5613 partition types listed below. Usually "parttype" should be either
5614 "msdos" or "gpt" (for large disks).
5615 Initially there are no partitions. Following this, you should call
5617 "$g->part_add" for each partition required.
5618 Possible values for "parttype" are:
5620 "efi"
5622 "gpt"
5623 Intel EFI / GPT partition table.
5624 This is recommended for >= 2 TB partitions that will be
5626 accessed from Linux and Intel-based Mac OS X. It also has
5627 limited backwards compatibility with the "mbr" format.
5628 "mbr"
5630 "msdos"
5631 The standard PC "Master Boot Record" (MBR) format used by MS-
5632 DOS and Windows. This partition type will only work for device
5633 sizes up to 2 TB. For large disks we recommend using "gpt".
5634 Other partition table types that may work but are not supported
5636 include:
5637 "aix"
5639 AIX disk labels.
5640 "amiga"
5642 "rdb"
5643 Amiga "Rigid Disk Block" format.
5644 "bsd"
5646 BSD disk labels.
5647 "dasd"
5649 DASD, used on IBM mainframes.
5650 "dvh"
5652 MIPS/SGI volumes.
5653 "mac"
5655 Old Mac partition format. Modern Macs use "gpt".
5656 "pc98"
5658 NEC PC-98 format, common in Japan apparently.
5659 "sun"
5661 Sun disk labels.
5662 @partitions = $g->part_list ($device);
5664 This command parses the partition table on "device" and returns the
5665 list of partitions found.
5666 The fields in the returned structure are:
5668 "part_num"
5670 Partition number, counting from 1.
5671 "part_start"
5673 Start of the partition in bytes. To get sectors you have to
5674 divide by the deviceXs sector size, see "$g->blockdev_getss".
5675 "part_end"
5677 End of the partition in bytes.
5678 "part_size"
5680 Size of the partition in bytes.
5681 $g->part_resize ($device, $partnum, $endsect);
5683 This command resizes the partition numbered "partnum" on "device"
5684 by moving the end position.
5685 Note that this does not modify any filesystem present in the
5687 partition. If you wish to do this, you will need to use filesystem
5688 resizing commands like "$g->resize2fs".
5689 When growing a partition you will want to grow the filesystem
5691 afterwards, but when shrinking, you need to shrink the filesystem
5692 before the partition.
5693 $g->part_set_bootable ($device, $partnum, $bootable);
5695 This sets the bootable flag on partition numbered "partnum" on
5696 device "device". Note that partitions are numbered from 1.
5697 The bootable flag is used by some operating systems (notably
5699 Windows) to determine which partition to boot from. It is by no
5700 means universally recognized.
5701 $g->part_set_disk_guid ($device, $guid);
5703 Set the disk identifier (GUID) of a GPT-partitioned "device" to
5704 "guid". Return an error if the partition table of "device" isn't
5705 GPT, or if "guid" is not a valid GUID.
5706 This function depends on the feature "gdisk". See also
5708 "$g->feature-available".
5709 $g->part_set_disk_guid_random ($device);
5711 Set the disk identifier (GUID) of a GPT-partitioned "device" to a
5712 randomly generated value. Return an error if the partition table
5713 of "device" isn't GPT.
5714 This function depends on the feature "gdisk". See also
5716 "$g->feature-available".
5717 $g->part_set_gpt_attributes ($device, $partnum, $attributes);
5719 Set the attribute flags of numbered GPT partition "partnum" to
5720 "attributes". Return an error if the partition table of "device"
5721 isn't GPT.
5722 See
5724 <https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_entries>
5725 for a useful list of partition attributes.
5726 This function depends on the feature "gdisk". See also
5728 "$g->feature-available".
5729 $g->part_set_gpt_guid ($device, $partnum, $guid);
5731 Set the GUID of numbered GPT partition "partnum" to "guid". Return
5732 an error if the partition table of "device" isn't GPT, or if "guid"
5733 is not a valid GUID.
5734 This function depends on the feature "gdisk". See also
5736 "$g->feature-available".
5737 $g->part_set_gpt_type ($device, $partnum, $guid);
5739 Set the type GUID of numbered GPT partition "partnum" to "guid".
5740 Return an error if the partition table of "device" isn't GPT, or if
5741 "guid" is not a valid GUID.
5742 See
5744 <https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs>
5745 for a useful list of type GUIDs.
5746 This function depends on the feature "gdisk". See also
5748 "$g->feature-available".
5749 $g->part_set_mbr_id ($device, $partnum, $idbyte);
5751 Sets the MBR type byte (also known as the ID byte) of the numbered
5752 partition "partnum" to "idbyte". Note that the type bytes quoted
5753 in most documentation are in fact hexadecimal numbers, but usually
5754 documented without any leading "0x" which might be confusing.
5755 Note that only MBR (old DOS-style) partitions have type bytes. You
5757 will get undefined results for other partition table types (see
5758 "$g->part_get_parttype").
5759 $g->part_set_name ($device, $partnum, $name);
5761 This sets the partition name on partition numbered "partnum" on
5762 device "device". Note that partitions are numbered from 1.
5763 The partition name can only be set on certain types of partition
5765 table. This works on "gpt" but not on "mbr" partitions.
5766 $device = $g->part_to_dev ($partition);
5768 This function takes a partition name (eg. "/dev/sdb1") and removes
5769 the partition number, returning the device name (eg. "/dev/sdb").
5770 The named partition must exist, for example as a string returned
5772 from "$g->list_partitions".
5773 See also "$g->part_to_partnum", "$g->device_index".
5775 $partnum = $g->part_to_partnum ($partition);
5777 This function takes a partition name (eg. "/dev/sdb1") and returns
5778 the partition number (eg. 1).
5779 The named partition must exist, for example as a string returned
5781 from "$g->list_partitions".
5782 See also "$g->part_to_dev".
5784 $g->ping_daemon ();
5786 This is a test probe into the guestfs daemon running inside the
5787 libguestfs appliance. Calling this function checks that the daemon
5788 responds to the ping message, without affecting the daemon or
5789 attached block device(s) in any other way.
5790 $content = $g->pread ($path, $count, $offset);
5792 This command lets you read part of a file. It reads "count" bytes
5793 of the file, starting at "offset", from file "path".
5794 This may read fewer bytes than requested. For further details see
5796 the pread(2) system call.
5797 See also "$g->pwrite", "$g->pread_device".
5799 Because of the message protocol, there is a transfer limit of
5801 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5802 guestfs(3).
5803 $content = $g->pread_device ($device, $count, $offset);
5805 This command lets you read part of a block device. It reads
5806 "count" bytes of "device", starting at "offset".
5807 This may read fewer bytes than requested. For further details see
5809 the pread(2) system call.
5810 See also "$g->pread".
5812 Because of the message protocol, there is a transfer limit of
5814 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5815 guestfs(3).
5816 $g->pvchange_uuid ($device);
5818 Generate a new random UUID for the physical volume "device".
5819 This function depends on the feature "lvm2". See also
5821 "$g->feature-available".
5822 $g->pvchange_uuid_all ();
5824 Generate new random UUIDs for all physical volumes.
5825 This function depends on the feature "lvm2". See also
5827 "$g->feature-available".
5828 $g->pvcreate ($device);
5830 This creates an LVM physical volume on the named "device", where
5831 "device" should usually be a partition name such as /dev/sda1.
5832 This function depends on the feature "lvm2". See also
5834 "$g->feature-available".
5835 $g->pvremove ($device);
5837 This wipes a physical volume "device" so that LVM will no longer
5838 recognise it.
5839 The implementation uses the pvremove(8) command which refuses to
5841 wipe physical volumes that contain any volume groups, so you have
5842 to remove those first.
5843 This function depends on the feature "lvm2". See also
5845 "$g->feature-available".
5846 $g->pvresize ($device);
5848 This resizes (expands or shrinks) an existing LVM physical volume
5849 to match the new size of the underlying device.
5850 This function depends on the feature "lvm2". See also
5852 "$g->feature-available".
5853 $g->pvresize_size ($device, $size);
5855 This command is the same as "$g->pvresize" except that it allows
5856 you to specify the new size (in bytes) explicitly.
5857 This function depends on the feature "lvm2". See also
5859 "$g->feature-available".
5860 @physvols = $g->pvs ();
5862 List all the physical volumes detected. This is the equivalent of
5863 the pvs(8) command.
5864 This returns a list of just the device names that contain PVs (eg.
5866 /dev/sda2).
5867 See also "$g->pvs_full".
5869 This function depends on the feature "lvm2". See also
5871 "$g->feature-available".
5872 @physvols = $g->pvs_full ();
5874 List all the physical volumes detected. This is the equivalent of
5875 the pvs(8) command. The "full" version includes all fields.
5876 This function depends on the feature "lvm2". See also
5878 "$g->feature-available".
5879 $uuid = $g->pvuuid ($device);
5881 This command returns the UUID of the LVM PV "device".
5882 $nbytes = $g->pwrite ($path, $content, $offset);
5884 This command writes to part of a file. It writes the data buffer
5885 "content" to the file "path" starting at offset "offset".
5886 This command implements the pwrite(2) system call, and like that
5888 system call it may not write the full data requested. The return
5889 value is the number of bytes that were actually written to the
5890 file. This could even be 0, although short writes are unlikely for
5891 regular files in ordinary circumstances.
5892 See also "$g->pread", "$g->pwrite_device".
5894 Because of the message protocol, there is a transfer limit of
5896 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5897 guestfs(3).
5898 $nbytes = $g->pwrite_device ($device, $content, $offset);
5900 This command writes to part of a device. It writes the data buffer
5901 "content" to "device" starting at offset "offset".
5902 This command implements the pwrite(2) system call, and like that
5904 system call it may not write the full data requested (although
5905 short writes to disk devices and partitions are probably impossible
5906 with standard Linux kernels).
5907 See also "$g->pwrite".
5909 Because of the message protocol, there is a transfer limit of
5911 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5912 guestfs(3).
5913 $content = $g->read_file ($path);
5915 This calls returns the contents of the file "path" as a buffer.
5916 Unlike "$g->cat", this function can correctly handle files that
5918 contain embedded ASCII NUL characters.
5919 @lines = $g->read_lines ($path);
5921 Return the contents of the file named "path".
5922 The file contents are returned as a list of lines. Trailing "LF"
5924 and "CRLF" character sequences are not returned.
5925 Note that this function cannot correctly handle binary files
5927 (specifically, files containing "\0" character which is treated as
5928 end of string). For those you need to use the "$g->read_file"
5929 function and split the buffer into lines yourself.
5930 @entries = $g->readdir ($dir);
5932 This returns the list of directory entries in directory "dir".
5933 All entries in the directory are returned, including "." and "..".
5935 The entries are not sorted, but returned in the same order as the
5936 underlying filesystem.
5937 Also this call returns basic file type information about each file.
5939 The "ftyp" field will contain one of the following characters:
5940 'b' Block special
5942 'c' Char special
5944 'd' Directory
5946 'f' FIFO (named pipe)
5948 'l' Symbolic link
5950 'r' Regular file
5952 's' Socket
5954 'u' Unknown file type
5956 '?' The readdir(3) call returned a "d_type" field with an
5958 unexpected value
5959 This function is primarily intended for use by programs. To get a
5961 simple list of names, use "$g->ls". To get a printable directory
5962 for human consumption, use "$g->ll".
5963 Because of the message protocol, there is a transfer limit of
5965 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5966 guestfs(3).
5967 $link = $g->readlink ($path);
5969 This command reads the target of a symbolic link.
5970 @links = $g->readlinklist ($path, \@names);
5972 This call allows you to do a "readlink" operation on multiple
5973 files, where all files are in the directory "path". "names" is the
5974 list of files from this directory.
5975 On return you get a list of strings, with a one-to-one
5977 correspondence to the "names" list. Each string is the value of
5978 the symbolic link.
5979 If the readlink(2) operation fails on any name, then the
5981 corresponding result string is the empty string "". However the
5982 whole operation is completed even if there were readlink(2) errors,
5983 and so you can call this function with names where you don't know
5984 if they are symbolic links already (albeit slightly less
5985 efficient).
5986 This call is intended for programs that want to efficiently list a
5988 directory contents without making many round-trips.
5989 $rpath = $g->realpath ($path);
5991 Return the canonicalized absolute pathname of "path". The returned
5992 path has no ".", ".." or symbolic link path elements.
5993 $g->remount ($mountpoint [, rw => $rw]);
5995 This call allows you to change the "rw" (readonly/read-write) flag
5996 on an already mounted filesystem at "mountpoint", converting a
5997 readonly filesystem to be read-write, or vice-versa.
5998 Note that at the moment you must supply the "optional" "rw"
6000 parameter. In future we may allow other flags to be adjusted.
6001 $g->remove_drive ($label);
6003 This function is conceptually the opposite of "$g->add_drive_opts".
6004 It removes the drive that was previously added with label "label".
6005 Note that in order to remove drives, you have to add them with
6007 labels (see the optional "label" argument to "$g->add_drive_opts").
6008 If you didn't use a label, then they cannot be removed.
6009 You can call this function before or after launching the handle.
6011 If called after launch, if the backend supports it, we try to hot
6012 unplug the drive: see "HOTPLUGGING" in guestfs(3). The disk must
6013 not be in use (eg. mounted) when you do this. We try to detect if
6014 the disk is in use and stop you from doing this.
6015 $g->removexattr ($xattr, $path);
6017 This call removes the extended attribute named "xattr" of the file
6018 "path".
6019 See also: "$g->lremovexattr", attr(5).
6021 This function depends on the feature "linuxxattrs". See also
6023 "$g->feature-available".
6024 $g->rename ($oldpath, $newpath);
6026 Rename a file to a new place on the same filesystem. This is the
6027 same as the Linux rename(2) system call. In most cases you are
6028 better to use "$g->mv" instead.
6029 $g->resize2fs ($device);
6031 This resizes an ext2, ext3 or ext4 filesystem to match the size of
6032 the underlying device.
6033 See also "RESIZE2FS ERRORS" in guestfs(3).
6035 $g->resize2fs_M ($device);
6037 This command is the same as "$g->resize2fs", but the filesystem is
6038 resized to its minimum size. This works like the -M option to the
6039 resize2fs(8) command.
6040 To get the resulting size of the filesystem you should call
6042 "$g->tune2fs_l" and read the "Block size" and "Block count" values.
6043 These two numbers, multiplied together, give the resulting size of
6044 the minimal filesystem in bytes.
6045 See also "RESIZE2FS ERRORS" in guestfs(3).
6047 $g->resize2fs_size ($device, $size);
6049 This command is the same as "$g->resize2fs" except that it allows
6050 you to specify the new size (in bytes) explicitly.
6051 See also "RESIZE2FS ERRORS" in guestfs(3).
6053 $g->rm ($path);
6055 Remove the single file "path".
6056 $g->rm_f ($path);
6058 Remove the file "path".
6059 If the file doesn't exist, that error is ignored. (Other errors,
6061 eg. I/O errors or bad paths, are not ignored)
6062 This call cannot remove directories. Use "$g->rmdir" to remove an
6064 empty directory, or "$g->rm_rf" to remove directories recursively.
6065 $g->rm_rf ($path);
6067 Remove the file or directory "path", recursively removing the
6068 contents if its a directory. This is like the "rm -rf" shell
6069 command.
6070 $g->rmdir ($path);
6072 Remove the single directory "path".
6073 $g->rmmountpoint ($exemptpath);
6075 This call removes a mountpoint that was previously created with
6076 "$g->mkmountpoint". See "$g->mkmountpoint" for full details.
6077 $g->rsync ($src, $dest [, archive => $archive] [, deletedest =>
6079 $deletedest]);
6080 This call may be used to copy or synchronize two directories under
6081 the same libguestfs handle. This uses the rsync(1) program which
6082 uses a fast algorithm that avoids copying files unnecessarily.
6083 "src" and "dest" are the source and destination directories. Files
6085 are copied from "src" to "dest".
6086 The optional arguments are:
6088 "archive"
6090 Turns on archive mode. This is the same as passing the
6091 --archive flag to "rsync".
6092 "deletedest"
6094 Delete files at the destination that do not exist at the
6095 source.
6096 This function depends on the feature "rsync". See also
6098 "$g->feature-available".
6099 $g->rsync_in ($remote, $dest [, archive => $archive] [, deletedest =>
6101 $deletedest]);
6102 This call may be used to copy or synchronize the filesystem on the
6103 host or on a remote computer with the filesystem within libguestfs.
6104 This uses the rsync(1) program which uses a fast algorithm that
6105 avoids copying files unnecessarily.
6106 This call only works if the network is enabled. See
6108 "$g->set_network" or the --network option to various tools like
6109 guestfish(1).
6110 Files are copied from the remote server and directory specified by
6112 "remote" to the destination directory "dest".
6113 The format of the remote server string is defined by rsync(1).
6115 Note that there is no way to supply a password or passphrase so the
6116 target must be set up not to require one.
6117 The optional arguments are the same as those of "$g->rsync".
6119 This function depends on the feature "rsync". See also
6121 "$g->feature-available".
6122 $g->rsync_out ($src, $remote [, archive => $archive] [, deletedest =>
6124 $deletedest]);
6125 This call may be used to copy or synchronize the filesystem within
6126 libguestfs with a filesystem on the host or on a remote computer.
6127 This uses the rsync(1) program which uses a fast algorithm that
6128 avoids copying files unnecessarily.
6129 This call only works if the network is enabled. See
6131 "$g->set_network" or the --network option to various tools like
6132 guestfish(1).
6133 Files are copied from the source directory "src" to the remote
6135 server and directory specified by "remote".
6136 The format of the remote server string is defined by rsync(1).
6138 Note that there is no way to supply a password or passphrase so the
6139 target must be set up not to require one.
6140 The optional arguments are the same as those of "$g->rsync".
6142 Globbing does not happen on the "src" parameter. In programs which
6144 use the API directly you have to expand wildcards yourself (see
6145 "$g->glob_expand"). In guestfish you can use the "glob" command
6146 (see "glob" in guestfish(1)), for example:
6147 ><fs> glob rsync-out /* rsync://remote/
6149 This function depends on the feature "rsync". See also
6151 "$g->feature-available".
6152 $g->scrub_device ($device);
6154 This command writes patterns over "device" to make data retrieval
6155 more difficult.
6156 It is an interface to the scrub(1) program. See that manual page
6158 for more details.
6159 This function depends on the feature "scrub". See also
6161 "$g->feature-available".
6162 $g->scrub_file ($file);
6164 This command writes patterns over a file to make data retrieval
6165 more difficult.
6166 The file is removed after scrubbing.
6168 It is an interface to the scrub(1) program. See that manual page
6170 for more details.
6171 This function depends on the feature "scrub". See also
6173 "$g->feature-available".
6174 $g->scrub_freespace ($dir);
6176 This command creates the directory "dir" and then fills it with
6177 files until the filesystem is full, and scrubs the files as for
6178 "$g->scrub_file", and deletes them. The intention is to scrub any
6179 free space on the partition containing "dir".
6180 It is an interface to the scrub(1) program. See that manual page
6182 for more details.
6183 This function depends on the feature "scrub". See also
6185 "$g->feature-available".
6186 $g->selinux_relabel ($specfile, $path [, force => $force]);
6188 SELinux relabel parts of the filesystem.
6189 The "specfile" parameter controls the policy spec file used. You
6191 have to parse "/etc/selinux/config" to find the correct SELinux
6192 policy and then pass the spec file, usually: "/etc/selinux/" +
6193 selinuxtype + "/contexts/files/file_contexts".
6194 The required "path" parameter is the top level directory where
6196 relabelling starts. Normally you should pass "path" as "/" to
6197 relabel the whole guest filesystem.
6198 The optional "force" boolean controls whether the context is reset
6200 for customizable files, and also whether the user, role and range
6201 parts of the file context is changed.
6202 This function depends on the feature "selinuxrelabel". See also
6204 "$g->feature-available".
6205 $g->set_append ($append);
6207 This function is used to add additional options to the libguestfs
6208 appliance kernel command line.
6209 The default is "NULL" unless overridden by setting
6211 "LIBGUESTFS_APPEND" environment variable.
6212 Setting "append" to "NULL" means no additional options are passed
6214 (libguestfs always adds a few of its own).
6215 $g->set_attach_method ($backend);
6217 Set the method that libguestfs uses to connect to the backend
6218 guestfsd daemon.
6219 See "BACKEND" in guestfs(3).
6221 This function is deprecated. In new code, use the "set_backend"
6223 call instead.
6224 Deprecated functions will not be removed from the API, but the fact
6226 that they are deprecated indicates that there are problems with
6227 correct use of these functions.
6228 $g->set_autosync ($autosync);
6230 If "autosync" is true, this enables autosync. Libguestfs will make
6231 a best effort attempt to make filesystems consistent and
6232 synchronized when the handle is closed (also if the program exits
6233 without closing handles).
6234 This is enabled by default (since libguestfs 1.5.24, previously it
6236 was disabled by default).
6237 $g->set_backend ($backend);
6239 Set the method that libguestfs uses to connect to the backend
6240 guestfsd daemon.
6241 This handle property was previously called the "attach method".
6243 See "BACKEND" in guestfs(3).
6245 $g->set_backend_setting ($name, $val);
6247 Append "name=value" to the backend settings string list. However
6248 if a string already exists matching "name" or beginning with
6249 "name=", then that setting is replaced.
6250 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
6252 $g->set_backend_settings (\@settings);
6254 Set a list of zero or more settings which are passed through to the
6255 current backend. Each setting is a string which is interpreted in
6256 a backend-specific way, or ignored if not understood by the
6257 backend.
6258 The default value is an empty list, unless the environment variable
6260 "LIBGUESTFS_BACKEND_SETTINGS" was set when the handle was created.
6261 This environment variable contains a colon-separated list of
6262 settings.
6263 This call replaces all backend settings. If you want to replace a
6265 single backend setting, see "$g->set_backend_setting". If you want
6266 to clear a single backend setting, see "$g->clear_backend_setting".
6267 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
6269 $g->set_cachedir ($cachedir);
6271 Set the directory used by the handle to store the appliance cache,
6272 when using a supermin appliance. The appliance is cached and
6273 shared between all handles which have the same effective user ID.
6274 The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR"
6276 control the default value: If "LIBGUESTFS_CACHEDIR" is set, then
6277 that is the default. Else if "TMPDIR" is set, then that is the
6278 default. Else /var/tmp is the default.
6279 $g->set_direct ($direct);
6281 If the direct appliance mode flag is enabled, then stdin and stdout
6282 are passed directly through to the appliance once it is launched.
6283 One consequence of this is that log messages aren't caught by the
6285 library and handled by "$g->set_log_message_callback", but go
6286 straight to stdout.
6287 You probably don't want to use this unless you know what you are
6289 doing.
6290 The default is disabled.
6292 This function is deprecated. In new code, use the
6294 "internal_get_console_socket" call instead.
6295 Deprecated functions will not be removed from the API, but the fact
6297 that they are deprecated indicates that there are problems with
6298 correct use of these functions.
6299 $g->set_e2attrs ($file, $attrs [, clear => $clear]);
6301 This sets or clears the file attributes "attrs" associated with the
6302 inode file.
6303 "attrs" is a string of characters representing file attributes.
6305 See "$g->get_e2attrs" for a list of possible attributes. Not all
6306 attributes can be changed.
6307 If optional boolean "clear" is not present or false, then the
6309 "attrs" listed are set in the inode.
6310 If "clear" is true, then the "attrs" listed are cleared in the
6312 inode.
6313 In both cases, other attributes not present in the "attrs" string
6315 are left unchanged.
6316 These attributes are only present when the file is located on an
6318 ext2/3/4 filesystem. Using this call on other filesystem types
6319 will result in an error.
6320 $g->set_e2generation ($file, $generation);
6322 This sets the ext2 file generation of a file.
6323 See "$g->get_e2generation".
6325 $g->set_e2label ($device, $label);
6327 This sets the ext2/3/4 filesystem label of the filesystem on
6328 "device" to "label". Filesystem labels are limited to 16
6329 characters.
6330 You can use either "$g->tune2fs_l" or "$g->get_e2label" to return
6332 the existing label on a filesystem.
6333 This function is deprecated. In new code, use the "set_label" call
6335 instead.
6336 Deprecated functions will not be removed from the API, but the fact
6338 that they are deprecated indicates that there are problems with
6339 correct use of these functions.
6340 $g->set_e2uuid ($device, $uuid);
6342 This sets the ext2/3/4 filesystem UUID of the filesystem on
6343 "device" to "uuid". The format of the UUID and alternatives such
6344 as "clear", "random" and "time" are described in the tune2fs(8)
6345 manpage.
6346 You can use "$g->vfs_uuid" to return the existing UUID of a
6348 filesystem.
6349 This function is deprecated. In new code, use the "set_uuid" call
6351 instead.
6352 Deprecated functions will not be removed from the API, but the fact
6354 that they are deprecated indicates that there are problems with
6355 correct use of these functions.
6356 $g->set_hv ($hv);
6358 Set the hypervisor binary that we will use. The hypervisor depends
6359 on the backend, but is usually the location of the qemu/KVM
6360 hypervisor. For the uml backend, it is the location of the "linux"
6361 or "vmlinux" binary.
6362 The default is chosen when the library was compiled by the
6364 configure script.
6365 You can also override this by setting the "LIBGUESTFS_HV"
6367 environment variable.
6368 Note that you should call this function as early as possible after
6370 creating the handle. This is because some pre-launch operations
6371 depend on testing qemu features (by running "qemu -help"). If the
6372 qemu binary changes, we don't retest features, and so you might see
6373 inconsistent results. Using the environment variable
6374 "LIBGUESTFS_HV" is safest of all since that picks the qemu binary
6375 at the same time as the handle is created.
6376 $g->set_identifier ($identifier);
6378 This is an informative string which the caller may optionally set
6379 in the handle. It is printed in various places, allowing the
6380 current handle to be identified in debugging output.
6381 One important place is when tracing is enabled. If the identifier
6383 string is not an empty string, then trace messages change from
6384 this:
6385 libguestfs: trace: get_tmpdir
6387 libguestfs: trace: get_tmpdir = "/tmp"
6388 to this:
6390 libguestfs: trace: ID: get_tmpdir
6392 libguestfs: trace: ID: get_tmpdir = "/tmp"
6393 where "ID" is the identifier string set by this call.
6395 The identifier must only contain alphanumeric ASCII characters,
6397 underscore and minus sign. The default is the empty string.
6398 See also "$g->set_program", "$g->set_trace", "$g->get_identifier".
6400 $g->set_label ($mountable, $label);
6402 Set the filesystem label on "mountable" to "label".
6403 Only some filesystem types support labels, and libguestfs supports
6405 setting labels on only a subset of these.
6406 ext2, ext3, ext4
6408 Labels are limited to 16 bytes.
6409 NTFS
6411 Labels are limited to 128 unicode characters.
6412 XFS The label is limited to 12 bytes. The filesystem must not be
6414 mounted when trying to set the label.
6415 btrfs
6417 The label is limited to 255 bytes and some characters are not
6418 allowed. Setting the label on a btrfs subvolume will set the
6419 label on its parent filesystem. The filesystem must not be
6420 mounted when trying to set the label.
6421 fat The label is limited to 11 bytes.
6423 swap
6425 The label is limited to 16 bytes.
6426 If there is no support for changing the label for the type of the
6428 specified filesystem, set_label will fail and set errno as ENOTSUP.
6429 To read the label on a filesystem, call "$g->vfs_label".
6431 $g->set_libvirt_requested_credential ($index, $cred);
6433 After requesting the "index"'th credential from the user, call this
6434 function to pass the answer back to libvirt.
6435 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
6437 example code.
6438 $g->set_libvirt_supported_credentials (\@creds);
6440 Call this function before setting an event handler for
6441 "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential
6442 types that the program knows how to process.
6443 The "creds" list must be a non-empty list of strings. Possible
6445 strings are:
6446 "username"
6448 "authname"
6449 "language"
6450 "cnonce"
6451 "passphrase"
6452 "echoprompt"
6453 "noechoprompt"
6454 "realm"
6455 "external"
6456 See libvirt documentation for the meaning of these credential
6458 types.
6459 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
6461 example code.
6462 $g->set_memsize ($memsize);
6464 This sets the memory size in megabytes allocated to the hypervisor.
6465 This only has any effect if called before "$g->launch".
6466 You can also change this by setting the environment variable
6468 "LIBGUESTFS_MEMSIZE" before the handle is created.
6469 For more information on the architecture of libguestfs, see
6471 guestfs(3).
6472 $g->set_network ($network);
6474 If "network" is true, then the network is enabled in the libguestfs
6475 appliance. The default is false.
6476 This affects whether commands are able to access the network (see
6478 "RUNNING COMMANDS" in guestfs(3)).
6479 You must call this before calling "$g->launch", otherwise it has no
6481 effect.
6482 $g->set_path ($searchpath);
6484 Set the path that libguestfs searches for kernel and initrd.img.
6485 The default is "$libdir/guestfs" unless overridden by setting
6487 "LIBGUESTFS_PATH" environment variable.
6488 Setting "path" to "NULL" restores the default path.
6490 $g->set_pgroup ($pgroup);
6492 If "pgroup" is true, child processes are placed into their own
6493 process group.
6494 The practical upshot of this is that signals like "SIGINT" (from
6496 users pressing "^C") won't be received by the child process.
6497 The default for this flag is false, because usually you want "^C"
6499 to kill the subprocess. Guestfish sets this flag to true when used
6500 interactively, so that "^C" can cancel long-running commands
6501 gracefully (see "$g->user_cancel").
6502 $g->set_program ($program);
6504 Set the program name. This is an informative string which the main
6505 program may optionally set in the handle.
6506 When the handle is created, the program name in the handle is set
6508 to the basename from "argv[0]". The program name can never be
6509 "NULL".
6510 $g->set_qemu ($hv);
6512 Set the hypervisor binary (usually qemu) that we will use.
6513 The default is chosen when the library was compiled by the
6515 configure script.
6516 You can also override this by setting the "LIBGUESTFS_HV"
6518 environment variable.
6519 Setting "hv" to "NULL" restores the default qemu binary.
6521 Note that you should call this function as early as possible after
6523 creating the handle. This is because some pre-launch operations
6524 depend on testing qemu features (by running "qemu -help"). If the
6525 qemu binary changes, we don't retest features, and so you might see
6526 inconsistent results. Using the environment variable
6527 "LIBGUESTFS_HV" is safest of all since that picks the qemu binary
6528 at the same time as the handle is created.
6529 This function is deprecated. In new code, use the "set_hv" call
6531 instead.
6532 Deprecated functions will not be removed from the API, but the fact
6534 that they are deprecated indicates that there are problems with
6535 correct use of these functions.
6536 $g->set_recovery_proc ($recoveryproc);
6538 If this is called with the parameter "false" then "$g->launch" does
6539 not create a recovery process. The purpose of the recovery process
6540 is to stop runaway hypervisor processes in the case where the main
6541 program aborts abruptly.
6542 This only has any effect if called before "$g->launch", and the
6544 default is true.
6545 About the only time when you would want to disable this is if the
6547 main process will fork itself into the background ("daemonize"
6548 itself). In this case the recovery process thinks that the main
6549 program has disappeared and so kills the hypervisor, which is not
6550 very helpful.
6551 $g->set_selinux ($selinux);
6553 This sets the selinux flag that is passed to the appliance at boot
6554 time. The default is "selinux=0" (disabled).
6555 Note that if SELinux is enabled, it is always in Permissive mode
6557 ("enforcing=0").
6558 For more information on the architecture of libguestfs, see
6560 guestfs(3).
6561 This function is deprecated. In new code, use the
6563 "selinux_relabel" call instead.
6564 Deprecated functions will not be removed from the API, but the fact
6566 that they are deprecated indicates that there are problems with
6567 correct use of these functions.
6568 $g->set_smp ($smp);
6570 Change the number of virtual CPUs assigned to the appliance. The
6571 default is 1. Increasing this may improve performance, though
6572 often it has no effect.
6573 This function must be called before "$g->launch".
6575 $g->set_tmpdir ($tmpdir);
6577 Set the directory used by the handle to store temporary files.
6578 The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control
6580 the default value: If "LIBGUESTFS_TMPDIR" is set, then that is the
6581 default. Else if "TMPDIR" is set, then that is the default. Else
6582 /tmp is the default.
6583 $g->set_trace ($trace);
6585 If the command trace flag is set to 1, then libguestfs calls,
6586 parameters and return values are traced.
6587 If you want to trace C API calls into libguestfs (and other
6589 libraries) then possibly a better way is to use the external
6590 ltrace(1) command.
6591 Command traces are disabled unless the environment variable
6593 "LIBGUESTFS_TRACE" is defined and set to 1.
6594 Trace messages are normally sent to "stderr", unless you register a
6596 callback to send them somewhere else (see
6597 "$g->set_event_callback").
6598 $g->set_uuid ($device, $uuid);
6600 Set the filesystem UUID on "device" to "uuid". If this fails and
6601 the errno is ENOTSUP, means that there is no support for changing
6602 the UUID for the type of the specified filesystem.
6603 Only some filesystem types support setting UUIDs.
6605 To read the UUID on a filesystem, call "$g->vfs_uuid".
6607 $g->set_uuid_random ($device);
6609 Set the filesystem UUID on "device" to a random UUID. If this
6610 fails and the errno is ENOTSUP, means that there is no support for
6611 changing the UUID for the type of the specified filesystem.
6612 Only some filesystem types support setting UUIDs.
6614 To read the UUID on a filesystem, call "$g->vfs_uuid".
6616 $g->set_verbose ($verbose);
6618 If "verbose" is true, this turns on verbose messages.
6619 Verbose messages are disabled unless the environment variable
6621 "LIBGUESTFS_DEBUG" is defined and set to 1.
6622 Verbose messages are normally sent to "stderr", unless you register
6624 a callback to send them somewhere else (see
6625 "$g->set_event_callback").
6626 $g->setcon ($context);
6628 This sets the SELinux security context of the daemon to the string
6629 "context".
6630 See the documentation about SELINUX in guestfs(3).
6632 This function depends on the feature "selinux". See also
6634 "$g->feature-available".
6635 This function is deprecated. In new code, use the
6637 "selinux_relabel" call instead.
6638 Deprecated functions will not be removed from the API, but the fact
6640 that they are deprecated indicates that there are problems with
6641 correct use of these functions.
6642 $g->setxattr ($xattr, $val, $vallen, $path);
6644 This call sets the extended attribute named "xattr" of the file
6645 "path" to the value "val" (of length "vallen"). The value is
6646 arbitrary 8 bit data.
6647 See also: "$g->lsetxattr", attr(5).
6649 This function depends on the feature "linuxxattrs". See also
6651 "$g->feature-available".
6652 $g->sfdisk ($device, $cyls, $heads, $sectors, \@lines);
6654 This is a direct interface to the sfdisk(8) program for creating
6655 partitions on block devices.
6656 "device" should be a block device, for example /dev/sda.
6658 "cyls", "heads" and "sectors" are the number of cylinders, heads
6660 and sectors on the device, which are passed directly to sfdisk(8)
6661 as the -C, -H and -S parameters. If you pass 0 for any of these,
6662 then the corresponding parameter is omitted. Usually for XlargeX
6663 disks, you can just pass 0 for these, but for small (floppy-sized)
6664 disks, sfdisk(8) (or rather, the kernel) cannot work out the right
6665 geometry and you will need to tell it.
6666 "lines" is a list of lines that we feed to sfdisk(8). For more
6668 information refer to the sfdisk(8) manpage.
6669 To create a single partition occupying the whole disk, you would
6671 pass "lines" as a single element list, when the single element
6672 being the string "," (comma).
6673 See also: "$g->sfdisk_l", "$g->sfdisk_N", "$g->part_init"
6675 This function is deprecated. In new code, use the "part_add" call
6677 instead.
6678 Deprecated functions will not be removed from the API, but the fact
6680 that they are deprecated indicates that there are problems with
6681 correct use of these functions.
6682 $g->sfdiskM ($device, \@lines);
6684 This is a simplified interface to the "$g->sfdisk" command, where
6685 partition sizes are specified in megabytes only (rounded to the
6686 nearest cylinder) and you don't need to specify the cyls, heads and
6687 sectors parameters which were rarely if ever used anyway.
6688 See also: "$g->sfdisk", the sfdisk(8) manpage and "$g->part_disk"
6690 This function is deprecated. In new code, use the "part_add" call
6692 instead.
6693 Deprecated functions will not be removed from the API, but the fact
6695 that they are deprecated indicates that there are problems with
6696 correct use of these functions.
6697 $g->sfdisk_N ($device, $partnum, $cyls, $heads, $sectors, $line);
6699 This runs sfdisk(8) option to modify just the single partition "n"
6700 (note: "n" counts from 1).
6701 For other parameters, see "$g->sfdisk". You should usually pass 0
6703 for the cyls/heads/sectors parameters.
6704 See also: "$g->part_add"
6706 This function is deprecated. In new code, use the "part_add" call
6708 instead.
6709 Deprecated functions will not be removed from the API, but the fact
6711 that they are deprecated indicates that there are problems with
6712 correct use of these functions.
6713 $partitions = $g->sfdisk_disk_geometry ($device);
6715 This displays the disk geometry of "device" read from the partition
6716 table. Especially in the case where the underlying block device
6717 has been resized, this can be different from the kernelXs idea of
6718 the geometry (see "$g->sfdisk_kernel_geometry").
6719 The result is in human-readable format, and not designed to be
6721 parsed.
6722 $partitions = $g->sfdisk_kernel_geometry ($device);
6724 This displays the kernelXs idea of the geometry of "device".
6725 The result is in human-readable format, and not designed to be
6727 parsed.
6728 $partitions = $g->sfdisk_l ($device);
6730 This displays the partition table on "device", in the human-
6731 readable output of the sfdisk(8) command. It is not intended to be
6732 parsed.
6733 See also: "$g->part_list"
6735 This function is deprecated. In new code, use the "part_list" call
6737 instead.
6738 Deprecated functions will not be removed from the API, but the fact
6740 that they are deprecated indicates that there are problems with
6741 correct use of these functions.
6742 $output = $g->sh ($command);
6744 This call runs a command from the guest filesystem via the guestXs
6745 /bin/sh.
6746 This is like "$g->command", but passes the command to:
6748 /bin/sh -c "command"
6750 Depending on the guestXs shell, this usually results in wildcards
6752 being expanded, shell expressions being interpolated and so on.
6753 All the provisos about "$g->command" apply to this call.
6755 @lines = $g->sh_lines ($command);
6757 This is the same as "$g->sh", but splits the result into a list of
6758 lines.
6759 See also: "$g->command_lines"
6761 $g->shutdown ();
6763 This is the opposite of "$g->launch". It performs an orderly
6764 shutdown of the backend process(es). If the autosync flag is set
6765 (which is the default) then the disk image is synchronized.
6766 If the subprocess exits with an error then this function will
6768 return an error, which should not be ignored (it may indicate that
6769 the disk image could not be written out properly).
6770 It is safe to call this multiple times. Extra calls are ignored.
6772 This call does not close or free up the handle. You still need to
6774 call "$g->close" afterwards.
6775 "$g->close" will call this if you don't do it explicitly, but note
6777 that any errors are ignored in that case.
6778 $g->sleep ($secs);
6780 Sleep for "secs" seconds.
6781 %statbuf = $g->stat ($path);
6783 Returns file information for the given "path".
6784 This is the same as the stat(2) system call.
6786 This function is deprecated. In new code, use the "statns" call
6788 instead.
6789 Deprecated functions will not be removed from the API, but the fact
6791 that they are deprecated indicates that there are problems with
6792 correct use of these functions.
6793 %statbuf = $g->statns ($path);
6795 Returns file information for the given "path".
6796 This is the same as the stat(2) system call.
6798 %statbuf = $g->statvfs ($path);
6800 Returns file system statistics for any mounted file system. "path"
6801 should be a file or directory in the mounted file system (typically
6802 it is the mount point itself, but it doesn't need to be).
6803 This is the same as the statvfs(2) system call.
6805 @stringsout = $g->strings ($path);
6807 This runs the strings(1) command on a file and returns the list of
6808 printable strings found.
6809 The "strings" command has, in the past, had problems with parsing
6811 untrusted files. These are mitigated in the current version of
6812 libguestfs, but see "CVE-2014-8484" in guestfs(3).
6813 Because of the message protocol, there is a transfer limit of
6815 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
6816 guestfs(3).
6817 @stringsout = $g->strings_e ($encoding, $path);
6819 This is like the "$g->strings" command, but allows you to specify
6820 the encoding of strings that are looked for in the source file
6821 "path".
6822 Allowed encodings are:
6824 s Single 7-bit-byte characters like ASCII and the ASCII-
6826 compatible parts of ISO-8859-X (this is what "$g->strings"
6827 uses).
6828 S Single 8-bit-byte characters.
6830 b 16-bit big endian strings such as those encoded in UTF-16BE or
6832 UCS-2BE.
6833 l (lower case letter L)
6835 16-bit little endian such as UTF-16LE and UCS-2LE. This is
6836 useful for examining binaries in Windows guests.
6837 B 32-bit big endian such as UCS-4BE.
6839 L 32-bit little endian such as UCS-4LE.
6841 The returned strings are transcoded to UTF-8.
6843 The "strings" command has, in the past, had problems with parsing
6845 untrusted files. These are mitigated in the current version of
6846 libguestfs, but see "CVE-2014-8484" in guestfs(3).
6847 Because of the message protocol, there is a transfer limit of
6849 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
6850 guestfs(3).
6851 $g->swapoff_device ($device);
6853 This command disables the libguestfs appliance swap device or
6854 partition named "device". See "$g->swapon_device".
6855 $g->swapoff_file ($file);
6857 This command disables the libguestfs appliance swap on file.
6858 $g->swapoff_label ($label);
6860 This command disables the libguestfs appliance swap on labeled swap
6861 partition.
6862 $g->swapoff_uuid ($uuid);
6864 This command disables the libguestfs appliance swap partition with
6865 the given UUID.
6866 This function depends on the feature "linuxfsuuid". See also
6868 "$g->feature-available".
6869 $g->swapon_device ($device);
6871 This command enables the libguestfs appliance to use the swap
6872 device or partition named "device". The increased memory is made
6873 available for all commands, for example those run using
6874 "$g->command" or "$g->sh".
6875 Note that you should not swap to existing guest swap partitions
6877 unless you know what you are doing. They may contain hibernation
6878 information, or other information that the guest doesn't want you
6879 to trash. You also risk leaking information about the host to the
6880 guest this way. Instead, attach a new host device to the guest and
6881 swap on that.
6882 $g->swapon_file ($file);
6884 This command enables swap to a file. See "$g->swapon_device" for
6885 other notes.
6886 $g->swapon_label ($label);
6888 This command enables swap to a labeled swap partition. See
6889 "$g->swapon_device" for other notes.
6890 $g->swapon_uuid ($uuid);
6892 This command enables swap to a swap partition with the given UUID.
6893 See "$g->swapon_device" for other notes.
6894 This function depends on the feature "linuxfsuuid". See also
6896 "$g->feature-available".
6897 $g->sync ();
6899 This syncs the disk, so that any writes are flushed through to the
6900 underlying disk image.
6901 You should always call this if you have modified a disk image,
6903 before closing the handle.
6904 $g->syslinux ($device [, directory => $directory]);
6906 Install the SYSLINUX bootloader on "device".
6907 The device parameter must be either a whole disk formatted as a FAT
6909 filesystem, or a partition formatted as a FAT filesystem. In the
6910 latter case, the partition should be marked as "active"
6911 ("$g->part_set_bootable") and a Master Boot Record must be
6912 installed (eg. using "$g->pwrite_device") on the first sector of
6913 the whole disk. The SYSLINUX package comes with some suitable
6914 Master Boot Records. See the syslinux(1) man page for further
6915 information.
6916 The optional arguments are:
6918 directory
6920 Install SYSLINUX in the named subdirectory, instead of in the
6921 root directory of the FAT filesystem.
6922 Additional configuration can be supplied to SYSLINUX by placing a
6924 file called syslinux.cfg on the FAT filesystem, either in the root
6925 directory, or under directory if that optional argument is being
6926 used. For further information about the contents of this file, see
6927 syslinux(1).
6928 See also "$g->extlinux".
6930 This function depends on the feature "syslinux". See also
6932 "$g->feature-available".
6933 @lines = $g->tail ($path);
6935 This command returns up to the last 10 lines of a file as a list of
6936 strings.
6937 Because of the message protocol, there is a transfer limit of
6939 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
6940 guestfs(3).
6941 @lines = $g->tail_n ($nrlines, $path);
6943 If the parameter "nrlines" is a positive number, this returns the
6944 last "nrlines" lines of the file "path".
6945 If the parameter "nrlines" is a negative number, this returns lines
6947 from the file "path", starting with the "-nrlines"'th line.
6948 If the parameter "nrlines" is zero, this returns an empty list.
6950 Because of the message protocol, there is a transfer limit of
6952 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
6953 guestfs(3).
6954 $g->tar_in ($tarfile, $directory [, compress => $compress] [, xattrs =>
6956 $xattrs] [, selinux => $selinux] [, acls => $acls]);
6957 This command uploads and unpacks local file "tarfile" into
6958 directory.
6959 The optional "compress" flag controls compression. If not given,
6961 then the input should be an uncompressed tar file. Otherwise one
6962 of the following strings may be given to select the compression
6963 type of the input file: "compress", "gzip", "bzip2", "xz", "lzop".
6964 (Note that not all builds of libguestfs will support all of these
6965 compression types).
6966 The other optional arguments are:
6968 "xattrs"
6970 If set to true, extended attributes are restored from the tar
6971 file.
6972 "selinux"
6974 If set to true, SELinux contexts are restored from the tar
6975 file.
6976 "acls"
6978 If set to true, POSIX ACLs are restored from the tar file.
6979 $g->tar_in_opts ($tarfile, $directory [, compress => $compress] [,
6981 xattrs => $xattrs] [, selinux => $selinux] [, acls => $acls]);
6982 This is an alias of "tar_in".
6983 $g->tar_out ($directory, $tarfile [, compress => $compress] [,
6985 numericowner => $numericowner] [, excludes => $excludes] [, xattrs =>
6986 $xattrs] [, selinux => $selinux] [, acls => $acls]);
6987 This command packs the contents of directory and downloads it to
6988 local file "tarfile".
6989 The optional "compress" flag controls compression. If not given,
6991 then the output will be an uncompressed tar file. Otherwise one of
6992 the following strings may be given to select the compression type
6993 of the output file: "compress", "gzip", "bzip2", "xz", "lzop".
6994 (Note that not all builds of libguestfs will support all of these
6995 compression types).
6996 The other optional arguments are:
6998 "excludes"
7000 A list of wildcards. Files are excluded if they match any of
7001 the wildcards.
7002 "numericowner"
7004 If set to true, the output tar file will contain UID/GID
7005 numbers instead of user/group names.
7006 "xattrs"
7008 If set to true, extended attributes are saved in the output
7009 tar.
7010 "selinux"
7012 If set to true, SELinux contexts are saved in the output tar.
7013 "acls"
7015 If set to true, POSIX ACLs are saved in the output tar.
7016 $g->tar_out_opts ($directory, $tarfile [, compress => $compress] [,
7018 numericowner => $numericowner] [, excludes => $excludes] [, xattrs =>
7019 $xattrs] [, selinux => $selinux] [, acls => $acls]);
7020 This is an alias of "tar_out".
7021 $g->tgz_in ($tarball, $directory);
7023 This command uploads and unpacks local file "tarball" (a gzip
7024 compressed tar file) into directory.
7025 This function is deprecated. In new code, use the "tar_in" call
7027 instead.
7028 Deprecated functions will not be removed from the API, but the fact
7030 that they are deprecated indicates that there are problems with
7031 correct use of these functions.
7032 $g->tgz_out ($directory, $tarball);
7034 This command packs the contents of directory and downloads it to
7035 local file "tarball".
7036 This function is deprecated. In new code, use the "tar_out" call
7038 instead.
7039 Deprecated functions will not be removed from the API, but the fact
7041 that they are deprecated indicates that there are problems with
7042 correct use of these functions.
7043 $g->touch ($path);
7045 Touch acts like the touch(1) command. It can be used to update the
7046 timestamps on a file, or, if the file does not exist, to create a
7047 new zero-length file.
7048 This command only works on regular files, and will fail on other
7050 file types such as directories, symbolic links, block special etc.
7051 $g->truncate ($path);
7053 This command truncates "path" to a zero-length file. The file must
7054 exist already.
7055 $g->truncate_size ($path, $size);
7057 This command truncates "path" to size "size" bytes. The file must
7058 exist already.
7059 If the current file size is less than "size" then the file is
7061 extended to the required size with zero bytes. This creates a
7062 sparse file (ie. disk blocks are not allocated for the file until
7063 you write to it). To create a non-sparse file of zeroes, use
7064 "$g->fallocate64" instead.
7065 $g->tune2fs ($device [, force => $force] [, maxmountcount =>
7067 $maxmountcount] [, mountcount => $mountcount] [, errorbehavior =>
7068 $errorbehavior] [, group => $group] [, intervalbetweenchecks =>
7069 $intervalbetweenchecks] [, reservedblockspercentage =>
7070 $reservedblockspercentage] [, lastmounteddirectory =>
7071 $lastmounteddirectory] [, reservedblockscount => $reservedblockscount]
7072 [, user => $user]);
7073 This call allows you to adjust various filesystem parameters of an
7074 ext2/ext3/ext4 filesystem called "device".
7075 The optional parameters are:
7077 "force"
7079 Force tune2fs to complete the operation even in the face of
7080 errors. This is the same as the tune2fs(8) "-f" option.
7081 "maxmountcount"
7083 Set the number of mounts after which the filesystem is checked
7084 by e2fsck(8). If this is 0 then the number of mounts is
7085 disregarded. This is the same as the tune2fs(8) "-c" option.
7086 "mountcount"
7088 Set the number of times the filesystem has been mounted. This
7089 is the same as the tune2fs(8) "-C" option.
7090 "errorbehavior"
7092 Change the behavior of the kernel code when errors are
7093 detected. Possible values currently are: "continue",
7094 "remount-ro", "panic". In practice these options don't really
7095 make any difference, particularly for write errors.
7096 This is the same as the tune2fs(8) "-e" option.
7098 "group"
7100 Set the group which can use reserved filesystem blocks. This
7101 is the same as the tune2fs(8) "-g" option except that it can
7102 only be specified as a number.
7103 "intervalbetweenchecks"
7105 Adjust the maximal time between two filesystem checks (in
7106 seconds). If the option is passed as 0 then time-dependent
7107 checking is disabled.
7108 This is the same as the tune2fs(8) "-i" option.
7110 "reservedblockspercentage"
7112 Set the percentage of the filesystem which may only be
7113 allocated by privileged processes. This is the same as the
7114 tune2fs(8) "-m" option.
7115 "lastmounteddirectory"
7117 Set the last mounted directory. This is the same as the
7118 tune2fs(8) "-M" option.
7119 "reservedblockscount" Set the number of reserved filesystem blocks.
7121 This is the same as the tune2fs(8) "-r" option.
7122 "user"
7123 Set the user who can use the reserved filesystem blocks. This
7124 is the same as the tune2fs(8) "-u" option except that it can
7125 only be specified as a number.
7126 To get the current values of filesystem parameters, see
7128 "$g->tune2fs_l". For precise details of how tune2fs works, see the
7129 tune2fs(8) man page.
7130 %superblock = $g->tune2fs_l ($device);
7132 This returns the contents of the ext2, ext3 or ext4 filesystem
7133 superblock on "device".
7134 It is the same as running "tune2fs -l device". See tune2fs(8)
7136 manpage for more details. The list of fields returned isn't
7137 clearly defined, and depends on both the version of "tune2fs" that
7138 libguestfs was built against, and the filesystem itself.
7139 $g->txz_in ($tarball, $directory);
7141 This command uploads and unpacks local file "tarball" (an xz
7142 compressed tar file) into directory.
7143 This function depends on the feature "xz". See also
7145 "$g->feature-available".
7146 This function is deprecated. In new code, use the "tar_in" call
7148 instead.
7149 Deprecated functions will not be removed from the API, but the fact
7151 that they are deprecated indicates that there are problems with
7152 correct use of these functions.
7153 $g->txz_out ($directory, $tarball);
7155 This command packs the contents of directory and downloads it to
7156 local file "tarball" (as an xz compressed tar archive).
7157 This function depends on the feature "xz". See also
7159 "$g->feature-available".
7160 This function is deprecated. In new code, use the "tar_out" call
7162 instead.
7163 Deprecated functions will not be removed from the API, but the fact
7165 that they are deprecated indicates that there are problems with
7166 correct use of these functions.
7167 $oldmask = $g->umask ($mask);
7169 This function sets the mask used for creating new files and device
7170 nodes to "mask & 0777".
7171 Typical umask values would be 022 which creates new files with
7173 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which
7174 creates new files with permissions like "-rw-rw-r--" or
7175 "-rwxrwxr-x".
7176 The default umask is 022. This is important because it means that
7178 directories and device nodes will be created with 0644 or 0755 mode
7179 even if you specify 0777.
7180 See also "$g->get_umask", umask(2), "$g->mknod", "$g->mkdir".
7182 This call returns the previous umask.
7184 $g->umount ($pathordevice [, force => $force] [, lazyunmount =>
7186 $lazyunmount]);
7187 This unmounts the given filesystem. The filesystem may be
7188 specified either by its mountpoint (path) or the device which
7189 contains the filesystem.
7190 $g->umount_opts ($pathordevice [, force => $force] [, lazyunmount =>
7192 $lazyunmount]);
7193 This is an alias of "umount".
7194 $g->umount_all ();
7196 This unmounts all mounted filesystems.
7197 Some internal mounts are not unmounted by this call.
7199 $g->umount_local ([retry => $retry]);
7201 If libguestfs is exporting the filesystem on a local mountpoint,
7202 then this unmounts it.
7203 See "MOUNT LOCAL" in guestfs(3) for full documentation.
7205 $g->upload ($filename, $remotefilename);
7207 Upload local file filename to remotefilename on the filesystem.
7208 filename can also be a named pipe.
7210 See also "$g->download".
7212 $g->upload_offset ($filename, $remotefilename, $offset);
7214 Upload local file filename to remotefilename on the filesystem.
7215 remotefilename is overwritten starting at the byte "offset"
7217 specified. The intention is to overwrite parts of existing files
7218 or devices, although if a non-existent file is specified then it is
7219 created with a "hole" before "offset". The size of the data
7220 written is implicit in the size of the source filename.
7221 Note that there is no limit on the amount of data that can be
7223 uploaded with this call, unlike with "$g->pwrite", and this call
7224 always writes the full amount unless an error occurs.
7225 See also "$g->upload", "$g->pwrite".
7227 $g->user_cancel ();
7229 This function cancels the current upload or download operation.
7230 Unlike most other libguestfs calls, this function is signal safe
7232 and thread safe. You can call it from a signal handler or from
7233 another thread, without needing to do any locking.
7234 The transfer that was in progress (if there is one) will stop
7236 shortly afterwards, and will return an error. The errno (see
7237 "guestfs_last_errno") is set to "EINTR", so you can test for this
7238 to find out if the operation was cancelled or failed because of
7239 another error.
7240 No cleanup is performed: for example, if a file was being uploaded
7242 then after cancellation there may be a partially uploaded file. It
7243 is the callerXs responsibility to clean up if necessary.
7244 There are two common places that you might call "$g->user_cancel":
7246 In an interactive text-based program, you might call it from a
7248 "SIGINT" signal handler so that pressing "^C" cancels the current
7249 operation. (You also need to call "$g->set_pgroup" so that child
7250 processes don't receive the "^C" signal).
7251 In a graphical program, when the main thread is displaying a
7253 progress bar with a cancel button, wire up the cancel button to
7254 call this function.
7255 $g->utimens ($path, $atsecs, $atnsecs, $mtsecs, $mtnsecs);
7257 This command sets the timestamps of a file with nanosecond
7258 precision.
7259 "atsecs", "atnsecs" are the last access time (atime) in secs and
7261 nanoseconds from the epoch.
7262 "mtsecs", "mtnsecs" are the last modification time (mtime) in secs
7264 and nanoseconds from the epoch.
7265 If the *nsecs field contains the special value "-1" then the
7267 corresponding timestamp is set to the current time. (The *secs
7268 field is ignored in this case).
7269 If the *nsecs field contains the special value "-2" then the
7271 corresponding timestamp is left unchanged. (The *secs field is
7272 ignored in this case).
7273 %uts = $g->utsname ();
7275 This returns the kernel version of the appliance, where this is
7276 available. This information is only useful for debugging. Nothing
7277 in the returned structure is defined by the API.
7278 %version = $g->version ();
7280 Return the libguestfs version number that the program is linked
7281 against.
7282 Note that because of dynamic linking this is not necessarily the
7284 version of libguestfs that you compiled against. You can compile
7285 the program, and then at runtime dynamically link against a
7286 completely different libguestfs.so library.
7287 This call was added in version 1.0.58. In previous versions of
7289 libguestfs there was no way to get the version number. From C code
7290 you can use dynamic linker functions to find out if this symbol
7291 exists (if it doesn't, then itXs an earlier version).
7292 The call returns a structure with four elements. The first three
7294 ("major", "minor" and "release") are numbers and correspond to the
7295 usual version triplet. The fourth element ("extra") is a string
7296 and is normally empty, but may be used for distro-specific
7297 information.
7298 To construct the original version string:
7300 "$major.$minor.$release$extra"
7301 See also: "LIBGUESTFS VERSION NUMBERS" in guestfs(3).
7303 Note: Don't use this call to test for availability of features. In
7305 enterprise distributions we backport features from later versions
7306 into earlier versions, making this an unreliable way to test for
7307 features. Use "$g->available" or "$g->feature_available" instead.
7308 $label = $g->vfs_label ($mountable);
7310 This returns the label of the filesystem on "mountable".
7311 If the filesystem is unlabeled, this returns the empty string.
7313 To find a filesystem from the label, use "$g->findfs_label".
7315 $sizeinbytes = $g->vfs_minimum_size ($mountable);
7317 Get the minimum size of filesystem in bytes. This is the minimum
7318 possible size for filesystem shrinking.
7319 If getting minimum size of specified filesystem is not supported,
7321 this will fail and set errno as ENOTSUP.
7322 See also ntfsresize(8), resize2fs(8), btrfs(8), xfs_info(8).
7324 $fstype = $g->vfs_type ($mountable);
7326 This command gets the filesystem type corresponding to the
7327 filesystem on "mountable".
7328 For most filesystems, the result is the name of the Linux VFS
7330 module which would be used to mount this filesystem if you mounted
7331 it without specifying the filesystem type. For example a string
7332 such as "ext3" or "ntfs".
7333 $uuid = $g->vfs_uuid ($mountable);
7335 This returns the filesystem UUID of the filesystem on "mountable".
7336 If the filesystem does not have a UUID, this returns the empty
7338 string.
7339 To find a filesystem from the UUID, use "$g->findfs_uuid".
7341 $g->vg_activate ($activate, \@volgroups);
7343 This command activates or (if "activate" is false) deactivates all
7344 logical volumes in the listed volume groups "volgroups".
7345 This command is the same as running "vgchange -a y|n volgroups..."
7347 Note that if "volgroups" is an empty list then all volume groups
7349 are activated or deactivated.
7350 This function depends on the feature "lvm2". See also
7352 "$g->feature-available".
7353 $g->vg_activate_all ($activate);
7355 This command activates or (if "activate" is false) deactivates all
7356 logical volumes in all volume groups.
7357 This command is the same as running "vgchange -a y|n"
7359 This function depends on the feature "lvm2". See also
7361 "$g->feature-available".
7362 $g->vgchange_uuid ($vg);
7364 Generate a new random UUID for the volume group "vg".
7365 This function depends on the feature "lvm2". See also
7367 "$g->feature-available".
7368 $g->vgchange_uuid_all ();
7370 Generate new random UUIDs for all volume groups.
7371 This function depends on the feature "lvm2". See also
7373 "$g->feature-available".
7374 $g->vgcreate ($volgroup, \@physvols);
7376 This creates an LVM volume group called "volgroup" from the non-
7377 empty list of physical volumes "physvols".
7378 This function depends on the feature "lvm2". See also
7380 "$g->feature-available".
7381 @uuids = $g->vglvuuids ($vgname);
7383 Given a VG called "vgname", this returns the UUIDs of all the
7384 logical volumes created in this volume group.
7385 You can use this along with "$g->lvs" and "$g->lvuuid" calls to
7387 associate logical volumes and volume groups.
7388 See also "$g->vgpvuuids".
7390 $metadata = $g->vgmeta ($vgname);
7392 "vgname" is an LVM volume group. This command examines the volume
7393 group and returns its metadata.
7394 Note that the metadata is an internal structure used by LVM,
7396 subject to change at any time, and is provided for information
7397 only.
7398 This function depends on the feature "lvm2". See also
7400 "$g->feature-available".
7401 @uuids = $g->vgpvuuids ($vgname);
7403 Given a VG called "vgname", this returns the UUIDs of all the
7404 physical volumes that this volume group resides on.
7405 You can use this along with "$g->pvs" and "$g->pvuuid" calls to
7407 associate physical volumes and volume groups.
7408 See also "$g->vglvuuids".
7410 $g->vgremove ($vgname);
7412 Remove an LVM volume group "vgname", (for example "VG").
7413 This also forcibly removes all logical volumes in the volume group
7415 (if any).
7416 This function depends on the feature "lvm2". See also
7418 "$g->feature-available".
7419 $g->vgrename ($volgroup, $newvolgroup);
7421 Rename a volume group "volgroup" with the new name "newvolgroup".
7422 @volgroups = $g->vgs ();
7424 List all the volumes groups detected. This is the equivalent of
7425 the vgs(8) command.
7426 This returns a list of just the volume group names that were
7428 detected (eg. "VolGroup00").
7429 See also "$g->vgs_full".
7431 This function depends on the feature "lvm2". See also
7433 "$g->feature-available".
7434 @volgroups = $g->vgs_full ();
7436 List all the volumes groups detected. This is the equivalent of
7437 the vgs(8) command. The "full" version includes all fields.
7438 This function depends on the feature "lvm2". See also
7440 "$g->feature-available".
7441 $g->vgscan ();
7443 This rescans all block devices and rebuilds the list of LVM
7444 physical volumes, volume groups and logical volumes.
7445 This function is deprecated. In new code, use the "lvm_scan" call
7447 instead.
7448 Deprecated functions will not be removed from the API, but the fact
7450 that they are deprecated indicates that there are problems with
7451 correct use of these functions.
7452 $uuid = $g->vguuid ($vgname);
7454 This command returns the UUID of the LVM VG named "vgname".
7455 $g->wait_ready ();
7457 This function is a no op.
7458 In versions of the API < 1.0.71 you had to call this function just
7460 after calling "$g->launch" to wait for the launch to complete.
7461 However this is no longer necessary because "$g->launch" now does
7462 the waiting.
7463 If you see any calls to this function in code then you can just
7465 remove them, unless you want to retain compatibility with older
7466 versions of the API.
7467 This function is deprecated. There is no replacement. Consult the
7469 API documentation in guestfs(3) for further information.
7470 Deprecated functions will not be removed from the API, but the fact
7472 that they are deprecated indicates that there are problems with
7473 correct use of these functions.
7474 $chars = $g->wc_c ($path);
7476 This command counts the characters in a file, using the "wc -c"
7477 external command.
7478 $lines = $g->wc_l ($path);
7480 This command counts the lines in a file, using the "wc -l" external
7481 command.
7482 $words = $g->wc_w ($path);
7484 This command counts the words in a file, using the "wc -w" external
7485 command.
7486 $g->wipefs ($device);
7488 This command erases filesystem or RAID signatures from the
7489 specified "device" to make the filesystem invisible to libblkid.
7490 This does not erase the filesystem itself nor any other data from
7492 the "device".
7493 Compare with "$g->zero" which zeroes the first few blocks of a
7495 device.
7496 This function depends on the feature "wipefs". See also
7498 "$g->feature-available".
7499 $g->write ($path, $content);
7501 This call creates a file called "path". The content of the file is
7502 the string "content" (which can contain any 8 bit data).
7503 See also "$g->write_append".
7505 $g->write_append ($path, $content);
7507 This call appends "content" to the end of file "path". If "path"
7508 does not exist, then a new file is created.
7509 See also "$g->write".
7511 $g->write_file ($path, $content, $size);
7513 This call creates a file called "path". The contents of the file
7514 is the string "content" (which can contain any 8 bit data), with
7515 length "size".
7516 As a special case, if "size" is 0 then the length is calculated
7518 using "strlen" (so in this case the content cannot contain embedded
7519 ASCII NULs).
7520 NB. Owing to a bug, writing content containing ASCII NUL characters
7522 does not work, even if the length is specified.
7523 Because of the message protocol, there is a transfer limit of
7525 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7526 guestfs(3).
7527 This function is deprecated. In new code, use the "write" call
7529 instead.
7530 Deprecated functions will not be removed from the API, but the fact
7532 that they are deprecated indicates that there are problems with
7533 correct use of these functions.
7534 $g->xfs_admin ($device [, extunwritten => $extunwritten] [, imgfile =>
7536 $imgfile] [, v2log => $v2log] [, projid32bit => $projid32bit] [,
7537 lazycounter => $lazycounter] [, label => $label] [, uuid => $uuid]);
7538 Change the parameters of the XFS filesystem on "device".
7539 Devices that are mounted cannot be modified. Administrators must
7541 unmount filesystems before this call can modify parameters.
7542 Some of the parameters of a mounted filesystem can be examined and
7544 modified using the "$g->xfs_info" and "$g->xfs_growfs" calls.
7545 This function depends on the feature "xfs". See also
7547 "$g->feature-available".
7548 $g->xfs_growfs ($path [, datasec => $datasec] [, logsec => $logsec] [,
7550 rtsec => $rtsec] [, datasize => $datasize] [, logsize => $logsize] [,
7551 rtsize => $rtsize] [, rtextsize => $rtextsize] [, maxpct => $maxpct]);
7552 Grow the XFS filesystem mounted at "path".
7553 The returned struct contains geometry information. Missing fields
7555 are returned as "-1" (for numeric fields) or empty string.
7556 This function depends on the feature "xfs". See also
7558 "$g->feature-available".
7559 %info = $g->xfs_info ($pathordevice);
7561 "pathordevice" is a mounted XFS filesystem or a device containing
7562 an XFS filesystem. This command returns the geometry of the
7563 filesystem.
7564 The returned struct contains geometry information. Missing fields
7566 are returned as "-1" (for numeric fields) or empty string.
7567 This function depends on the feature "xfs". See also
7569 "$g->feature-available".
7570 $status = $g->xfs_repair ($device [, forcelogzero => $forcelogzero] [,
7572 nomodify => $nomodify] [, noprefetch => $noprefetch] [, forcegeometry
7573 => $forcegeometry] [, maxmem => $maxmem] [, ihashsize => $ihashsize] [,
7574 bhashsize => $bhashsize] [, agstride => $agstride] [, logdev =>
7575 $logdev] [, rtdev => $rtdev]);
7576 Repair corrupt or damaged XFS filesystem on "device".
7577 The filesystem is specified using the "device" argument which
7579 should be the device name of the disk partition or volume
7580 containing the filesystem. If given the name of a block device,
7581 "xfs_repair" will attempt to find the raw device associated with
7582 the specified block device and will use the raw device instead.
7583 Regardless, the filesystem to be repaired must be unmounted,
7585 otherwise, the resulting filesystem may be inconsistent or corrupt.
7586 The returned status indicates whether filesystem corruption was
7588 detected (returns 1) or was not detected (returns 0).
7589 This function depends on the feature "xfs". See also
7591 "$g->feature-available".
7592 $g->yara_destroy ();
7594 Destroy previously loaded Yara rules in order to free libguestfs
7595 resources.
7596 This function depends on the feature "libyara". See also
7598 "$g->feature-available".
7599 $g->yara_load ($filename);
7601 Upload a set of Yara rules from local file filename.
7602 Yara rules allow to categorize files based on textual or binary
7604 patterns within their content. See "$g->yara_scan" to see how to
7605 scan files with the loaded rules.
7606 Rules can be in binary format, as when compiled with yarac command,
7608 or in source code format. In the latter case, the rules will be
7609 first compiled and then loaded.
7610 Rules in source code format cannot include external files. In such
7612 cases, it is recommended to compile them first.
7613 Previously loaded rules will be destroyed.
7615 This function depends on the feature "libyara". See also
7617 "$g->feature-available".
7618 @detections = $g->yara_scan ($path);
7620 Scan a file with the previously loaded Yara rules.
7621 For each matching rule, a "yara_detection" structure is returned.
7623 The "yara_detection" structure contains the following fields.
7625 "yara_name"
7627 Path of the file matching a Yara rule.
7628 "yara_rule"
7630 Identifier of the Yara rule which matched against the given
7631 file.
7632 This function depends on the feature "libyara". See also
7634 "$g->feature-available".
7635 @lines = $g->zegrep ($regex, $path);
7637 This calls the external "zegrep" program and returns the matching
7638 lines.
7639 Because of the message protocol, there is a transfer limit of
7641 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7642 guestfs(3).
7643 This function is deprecated. In new code, use the "grep" call
7645 instead.
7646 Deprecated functions will not be removed from the API, but the fact
7648 that they are deprecated indicates that there are problems with
7649 correct use of these functions.
7650 @lines = $g->zegrepi ($regex, $path);
7652 This calls the external "zegrep -i" program and returns the
7653 matching lines.
7654 Because of the message protocol, there is a transfer limit of
7656 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7657 guestfs(3).
7658 This function is deprecated. In new code, use the "grep" call
7660 instead.
7661 Deprecated functions will not be removed from the API, but the fact
7663 that they are deprecated indicates that there are problems with
7664 correct use of these functions.
7665 $g->zero ($device);
7667 This command writes zeroes over the first few blocks of "device".
7668 How many blocks are zeroed isn't specified (but itXs not enough to
7670 securely wipe the device). It should be sufficient to remove any
7671 partition tables, filesystem superblocks and so on.
7672 If blocks are already zero, then this command avoids writing
7674 zeroes. This prevents the underlying device from becoming non-
7675 sparse or growing unnecessarily.
7676 See also: "$g->zero_device", "$g->scrub_device",
7678 "$g->is_zero_device"
7679 $g->zero_device ($device);
7681 This command writes zeroes over the entire "device". Compare with
7682 "$g->zero" which just zeroes the first few blocks of a device.
7683 If blocks are already zero, then this command avoids writing
7685 zeroes. This prevents the underlying device from becoming non-
7686 sparse or growing unnecessarily.
7687 $g->zero_free_space ($directory);
7689 Zero the free space in the filesystem mounted on directory. The
7690 filesystem must be mounted read-write.
7691 The filesystem contents are not affected, but any free space in the
7693 filesystem is freed.
7694 Free space is not "trimmed". You may want to call "$g->fstrim"
7696 either as an alternative to this, or after calling this, depending
7697 on your requirements.
7698 $g->zerofree ($device);
7700 This runs the zerofree program on "device". This program claims to
7701 zero unused inodes and disk blocks on an ext2/3 filesystem, thus
7702 making it possible to compress the filesystem more effectively.
7703 You should not run this program if the filesystem is mounted.
7705 It is possible that using this program can damage the filesystem or
7707 data on the filesystem.
7708 This function depends on the feature "zerofree". See also
7710 "$g->feature-available".
7711 @lines = $g->zfgrep ($pattern, $path);
7713 This calls the external "zfgrep" program and returns the matching
7714 lines.
7715 Because of the message protocol, there is a transfer limit of
7717 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7718 guestfs(3).
7719 This function is deprecated. In new code, use the "grep" call
7721 instead.
7722 Deprecated functions will not be removed from the API, but the fact
7724 that they are deprecated indicates that there are problems with
7725 correct use of these functions.
7726 @lines = $g->zfgrepi ($pattern, $path);
7728 This calls the external "zfgrep -i" program and returns the
7729 matching lines.
7730 Because of the message protocol, there is a transfer limit of
7732 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7733 guestfs(3).
7734 This function is deprecated. In new code, use the "grep" call
7736 instead.
7737 Deprecated functions will not be removed from the API, but the fact
7739 that they are deprecated indicates that there are problems with
7740 correct use of these functions.
7741 $description = $g->zfile ($meth, $path);
7743 This command runs file(1) after first decompressing "path" using
7744 "meth".
7745 "meth" must be one of "gzip", "compress" or "bzip2".
7747 Since 1.0.63, use "$g->file" instead which can now process
7749 compressed files.
7750 This function is deprecated. In new code, use the "file" call
7752 instead.
7753 Deprecated functions will not be removed from the API, but the fact
7755 that they are deprecated indicates that there are problems with
7756 correct use of these functions.
7757 @lines = $g->zgrep ($regex, $path);
7759 This calls the external zgrep(1) program and returns the matching
7760 lines.
7761 Because of the message protocol, there is a transfer limit of
7763 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7764 guestfs(3).
7765 This function is deprecated. In new code, use the "grep" call
7767 instead.
7768 Deprecated functions will not be removed from the API, but the fact
7770 that they are deprecated indicates that there are problems with
7771 correct use of these functions.
7772 @lines = $g->zgrepi ($regex, $path);
7774 This calls the external "zgrep -i" program and returns the matching
7775 lines.
7776 Because of the message protocol, there is a transfer limit of
7778 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7779 guestfs(3).
7780 This function is deprecated. In new code, use the "grep" call
7782 instead.
7783 Deprecated functions will not be removed from the API, but the fact
7785 that they are deprecated indicates that there are problems with
7786 correct use of these functions.
7787
7789 From time to time we add new libguestfs APIs. Also some libguestfs
7790 APIs won't be available in all builds of libguestfs (the Fedora build
7791 is full-featured, but other builds may disable features). How do you
7792 test whether the APIs that your Perl program needs are available in the
7793 version of "Sys::Guestfs" that you are using?
7794 To test if a particular function is available in the "Sys::Guestfs"
7796 class, use the ordinary Perl UNIVERSAL method "can(METHOD)" (see
7797 perlobj(1)). For example:
7798 use Sys::Guestfs;
7800 if (defined (Sys::Guestfs->can ("set_verbose"))) {
7801 print "\$g->set_verbose is available\n";
7802 }
7803 To test if particular features are supported by the current build, use
7805 the "feature_available" method like the example below. Note that the
7806 appliance must be launched first.
7807 $g->feature_available ( ["augeas"] );
7809 For further discussion on this topic, refer to "AVAILABILITY" in
7811 guestfs(3).
7812
7814 The handle returned from "new" is a hash reference. The hash normally
7815 contains some elements:
7816 {
7818 _g => [private data used by libguestfs],
7819 _flags => [flags provided when creating the handle]
7820 }
7821 Callers can add other elements to this hash to store data for their own
7823 purposes. The data lasts for the lifetime of the handle.
7824 Any fields whose names begin with an underscore are reserved for
7826 private use by libguestfs. We may add more in future.
7827 It is recommended that callers prefix the name of their field(s) with
7829 some unique string, to avoid conflicts with other users.
7830
7832 Copyright (C) 2009-2020 Red Hat Inc.
7833
7835 Please see the file COPYING.LIB for the full license.
7836
7838 guestfs(3), guestfish(1), <http://libguestfs.org>.
7839perl v5.30.2 2020-04-16 Sys::Guestfs(3)