1Sys::Guestfs(3) User Contributed Perl Documentation Sys::Guestfs(3)
2
6 Sys::Guestfs - Perl bindings for libguestfs
7
9 use Sys::Guestfs;
10 my $g = Sys::Guestfs->new ();
12 $g->add_drive_opts ('guest.img', format => 'raw');
13 $g->launch ();
14 $g->mount ('/dev/sda1', '/');
15 $g->touch ('/hello');
16 $g->shutdown ();
17 $g->close ();
18
20 The "Sys::Guestfs" module provides a Perl XS binding to the libguestfs
21 API for examining and modifying virtual machine disk images.
22 Amongst the things this is good for: making batch configuration changes
24 to guests, getting disk used/free statistics (see also: virt-df),
25 migrating between virtualization systems (see also: virt-p2v),
26 performing partial backups, performing partial guest clones, cloning
27 guests and changing registry/UUID/hostname info, and much else besides.
28 Libguestfs uses Linux kernel and qemu code, and can access any type of
30 guest filesystem that Linux and qemu can, including but not limited to:
31 ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
32 schemes, qcow, qcow2, vmdk.
33 Libguestfs provides ways to enumerate guest storage (eg. partitions,
35 LVs, what filesystem is in each LV, etc.). It can also run commands in
36 the context of the guest. Also you can access filesystems over FUSE.
37
39 All errors turn into calls to "croak" (see Carp(3)).
40 The error string from libguestfs is directly available from $@. Use
42 the "last_errno" method if you want to get the errno.
43
45 $g = Sys::Guestfs->new ([environment => 0,] [close_on_exit => 0]);
46 Create a new guestfs handle.
47 If the optional argument "environment" is false, then the
49 "GUESTFS_CREATE_NO_ENVIRONMENT" flag is set.
50 If the optional argument "close_on_exit" is false, then the
52 "GUESTFS_CREATE_NO_CLOSE_ON_EXIT" flag is set.
53 $g->close ();
55 Explicitly close the guestfs handle.
56 Note: You should not usually call this function. The handle will
58 be closed implicitly when its reference count goes to zero (eg.
59 when it goes out of scope or the program ends). This call is only
60 required in some exceptional cases, such as where the program may
61 contain cached references to the handle 'somewhere' and you really
62 have to have the close happen right away. After calling "close"
63 the program must not call any method (including "close") on the
64 handle (but the implicit call to "DESTROY" that happens when the
65 final reference is cleaned up is OK).
66 $Sys::Guestfs::EVENT_CLOSE
68 See "GUESTFS_EVENT_CLOSE" in guestfs(3).
69 $Sys::Guestfs::EVENT_SUBPROCESS_QUIT
71 See "GUESTFS_EVENT_SUBPROCESS_QUIT" in guestfs(3).
72 $Sys::Guestfs::EVENT_LAUNCH_DONE
74 See "GUESTFS_EVENT_LAUNCH_DONE" in guestfs(3).
75 $Sys::Guestfs::EVENT_PROGRESS
77 See "GUESTFS_EVENT_PROGRESS" in guestfs(3).
78 $Sys::Guestfs::EVENT_APPLIANCE
80 See "GUESTFS_EVENT_APPLIANCE" in guestfs(3).
81 $Sys::Guestfs::EVENT_LIBRARY
83 See "GUESTFS_EVENT_LIBRARY" in guestfs(3).
84 $Sys::Guestfs::EVENT_TRACE
86 See "GUESTFS_EVENT_TRACE" in guestfs(3).
87 $Sys::Guestfs::EVENT_ENTER
89 See "GUESTFS_EVENT_ENTER" in guestfs(3).
90 $Sys::Guestfs::EVENT_LIBVIRT_AUTH
92 See "GUESTFS_EVENT_LIBVIRT_AUTH" in guestfs(3).
93 $Sys::Guestfs::EVENT_WARNING
95 See "GUESTFS_EVENT_WARNING" in guestfs(3).
96 $Sys::Guestfs::EVENT_ALL
98 See "GUESTFS_EVENT_ALL" in guestfs(3).
99 $event_handle = $g->set_event_callback (\&cb, $event_bitmask);
101 Register "cb" as a callback function for all of the events in
102 $event_bitmask (one or more "$Sys::Guestfs::EVENT_*" flags
103 logically or'd together).
104 This function returns an event handle which can be used to delete
106 the callback using "delete_event_callback".
107 The callback function receives 4 parameters:
109 &cb ($event, $event_handle, $buf, $array)
111 $event
113 The event which happened (equal to one of
114 "$Sys::Guestfs::EVENT_*").
115 $event_handle
117 The event handle.
118 $buf
120 For some event types, this is a message buffer (ie. a string).
121 $array
123 For some event types (notably progress events), this is an
124 array of integers.
125 You should carefully read the documentation for
127 "guestfs_set_event_callback" in guestfs(3) before using this
128 function.
129 $g->delete_event_callback ($event_handle);
131 This removes the callback which was previously registered using
132 "set_event_callback".
133 $str = Sys::Guestfs::event_to_string ($events);
135 $events is either a single event or a bitmask of events. This
136 returns a printable string, useful for debugging.
137 Note that this is a class function, not a method.
139 $errnum = $g->last_errno ();
141 This returns the last error number (errno) that happened on the
142 handle $g.
143 If successful, an errno integer not equal to zero is returned.
145 If no error number is available, this returns 0. See
147 "guestfs_last_errno" in guestfs(3) for more details of why this can
148 happen.
149 You can use the standard Perl module Errno(3) to compare the
151 numeric error returned from this call with symbolic errnos:
152 $g->mkdir ("/foo");
154 if ($g->last_errno() == Errno::EEXIST()) {
155 # mkdir failed because the directory exists already.
156 }
157 $g->acl_delete_def_file ($dir);
159 This function deletes the default POSIX Access Control List (ACL)
160 attached to directory "dir".
161 This function depends on the feature "acl". See also
163 "$g->feature-available".
164 $acl = $g->acl_get_file ($path, $acltype);
166 This function returns the POSIX Access Control List (ACL) attached
167 to "path". The ACL is returned in "long text form" (see acl(5)).
168 The "acltype" parameter may be:
170 "access"
172 Return the ordinary (access) ACL for any file, directory or
173 other filesystem object.
174 "default"
176 Return the default ACL. Normally this only makes sense if
177 "path" is a directory.
178 This function depends on the feature "acl". See also
180 "$g->feature-available".
181 $g->acl_set_file ($path, $acltype, $acl);
183 This function sets the POSIX Access Control List (ACL) attached to
184 "path".
185 The "acltype" parameter may be:
187 "access"
189 Set the ordinary (access) ACL for any file, directory or other
190 filesystem object.
191 "default"
193 Set the default ACL. Normally this only makes sense if "path"
194 is a directory.
195 The "acl" parameter is the new ACL in either "long text form" or
197 "short text form" (see acl(5)). The new ACL completely replaces
198 any previous ACL on the file. The ACL must contain the full Unix
199 permissions (eg. "u::rwx,g::rx,o::rx").
200 If you are specifying individual users or groups, then the mask
202 field is also required (eg. "m::rwx"), followed by the "u:ID:..."
203 and/or "g:ID:..." field(s). A full ACL string might therefore look
204 like this:
205 u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx
207 \ Unix permissions / \mask/ \ ACL /
208 You should use numeric UIDs and GIDs. To map usernames and
210 groupnames to the correct numeric ID in the context of the guest,
211 use the Augeas functions (see "$g->aug_init").
212 This function depends on the feature "acl". See also
214 "$g->feature-available".
215 $g->add_cdrom ($filename);
217 This function adds a virtual CD-ROM disk image to the guest.
218 The image is added as read-only drive, so this function is
220 equivalent of "$g->add_drive_ro".
221 This function is deprecated. In new code, use the "add_drive_ro"
223 call instead.
224 Deprecated functions will not be removed from the API, but the fact
226 that they are deprecated indicates that there are problems with
227 correct use of these functions.
228 $nrdisks = $g->add_domain ($dom [, libvirturi => $libvirturi] [,
230 readonly => $readonly] [, iface => $iface] [, live => $live] [,
231 allowuuid => $allowuuid] [, readonlydisk => $readonlydisk] [, cachemode
232 => $cachemode] [, discard => $discard] [, copyonread => $copyonread]);
233 This function adds the disk(s) attached to the named libvirt domain
234 "dom". It works by connecting to libvirt, requesting the domain
235 and domain XML from libvirt, parsing it for disks, and calling
236 "$g->add_drive_opts" on each one.
237 The number of disks added is returned. This operation is atomic:
239 if an error is returned, then no disks are added.
240 This function does some minimal checks to make sure the libvirt
242 domain is not running (unless "readonly" is true). In a future
243 version we will try to acquire the libvirt lock on each disk.
244 Disks must be accessible locally. This often means that adding
246 disks from a remote libvirt connection (see
247 <http://libvirt.org/remote.html>) will fail unless those disks are
248 accessible via the same device path locally too.
249 The optional "libvirturi" parameter sets the libvirt URI (see
251 <http://libvirt.org/uri.html>). If this is not set then we connect
252 to the default libvirt URI (or one set through an environment
253 variable, see the libvirt documentation for full details).
254 The optional "live" flag controls whether this call will try to
256 connect to a running virtual machine "guestfsd" process if it sees
257 a suitable <channel> element in the libvirt XML definition. The
258 default (if the flag is omitted) is never to try. See "ATTACHING
259 TO RUNNING DAEMONS" in guestfs(3) for more information.
260 If the "allowuuid" flag is true (default is false) then a UUID may
262 be passed instead of the domain name. The "dom" string is treated
263 as a UUID first and looked up, and if that lookup fails then we
264 treat "dom" as a name as usual.
265 The optional "readonlydisk" parameter controls what we do for disks
267 which are marked <readonly/> in the libvirt XML. Possible values
268 are:
269 readonlydisk = "error"
271 If "readonly" is false:
272 The whole call is aborted with an error if any disk with the
274 <readonly/> flag is found.
275 If "readonly" is true:
277 Disks with the <readonly/> flag are added read-only.
279 readonlydisk = "read"
281 If "readonly" is false:
282 Disks with the <readonly/> flag are added read-only. Other
284 disks are added read/write.
285 If "readonly" is true:
287 Disks with the <readonly/> flag are added read-only.
289 readonlydisk = "write" (default)
291 If "readonly" is false:
292 Disks with the <readonly/> flag are added read/write.
294 If "readonly" is true:
296 Disks with the <readonly/> flag are added read-only.
298 readonlydisk = "ignore"
300 If "readonly" is true or false:
301 Disks with the <readonly/> flag are skipped.
303 The other optional parameters are passed directly through to
305 "$g->add_drive_opts".
306 $g->add_drive ($filename [, readonly => $readonly] [, format =>
308 $format] [, iface => $iface] [, name => $name] [, label => $label] [,
309 protocol => $protocol] [, server => $server] [, username => $username]
310 [, secret => $secret] [, cachemode => $cachemode] [, discard =>
311 $discard] [, copyonread => $copyonread]);
312 This function adds a disk image called filename to the handle.
313 filename may be a regular host file or a host device.
314 When this function is called before "$g->launch" (the usual case)
316 then the first time you call this function, the disk appears in the
317 API as /dev/sda, the second time as /dev/sdb, and so on.
318 In libguestfs X 1.20 you can also call this function after launch
320 (with some restrictions). This is called "hotplugging". When
321 hotplugging, you must specify a "label" so that the new disk gets a
322 predictable name. For more information see "HOTPLUGGING" in
323 guestfs(3).
324 You don't necessarily need to be root when using libguestfs.
326 However you obviously do need sufficient permissions to access the
327 filename for whatever operations you want to perform (ie. read
328 access if you just want to read the image or write access if you
329 want to modify the image).
330 This call checks that filename exists.
332 filename may be the special string "/dev/null". See "NULL DISKS"
334 in guestfs(3).
335 The optional arguments are:
337 "readonly"
339 If true then the image is treated as read-only. Writes are
340 still allowed, but they are stored in a temporary snapshot
341 overlay which is discarded at the end. The disk that you add
342 is not modified.
343 "format"
345 This forces the image format. If you omit this (or use
346 "$g->add_drive" or "$g->add_drive_ro") then the format is
347 automatically detected. Possible formats include "raw" and
348 "qcow2".
349 Automatic detection of the format opens you up to a potential
351 security hole when dealing with untrusted raw-format images.
352 See CVE-2010-3851 and RHBZ#642934. Specifying the format
353 closes this security hole.
354 "iface"
356 This rarely-used option lets you emulate the behaviour of the
357 deprecated "$g->add_drive_with_if" call (q.v.)
358 "name"
360 The name the drive had in the original guest, e.g. /dev/sdb.
361 This is used as a hint to the guest inspection process if it is
362 available.
363 "label"
365 Give the disk a label. The label should be a unique, short
366 string using only ASCII characters "[a-zA-Z]". As well as its
367 usual name in the API (such as /dev/sda), the drive will also
368 be named /dev/disk/guestfs/label.
369 See "DISK LABELS" in guestfs(3).
371 "protocol"
373 The optional protocol argument can be used to select an
374 alternate source protocol.
375 See also: "REMOTE STORAGE" in guestfs(3).
377 "protocol = "file""
379 filename is interpreted as a local file or device. This is
380 the default if the optional protocol parameter is omitted.
381 "protocol = "nbd""
383 Connect to the Network Block Device server. The "server"
384 parameter must also be supplied - see below.
385 See also: "NETWORK BLOCK DEVICE" in guestfs(3).
387 "protocol = "rbd""
389 Connect to the Ceph (librbd/RBD) server. The "server"
390 parameter must also be supplied - see below. The
391 "username" parameter may be supplied. See below. The
392 "secret" parameter may be supplied. See below.
393 See also: "CEPH" in guestfs(3).
395 "server"
397 For protocols which require access to a remote server, this is
398 a list of server(s).
399 Protocol Number of servers required
401 -------- --------------------------
402 file List must be empty or param not used at all
403 nbd Exactly one
404 rbd Zero or more
405 Each list element is a string specifying a server. The string
407 must be in one of the following formats:
408 hostname
410 hostname:port
411 tcp:hostname
412 tcp:hostname:port
413 unix:/path/to/socket
414 If the port number is omitted, then the standard port number
416 for the protocol is used (see /etc/services).
417 "username"
419 For the "rbd" protocol, this specifies the remote username.
420 If not given, then no authentication is attempted for ceph.
422 But note this sometimes may give unexpected results, for
423 example if using the libvirt backend and if the libvirt backend
424 is configured to start the qemu appliance as a special user
425 such as "qemu.qemu". If in doubt, specify the remote username
426 you want.
427 "secret"
429 For the "rbd" protocol only, this specifies the XsecretX to use
430 when connecting to the remote device. It must be base64
431 encoded.
432 If not given, then a secret matching the given username will be
434 looked up in the default keychain locations, or if no username
435 is given, then no authentication will be used.
436 "cachemode"
438 Choose whether or not libguestfs will obey sync operations
439 (safe but slow) or not (unsafe but fast). The possible values
440 for this string are:
441 "cachemode = "writeback""
443 This is the default.
444 Write operations in the API do not return until a write(2)
446 call has completed in the host [but note this does not
447 imply that anything gets written to disk].
448 Sync operations in the API, including implicit syncs caused
450 by filesystem journalling, will not return until an
451 fdatasync(2) call has completed in the host, indicating
452 that data has been committed to disk.
453 "cachemode = "unsafe""
455 In this mode, there are no guarantees. Libguestfs may
456 cache anything and ignore sync requests. This is suitable
457 only for scratch or temporary disks.
458 "discard"
460 Enable or disable discard (a.k.a. trim or unmap) support on
461 this drive. If enabled, operations such as "$g->fstrim" will
462 be able to discard / make thin / punch holes in the underlying
463 host file or device.
464 Possible discard settings are:
466 "discard = "disable""
468 Disable discard support. This is the default.
469 "discard = "enable""
471 Enable discard support. Fail if discard is not possible.
472 "discard = "besteffort""
474 Enable discard support if possible, but don't fail if it is
475 not supported.
476 Since not all backends and not all underlying systems
478 support discard, this is a good choice if you want to use
479 discard if possible, but don't mind if it doesn't work.
480 "copyonread"
482 The boolean parameter "copyonread" enables copy-on-read
483 support. This only affects disk formats which have backing
484 files, and causes reads to be stored in the overlay layer,
485 speeding up multiple reads of the same area of disk.
486 The default is false.
488 $g->add_drive_opts ($filename [, readonly => $readonly] [, format =>
490 $format] [, iface => $iface] [, name => $name] [, label => $label] [,
491 protocol => $protocol] [, server => $server] [, username => $username]
492 [, secret => $secret] [, cachemode => $cachemode] [, discard =>
493 $discard] [, copyonread => $copyonread]);
494 This is an alias of "add_drive".
495 $g->add_drive_ro ($filename);
497 This function is the equivalent of calling "$g->add_drive_opts"
498 with the optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set
499 to 1, so the disk is added read-only, with the format being
500 detected automatically.
501 $g->add_drive_ro_with_if ($filename, $iface);
503 This is the same as "$g->add_drive_ro" but it allows you to specify
504 the QEMU interface emulation to use at run time.
505 This function is deprecated. In new code, use the "add_drive" call
507 instead.
508 Deprecated functions will not be removed from the API, but the fact
510 that they are deprecated indicates that there are problems with
511 correct use of these functions.
512 $g->add_drive_scratch ($size [, name => $name] [, label => $label]);
514 This command adds a temporary scratch drive to the handle. The
515 "size" parameter is the virtual size (in bytes). The scratch drive
516 is blank initially (all reads return zeroes until you start writing
517 to it). The drive is deleted when the handle is closed.
518 The optional arguments "name" and "label" are passed through to
520 "$g->add_drive".
521 $g->add_drive_with_if ($filename, $iface);
523 This is the same as "$g->add_drive" but it allows you to specify
524 the QEMU interface emulation to use at run time.
525 This function is deprecated. In new code, use the "add_drive" call
527 instead.
528 Deprecated functions will not be removed from the API, but the fact
530 that they are deprecated indicates that there are problems with
531 correct use of these functions.
532 $nrdisks = $g->add_libvirt_dom ($dom [, readonly => $readonly] [, iface
534 => $iface] [, live => $live] [, readonlydisk => $readonlydisk] [,
535 cachemode => $cachemode] [, discard => $discard] [, copyonread =>
536 $copyonread]);
537 This function adds the disk(s) attached to the libvirt domain
538 "dom". It works by requesting the domain XML from libvirt, parsing
539 it for disks, and calling "$g->add_drive_opts" on each one.
540 In the C API we declare "void *dom", but really it has type
542 "virDomainPtr dom". This is so we don't need <libvirt.h>.
543 The number of disks added is returned. This operation is atomic:
545 if an error is returned, then no disks are added.
546 This function does some minimal checks to make sure the libvirt
548 domain is not running (unless "readonly" is true). In a future
549 version we will try to acquire the libvirt lock on each disk.
550 Disks must be accessible locally. This often means that adding
552 disks from a remote libvirt connection (see
553 <http://libvirt.org/remote.html>) will fail unless those disks are
554 accessible via the same device path locally too.
555 The optional "live" flag controls whether this call will try to
557 connect to a running virtual machine "guestfsd" process if it sees
558 a suitable <channel> element in the libvirt XML definition. The
559 default (if the flag is omitted) is never to try. See "ATTACHING
560 TO RUNNING DAEMONS" in guestfs(3) for more information.
561 The optional "readonlydisk" parameter controls what we do for disks
563 which are marked <readonly/> in the libvirt XML. See
564 "$g->add_domain" for possible values.
565 The other optional parameters are passed directly through to
567 "$g->add_drive_opts".
568 $g->aug_clear ($augpath);
570 Set the value associated with "path" to "NULL". This is the same
571 as the augtool(1) "clear" command.
572 $g->aug_close ();
574 Close the current Augeas handle and free up any resources used by
575 it. After calling this, you have to call "$g->aug_init" again
576 before you can use any other Augeas functions.
577 %nrnodescreated = $g->aug_defnode ($name, $expr, $val);
579 Defines a variable "name" whose value is the result of evaluating
580 "expr".
581 If "expr" evaluates to an empty nodeset, a node is created,
583 equivalent to calling "$g->aug_set" "expr", "value". "name" will
584 be the nodeset containing that single node.
585 On success this returns a pair containing the number of nodes in
587 the nodeset, and a boolean flag if a node was created.
588 $nrnodes = $g->aug_defvar ($name, $expr);
590 Defines an Augeas variable "name" whose value is the result of
591 evaluating "expr". If "expr" is NULL, then "name" is undefined.
592 On success this returns the number of nodes in "expr", or 0 if
594 "expr" evaluates to something which is not a nodeset.
595 $val = $g->aug_get ($augpath);
597 Look up the value associated with "path". If "path" matches
598 exactly one node, the "value" is returned.
599 $g->aug_init ($root, $flags);
601 Create a new Augeas handle for editing configuration files. If
602 there was any previous Augeas handle associated with this guestfs
603 session, then it is closed.
604 You must call this before using any other "$g->aug_*" commands.
606 "root" is the filesystem root. "root" must not be NULL, use /
608 instead.
609 The flags are the same as the flags defined in <augeas.h>, the
611 logical or of the following integers:
612 "AUG_SAVE_BACKUP" = 1
614 Keep the original file with a ".augsave" extension.
615 "AUG_SAVE_NEWFILE" = 2
617 Save changes into a file with extension ".augnew", and do not
618 overwrite original. Overrides "AUG_SAVE_BACKUP".
619 "AUG_TYPE_CHECK" = 4
621 Typecheck lenses.
622 This option is only useful when debugging Augeas lenses. Use
624 of this option may require additional memory for the libguestfs
625 appliance. You may need to set the "LIBGUESTFS_MEMSIZE"
626 environment variable or call "$g->set_memsize".
627 "AUG_NO_STDINC" = 8
629 Do not use standard load path for modules.
630 "AUG_SAVE_NOOP" = 16
632 Make save a no-op, just record what would have been changed.
633 "AUG_NO_LOAD" = 32
635 Do not load the tree in "$g->aug_init".
636 To close the handle, you can call "$g->aug_close".
638 To find out more about Augeas, see <http://augeas.net/>.
640 $g->aug_insert ($augpath, $label, $before);
642 Create a new sibling "label" for "path", inserting it into the tree
643 before or after "path" (depending on the boolean flag "before").
644 "path" must match exactly one existing node in the tree, and
646 "label" must be a label, ie. not contain /, "*" or end with a
647 bracketed index "[N]".
648 $label = $g->aug_label ($augpath);
650 The label (name of the last element) of the Augeas path expression
651 "augpath" is returned. "augpath" must match exactly one node, else
652 this function returns an error.
653 $g->aug_load ();
655 Load files into the tree.
656 See "aug_load" in the Augeas documentation for the full gory
658 details.
659 @matches = $g->aug_ls ($augpath);
661 This is just a shortcut for listing "$g->aug_match" "path/*" and
662 sorting the resulting nodes into alphabetical order.
663 @matches = $g->aug_match ($augpath);
665 Returns a list of paths which match the path expression "path".
666 The returned paths are sufficiently qualified so that they match
667 exactly one node in the current tree.
668 $g->aug_mv ($src, $dest);
670 Move the node "src" to "dest". "src" must match exactly one node.
671 "dest" is overwritten if it exists.
672 $nrnodes = $g->aug_rm ($augpath);
674 Remove "path" and all of its children.
675 On success this returns the number of entries which were removed.
677 $g->aug_save ();
679 This writes all pending changes to disk.
680 The flags which were passed to "$g->aug_init" affect exactly how
682 files are saved.
683 $g->aug_set ($augpath, $val);
685 Set the value associated with "path" to "val".
686 In the Augeas API, it is possible to clear a node by setting the
688 value to NULL. Due to an oversight in the libguestfs API you
689 cannot do that with this call. Instead you must use the
690 "$g->aug_clear" call.
691 $nodes = $g->aug_setm ($base, $sub, $val);
693 Change multiple Augeas nodes in a single operation. "base" is an
694 expression matching multiple nodes. "sub" is a path expression
695 relative to "base". All nodes matching "base" are found, and then
696 for each node, "sub" is changed to "val". "sub" may also be "NULL"
697 in which case the "base" nodes are modified.
698 This returns the number of nodes modified.
700 $g->aug_transform ($lens, $file [, remove => $remove]);
702 Add an Augeas transformation for the specified "lens" so it can
703 handle "file".
704 If "remove" is true ("false" by default), then the transformation
706 is removed.
707 $g->available (\@groups);
709 This command is used to check the availability of some groups of
710 functionality in the appliance, which not all builds of the
711 libguestfs appliance will be able to provide.
712 The libguestfs groups, and the functions that those groups
714 correspond to, are listed in "AVAILABILITY" in guestfs(3). You can
715 also fetch this list at runtime by calling
716 "$g->available_all_groups".
717 The argument "groups" is a list of group names, eg: "["inotify",
719 "augeas"]" would check for the availability of the Linux inotify
720 functions and Augeas (configuration file editing) functions.
721 The command returns no error if all requested groups are available.
723 It fails with an error if one or more of the requested groups is
725 unavailable in the appliance.
726 If an unknown group name is included in the list of groups then an
728 error is always returned.
729 Notes:
731 · "$g->feature_available" is the same as this call, but with a
733 slightly simpler to use API: that call returns a boolean
734 true/false instead of throwing an error.
735 · You must call "$g->launch" before calling this function.
737 The reason is because we don't know what groups are supported
739 by the appliance/daemon until it is running and can be queried.
740 · If a group of functions is available, this does not necessarily
742 mean that they will work. You still have to check for errors
743 when calling individual API functions even if they are
744 available.
745 · It is usually the job of distro packagers to build complete
747 functionality into the libguestfs appliance. Upstream
748 libguestfs, if built from source with all requirements
749 satisfied, will support everything.
750 · This call was added in version 1.0.80. In previous versions of
752 libguestfs all you could do would be to speculatively execute a
753 command to find out if the daemon implemented it. See also
754 "$g->version".
755 See also "$g->filesystem_available".
757 @groups = $g->available_all_groups ();
759 This command returns a list of all optional groups that this daemon
760 knows about. Note this returns both supported and unsupported
761 groups. To find out which ones the daemon can actually support you
762 have to call "$g->available" / "$g->feature_available" on each
763 member of the returned list.
764 See also "$g->available", "$g->feature_available" and
766 "AVAILABILITY" in guestfs(3).
767 $g->base64_in ($base64file, $filename);
769 This command uploads base64-encoded data from "base64file" to
770 filename.
771 $g->base64_out ($filename, $base64file);
773 This command downloads the contents of filename, writing it out to
774 local file "base64file" encoded as base64.
775 $g->blkdiscard ($device);
777 This discards all blocks on the block device "device", giving the
778 free space back to the host.
779 This operation requires support in libguestfs, the host filesystem,
781 qemu and the host kernel. If this support isn't present it may
782 give an error or even appear to run but do nothing. You must also
783 set the "discard" attribute on the underlying drive (see
784 "$g->add_drive_opts").
785 This function depends on the feature "blkdiscard". See also
787 "$g->feature-available".
788 $zeroes = $g->blkdiscardzeroes ($device);
790 This call returns true if blocks on "device" that have been
791 discarded by a call to "$g->blkdiscard" are returned as blocks of
792 zero bytes when read the next time.
793 If it returns false, then it may be that discarded blocks are read
795 as stale or random data.
796 This function depends on the feature "blkdiscardzeroes". See also
798 "$g->feature-available".
799 %info = $g->blkid ($device);
801 This command returns block device attributes for "device". The
802 following fields are usually present in the returned hash. Other
803 fields may also be present.
804 "UUID"
806 The uuid of this device.
807 "LABEL"
809 The label of this device.
810 "VERSION"
812 The version of blkid command.
813 "TYPE"
815 The filesystem type or RAID of this device.
816 "USAGE"
818 The usage of this device, for example "filesystem" or "raid".
819 $g->blockdev_flushbufs ($device);
821 This tells the kernel to flush internal buffers associated with
822 "device".
823 This uses the blockdev(8) command.
825 $blocksize = $g->blockdev_getbsz ($device);
827 This returns the block size of a device.
828 Note: this is different from both size in blocks and filesystem
830 block size. Also this setting is not really used by anything. You
831 should probably not use it for anything. Filesystems have their
832 own idea about what block size to choose.
833 This uses the blockdev(8) command.
835 $ro = $g->blockdev_getro ($device);
837 Returns a boolean indicating if the block device is read-only (true
838 if read-only, false if not).
839 This uses the blockdev(8) command.
841 $sizeinbytes = $g->blockdev_getsize64 ($device);
843 This returns the size of the device in bytes.
844 See also "$g->blockdev_getsz".
846 This uses the blockdev(8) command.
848 $sectorsize = $g->blockdev_getss ($device);
850 This returns the size of sectors on a block device. Usually 512,
851 but can be larger for modern devices.
852 (Note, this is not the size in sectors, use "$g->blockdev_getsz"
854 for that).
855 This uses the blockdev(8) command.
857 $sizeinsectors = $g->blockdev_getsz ($device);
859 This returns the size of the device in units of 512-byte sectors
860 (even if the sectorsize isn't 512 bytes ... weird).
861 See also "$g->blockdev_getss" for the real sector size of the
863 device, and "$g->blockdev_getsize64" for the more useful size in
864 bytes.
865 This uses the blockdev(8) command.
867 $g->blockdev_rereadpt ($device);
869 Reread the partition table on "device".
870 This uses the blockdev(8) command.
872 $g->blockdev_setbsz ($device, $blocksize);
874 This call does nothing and has never done anything because of a bug
875 in blockdev. Do not use it.
876 If you need to set the filesystem block size, use the "blocksize"
878 option of "$g->mkfs".
879 This function is deprecated. There is no replacement. Consult the
881 API documentation in guestfs(3) for further information.
882 Deprecated functions will not be removed from the API, but the fact
884 that they are deprecated indicates that there are problems with
885 correct use of these functions.
886 $g->blockdev_setra ($device, $sectors);
888 Set readahead (in 512-byte sectors) for the device.
889 This uses the blockdev(8) command.
891 $g->blockdev_setro ($device);
893 Sets the block device named "device" to read-only.
894 This uses the blockdev(8) command.
896 $g->blockdev_setrw ($device);
898 Sets the block device named "device" to read-write.
899 This uses the blockdev(8) command.
901 $g->btrfs_balance_cancel ($path);
903 Cancel a running balance on a btrfs filesystem.
904 This function depends on the feature "btrfs". See also
906 "$g->feature-available".
907 $g->btrfs_balance_pause ($path);
909 Pause a running balance on a btrfs filesystem.
910 This function depends on the feature "btrfs". See also
912 "$g->feature-available".
913 $g->btrfs_balance_resume ($path);
915 Resume a paused balance on a btrfs filesystem.
916 This function depends on the feature "btrfs". See also
918 "$g->feature-available".
919 %status = $g->btrfs_balance_status ($path);
921 Show the status of a running or paused balance on a btrfs
922 filesystem.
923 This function depends on the feature "btrfs". See also
925 "$g->feature-available".
926 $g->btrfs_device_add (\@devices, $fs);
928 Add the list of device(s) in "devices" to the btrfs filesystem
929 mounted at "fs". If "devices" is an empty list, this does nothing.
930 This function depends on the feature "btrfs". See also
932 "$g->feature-available".
933 $g->btrfs_device_delete (\@devices, $fs);
935 Remove the "devices" from the btrfs filesystem mounted at "fs". If
936 "devices" is an empty list, this does nothing.
937 This function depends on the feature "btrfs". See also
939 "$g->feature-available".
940 $g->btrfs_filesystem_balance ($fs);
942 Balance the chunks in the btrfs filesystem mounted at "fs" across
943 the underlying devices.
944 This function depends on the feature "btrfs". See also
946 "$g->feature-available".
947 $g->btrfs_filesystem_defragment ($path [, flush => $flush] [, compress
949 => $compress]);
950 Defragment a file or directory on a btrfs filesystem. compress is
951 one of zlib or lzo.
952 This function depends on the feature "btrfs". See also
954 "$g->feature-available".
955 $g->btrfs_filesystem_resize ($mountpoint [, size => $size]);
957 This command resizes a btrfs filesystem.
958 Note that unlike other resize calls, the filesystem has to be
960 mounted and the parameter is the mountpoint not the device (this is
961 a requirement of btrfs itself).
962 The optional parameters are:
964 "size"
966 The new size (in bytes) of the filesystem. If omitted, the
967 filesystem is resized to the maximum size.
968 See also btrfs(8).
970 This function depends on the feature "btrfs". See also
972 "$g->feature-available".
973 @devices = $g->btrfs_filesystem_show ($device);
975 Show all the devices where the filesystems in "device" is spanned
976 over.
977 If not all the devices for the filesystems are present, then this
979 function fails and the "errno" is set to "ENODEV".
980 This function depends on the feature "btrfs". See also
982 "$g->feature-available".
983 $g->btrfs_filesystem_sync ($fs);
985 Force sync on the btrfs filesystem mounted at "fs".
986 This function depends on the feature "btrfs". See also
988 "$g->feature-available".
989 $g->btrfs_fsck ($device [, superblock => $superblock] [, repair =>
991 $repair]);
992 Used to check a btrfs filesystem, "device" is the device file where
993 the filesystem is stored.
994 This function depends on the feature "btrfs". See also
996 "$g->feature-available".
997 $g->btrfs_image (\@source, $image [, compresslevel => $compresslevel]);
999 This is used to create an image of a btrfs filesystem. All data
1000 will be zeroed, but metadata and the like is preserved.
1001 This function depends on the feature "btrfs". See also
1003 "$g->feature-available".
1004 $g->btrfs_qgroup_assign ($src, $dst, $path);
1006 Add qgroup "src" to parent qgroup "dst". This command can group
1007 several qgroups into a parent qgroup to share common limit.
1008 This function depends on the feature "btrfs". See also
1010 "$g->feature-available".
1011 $g->btrfs_qgroup_create ($qgroupid, $subvolume);
1013 Create a quota group (qgroup) for subvolume at "subvolume".
1014 This function depends on the feature "btrfs". See also
1016 "$g->feature-available".
1017 $g->btrfs_qgroup_destroy ($qgroupid, $subvolume);
1019 Destroy a quota group.
1020 This function depends on the feature "btrfs". See also
1022 "$g->feature-available".
1023 $g->btrfs_qgroup_limit ($subvolume, $size);
1025 Limit the size of the subvolume with path "subvolume".
1026 This function depends on the feature "btrfs". See also
1028 "$g->feature-available".
1029 $g->btrfs_qgroup_remove ($src, $dst, $path);
1031 Remove qgroup "src" from the parent qgroup "dst".
1032 This function depends on the feature "btrfs". See also
1034 "$g->feature-available".
1035 @qgroups = $g->btrfs_qgroup_show ($path);
1037 Show all subvolume quota groups in a btrfs filesystem, including
1038 their usages.
1039 This function depends on the feature "btrfs". See also
1041 "$g->feature-available".
1042 $g->btrfs_quota_enable ($fs, $enable);
1044 Enable or disable subvolume quota support for filesystem which
1045 contains "path".
1046 This function depends on the feature "btrfs". See also
1048 "$g->feature-available".
1049 $g->btrfs_quota_rescan ($fs);
1051 Trash all qgroup numbers and scan the metadata again with the
1052 current config.
1053 This function depends on the feature "btrfs". See also
1055 "$g->feature-available".
1056 $g->btrfs_replace ($srcdev, $targetdev, $mntpoint);
1058 Replace device of a btrfs filesystem. On a live filesystem,
1059 duplicate the data to the target device which is currently stored
1060 on the source device. After completion of the operation, the
1061 source device is wiped out and removed from the filesystem.
1062 The "targetdev" needs to be same size or larger than the "srcdev".
1064 Devices which are currently mounted are never allowed to be used as
1065 the "targetdev".
1066 This function depends on the feature "btrfs". See also
1068 "$g->feature-available".
1069 $g->btrfs_rescue_chunk_recover ($device);
1071 Recover the chunk tree of btrfs filesystem by scanning the devices
1072 one by one.
1073 This function depends on the feature "btrfs". See also
1075 "$g->feature-available".
1076 $g->btrfs_rescue_super_recover ($device);
1078 Recover bad superblocks from good copies.
1079 This function depends on the feature "btrfs". See also
1081 "$g->feature-available".
1082 $g->btrfs_scrub_cancel ($path);
1084 Cancel a running scrub on a btrfs filesystem.
1085 This function depends on the feature "btrfs". See also
1087 "$g->feature-available".
1088 $g->btrfs_scrub_resume ($path);
1090 Resume a previously canceled or interrupted scrub on a btrfs
1091 filesystem.
1092 This function depends on the feature "btrfs". See also
1094 "$g->feature-available".
1095 $g->btrfs_scrub_start ($path);
1097 Reads all the data and metadata on the filesystem, and uses
1098 checksums and the duplicate copies from RAID storage to identify
1099 and repair any corrupt data.
1100 This function depends on the feature "btrfs". See also
1102 "$g->feature-available".
1103 %status = $g->btrfs_scrub_status ($path);
1105 Show status of running or finished scrub on a btrfs filesystem.
1106 This function depends on the feature "btrfs". See also
1108 "$g->feature-available".
1109 $g->btrfs_set_seeding ($device, $seeding);
1111 Enable or disable the seeding feature of a device that contains a
1112 btrfs filesystem.
1113 This function depends on the feature "btrfs". See also
1115 "$g->feature-available".
1116 $g->btrfs_subvolume_create ($dest [, qgroupid => $qgroupid]);
1118 Create a btrfs subvolume. The "dest" argument is the destination
1119 directory and the name of the subvolume, in the form
1120 /path/to/dest/name. The optional parameter "qgroupid" represents
1121 the qgroup which the newly created subvolume will be added to.
1122 This function depends on the feature "btrfs". See also
1124 "$g->feature-available".
1125 $g->btrfs_subvolume_create_opts ($dest [, qgroupid => $qgroupid]);
1127 This is an alias of "btrfs_subvolume_create".
1128 $g->btrfs_subvolume_delete ($subvolume);
1130 Delete the named btrfs subvolume or snapshot.
1131 This function depends on the feature "btrfs". See also
1133 "$g->feature-available".
1134 $id = $g->btrfs_subvolume_get_default ($fs);
1136 Get the default subvolume or snapshot of a filesystem mounted at
1137 "mountpoint".
1138 This function depends on the feature "btrfs". See also
1140 "$g->feature-available".
1141 @subvolumes = $g->btrfs_subvolume_list ($fs);
1143 List the btrfs snapshots and subvolumes of the btrfs filesystem
1144 which is mounted at "fs".
1145 This function depends on the feature "btrfs". See also
1147 "$g->feature-available".
1148 $g->btrfs_subvolume_set_default ($id, $fs);
1150 Set the subvolume of the btrfs filesystem "fs" which will be
1151 mounted by default. See "$g->btrfs_subvolume_list" to get a list
1152 of subvolumes.
1153 This function depends on the feature "btrfs". See also
1155 "$g->feature-available".
1156 %btrfssubvolumeinfo = $g->btrfs_subvolume_show ($subvolume);
1158 Return detailed information of the subvolume.
1159 This function depends on the feature "btrfs". See also
1161 "$g->feature-available".
1162 $g->btrfs_subvolume_snapshot ($source, $dest [, ro => $ro] [, qgroupid
1164 => $qgroupid]);
1165 Create a snapshot of the btrfs subvolume "source". The "dest"
1166 argument is the destination directory and the name of the snapshot,
1167 in the form /path/to/dest/name. By default the newly created
1168 snapshot is writable, if the value of optional parameter "ro" is
1169 true, then a readonly snapshot is created. The optional parameter
1170 "qgroupid" represents the qgroup which the newly created snapshot
1171 will be added to.
1172 This function depends on the feature "btrfs". See also
1174 "$g->feature-available".
1175 $g->btrfs_subvolume_snapshot_opts ($source, $dest [, ro => $ro] [,
1177 qgroupid => $qgroupid]);
1178 This is an alias of "btrfs_subvolume_snapshot".
1179 $g->btrfstune_enable_extended_inode_refs ($device);
1181 This will Enable extended inode refs.
1182 This function depends on the feature "btrfs". See also
1184 "$g->feature-available".
1185 $g->btrfstune_enable_skinny_metadata_extent_refs ($device);
1187 This enable skinny metadata extent refs.
1188 This function depends on the feature "btrfs". See also
1190 "$g->feature-available".
1191 $g->btrfstune_seeding ($device, $seeding);
1193 Enable seeding of a btrfs device, this will force a fs readonly so
1194 that you can use it to build other filesystems.
1195 This function depends on the feature "btrfs". See also
1197 "$g->feature-available".
1198 $ptr = $g->c_pointer ();
1200 In non-C language bindings, this allows you to retrieve the
1201 underlying C pointer to the handle (ie. "$g->h *"). The purpose of
1202 this is to allow other libraries to interwork with libguestfs.
1203 $canonical = $g->canonical_device_name ($device);
1205 This utility function is useful when displaying device names to the
1206 user. It takes a number of irregular device names and returns them
1207 in a consistent format:
1208 /dev/hdX
1210 /dev/vdX
1211 These are returned as /dev/sdX. Note this works for device
1212 names and partition names. This is approximately the reverse
1213 of the algorithm described in "BLOCK DEVICE NAMING" in
1214 guestfs(3).
1215 /dev/mapper/VG-LV
1217 /dev/dm-N
1218 Converted to /dev/VG/LV form using "$g->lvm_canonical_lv_name".
1219 Other strings are returned unmodified.
1221 $cap = $g->cap_get_file ($path);
1223 This function returns the Linux capabilities attached to "path".
1224 The capabilities set is returned in text form (see cap_to_text(3)).
1225 If no capabilities are attached to a file, an empty string is
1227 returned.
1228 This function depends on the feature "linuxcaps". See also
1230 "$g->feature-available".
1231 $g->cap_set_file ($path, $cap);
1233 This function sets the Linux capabilities attached to "path". The
1234 capabilities set "cap" should be passed in text form (see
1235 cap_from_text(3)).
1236 This function depends on the feature "linuxcaps". See also
1238 "$g->feature-available".
1239 $rpath = $g->case_sensitive_path ($path);
1241 This can be used to resolve case insensitive paths on a filesystem
1242 which is case sensitive. The use case is to resolve paths which
1243 you have read from Windows configuration files or the Windows
1244 Registry, to the true path.
1245 The command handles a peculiarity of the Linux ntfs-3g filesystem
1247 driver (and probably others), which is that although the underlying
1248 filesystem is case-insensitive, the driver exports the filesystem
1249 to Linux as case-sensitive.
1250 One consequence of this is that special directories such as
1252 C:\windows may appear as /WINDOWS or /windows (or other things)
1253 depending on the precise details of how they were created. In
1254 Windows itself this would not be a problem.
1255 Bug or feature? You decide:
1257 <http://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1>
1258 "$g->case_sensitive_path" attempts to resolve the true case of each
1260 element in the path. It will return a resolved path if either the
1261 full path or its parent directory exists. If the parent directory
1262 exists but the full path does not, the case of the parent directory
1263 will be correctly resolved, and the remainder appended unmodified.
1264 For example, if the file "/Windows/System32/netkvm.sys" exists:
1265 "$g->case_sensitive_path" ("/windows/system32/netkvm.sys")
1267 "Windows/System32/netkvm.sys"
1268 "$g->case_sensitive_path" ("/windows/system32/NoSuchFile")
1270 "Windows/System32/NoSuchFile"
1271 "$g->case_sensitive_path" ("/windows/system33/netkvm.sys")
1273 ERROR
1274 Note: Because of the above behaviour, "$g->case_sensitive_path"
1276 cannot be used to check for the existence of a file.
1277 Note: This function does not handle drive names, backslashes etc.
1279 See also "$g->realpath".
1281 $content = $g->cat ($path);
1283 Return the contents of the file named "path".
1284 Because, in C, this function returns a "char *", there is no way to
1286 differentiate between a "\0" character in a file and end of string.
1287 To handle binary files, use the "$g->read_file" or "$g->download"
1288 functions.
1289 $checksum = $g->checksum ($csumtype, $path);
1291 This call computes the MD5, SHAx or CRC checksum of the file named
1292 "path".
1293 The type of checksum to compute is given by the "csumtype"
1295 parameter which must have one of the following values:
1296 "crc"
1298 Compute the cyclic redundancy check (CRC) specified by POSIX
1299 for the "cksum" command.
1300 "md5"
1302 Compute the MD5 hash (using the "md5sum" program).
1303 "sha1"
1305 Compute the SHA1 hash (using the "sha1sum" program).
1306 "sha224"
1308 Compute the SHA224 hash (using the "sha224sum" program).
1309 "sha256"
1311 Compute the SHA256 hash (using the "sha256sum" program).
1312 "sha384"
1314 Compute the SHA384 hash (using the "sha384sum" program).
1315 "sha512"
1317 Compute the SHA512 hash (using the "sha512sum" program).
1318 The checksum is returned as a printable string.
1320 To get the checksum for a device, use "$g->checksum_device".
1322 To get the checksums for many files, use "$g->checksums_out".
1324 $checksum = $g->checksum_device ($csumtype, $device);
1326 This call computes the MD5, SHAx or CRC checksum of the contents of
1327 the device named "device". For the types of checksums supported
1328 see the "$g->checksum" command.
1329 $g->checksums_out ($csumtype, $directory, $sumsfile);
1331 This command computes the checksums of all regular files in
1332 directory and then emits a list of those checksums to the local
1333 output file "sumsfile".
1334 This can be used for verifying the integrity of a virtual machine.
1336 However to be properly secure you should pay attention to the
1337 output of the checksum command (it uses the ones from GNU
1338 coreutils). In particular when the filename is not printable,
1339 coreutils uses a special backslash syntax. For more information,
1340 see the GNU coreutils info file.
1341 $g->chmod ($mode, $path);
1343 Change the mode (permissions) of "path" to "mode". Only numeric
1344 modes are supported.
1345 Note: When using this command from guestfish, "mode" by default
1347 would be decimal, unless you prefix it with 0 to get octal, ie. use
1348 0700 not 700.
1349 The mode actually set is affected by the umask.
1351 $g->chown ($owner, $group, $path);
1353 Change the file owner to "owner" and group to "group".
1354 Only numeric uid and gid are supported. If you want to use names,
1356 you will need to locate and parse the password file yourself
1357 (Augeas support makes this relatively easy).
1358 $count = $g->clear_backend_setting ($name);
1360 If there is a backend setting string matching "name" or beginning
1361 with "name=", then that string is removed from the backend
1362 settings.
1363 This call returns the number of strings which were removed (which
1365 may be 0, 1 or greater than 1).
1366 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
1368 $output = $g->command (\@arguments);
1370 This call runs a command from the guest filesystem. The filesystem
1371 must be mounted, and must contain a compatible operating system
1372 (ie. something Linux, with the same or compatible processor
1373 architecture).
1374 The single parameter is an argv-style list of arguments. The first
1376 element is the name of the program to run. Subsequent elements are
1377 parameters. The list must be non-empty (ie. must contain a program
1378 name). Note that the command runs directly, and is not invoked via
1379 the shell (see "$g->sh").
1380 The return value is anything printed to stdout by the command.
1382 If the command returns a non-zero exit status, then this function
1384 returns an error message. The error message string is the content
1385 of stderr from the command.
1386 The $PATH environment variable will contain at least /usr/bin and
1388 /bin. If you require a program from another location, you should
1389 provide the full path in the first parameter.
1390 Shared libraries and data files required by the program must be
1392 available on filesystems which are mounted in the correct places.
1393 It is the callerXs responsibility to ensure all filesystems that
1394 are needed are mounted at the right locations.
1395 Because of the message protocol, there is a transfer limit of
1397 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1398 guestfs(3).
1399 @lines = $g->command_lines (\@arguments);
1401 This is the same as "$g->command", but splits the result into a
1402 list of lines.
1403 See also: "$g->sh_lines"
1405 Because of the message protocol, there is a transfer limit of
1407 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1408 guestfs(3).
1409 $g->compress_device_out ($ctype, $device, $zdevice [, level =>
1411 $level]);
1412 This command compresses "device" and writes it out to the local
1413 file "zdevice".
1414 The "ctype" and optional "level" parameters have the same meaning
1416 as in "$g->compress_out".
1417 $g->compress_out ($ctype, $file, $zfile [, level => $level]);
1419 This command compresses file and writes it out to the local file
1420 zfile.
1421 The compression program used is controlled by the "ctype"
1423 parameter. Currently this includes: "compress", "gzip", "bzip2",
1424 "xz" or "lzop". Some compression types may not be supported by
1425 particular builds of libguestfs, in which case you will get an
1426 error containing the substring "not supported".
1427 The optional "level" parameter controls compression level. The
1429 meaning and default for this parameter depends on the compression
1430 program being used.
1431 $g->config ($hvparam, $hvvalue);
1433 This can be used to add arbitrary hypervisor parameters of the form
1434 -param value. Actually itXs not quite arbitrary - we prevent you
1435 from setting some parameters which would interfere with parameters
1436 that we use.
1437 The first character of "hvparam" string must be a "-" (dash).
1439 "hvvalue" can be NULL.
1441 $g->copy_attributes ($src, $dest [, all => $all] [, mode => $mode] [,
1443 xattributes => $xattributes] [, ownership => $ownership]);
1444 Copy the attributes of a path (which can be a file or a directory)
1445 to another path.
1446 By default "no" attribute is copied, so make sure to specify any
1448 (or "all" to copy everything).
1449 The optional arguments specify which attributes can be copied:
1451 "mode"
1453 Copy part of the file mode from "source" to "destination". Only
1454 the UNIX permissions and the sticky/setuid/setgid bits can be
1455 copied.
1456 "xattributes"
1458 Copy the Linux extended attributes (xattrs) from "source" to
1459 "destination". This flag does nothing if the linuxxattrs
1460 feature is not available (see "$g->feature_available").
1461 "ownership"
1463 Copy the owner uid and the group gid of "source" to
1464 "destination".
1465 "all"
1467 Copy all the attributes from "source" to "destination".
1468 Enabling it enables all the other flags, if they are not
1469 specified already.
1470 $g->copy_device_to_device ($src, $dest [, srcoffset => $srcoffset] [,
1472 destoffset => $destoffset] [, size => $size] [, sparse => $sparse] [,
1473 append => $append]);
1474 The four calls "$g->copy_device_to_device",
1475 "$g->copy_device_to_file", "$g->copy_file_to_device", and
1476 "$g->copy_file_to_file" let you copy from a source (device|file) to
1477 a destination (device|file).
1478 Partial copies can be made since you can specify optionally the
1480 source offset, destination offset and size to copy. These values
1481 are all specified in bytes. If not given, the offsets both default
1482 to zero, and the size defaults to copying as much as possible until
1483 we hit the end of the source.
1484 The source and destination may be the same object. However
1486 overlapping regions may not be copied correctly.
1487 If the destination is a file, it is created if required. If the
1489 destination file is not large enough, it is extended.
1490 If the destination is a file and the "append" flag is not set, then
1492 the destination file is truncated. If the "append" flag is set,
1493 then the copy appends to the destination file. The "append" flag
1494 currently cannot be set for devices.
1495 If the "sparse" flag is true then the call avoids writing blocks
1497 that contain only zeroes, which can help in some situations where
1498 the backing disk is thin-provisioned. Note that unless the target
1499 is already zeroed, using this option will result in incorrect
1500 copying.
1501 $g->copy_device_to_file ($src, $dest [, srcoffset => $srcoffset] [,
1503 destoffset => $destoffset] [, size => $size] [, sparse => $sparse] [,
1504 append => $append]);
1505 See "$g->copy_device_to_device" for a general overview of this
1506 call.
1507 $g->copy_file_to_device ($src, $dest [, srcoffset => $srcoffset] [,
1509 destoffset => $destoffset] [, size => $size] [, sparse => $sparse] [,
1510 append => $append]);
1511 See "$g->copy_device_to_device" for a general overview of this
1512 call.
1513 $g->copy_file_to_file ($src, $dest [, srcoffset => $srcoffset] [,
1515 destoffset => $destoffset] [, size => $size] [, sparse => $sparse] [,
1516 append => $append]);
1517 See "$g->copy_device_to_device" for a general overview of this
1518 call.
1519 This is not the function you want for copying files. This is for
1521 copying blocks within existing files. See "$g->cp", "$g->cp_a" and
1522 "$g->mv" for general file copying and moving functions.
1523 $g->copy_in ($localpath, $remotedir);
1525 "$g->copy_in" copies local files or directories recursively into
1526 the disk image, placing them in the directory called "remotedir"
1527 (which must exist).
1528 Wildcards cannot be used.
1530 $g->copy_out ($remotepath, $localdir);
1532 "$g->copy_out" copies remote files or directories recursively out
1533 of the disk image, placing them on the host disk in a local
1534 directory called "localdir" (which must exist).
1535 To download to the current directory, use "." as in:
1537 C<$g-E<gt>copy_out> /home .
1539 Wildcards cannot be used.
1541 $g->copy_size ($src, $dest, $size);
1543 This command copies exactly "size" bytes from one source device or
1544 file "src" to another destination device or file "dest".
1545 Note this will fail if the source is too short or if the
1547 destination is not large enough.
1548 This function is deprecated. In new code, use the
1550 "copy_device_to_device" call instead.
1551 Deprecated functions will not be removed from the API, but the fact
1553 that they are deprecated indicates that there are problems with
1554 correct use of these functions.
1555 $g->cp ($src, $dest);
1557 This copies a file from "src" to "dest" where "dest" is either a
1558 destination filename or destination directory.
1559 $g->cp_a ($src, $dest);
1561 This copies a file or directory from "src" to "dest" recursively
1562 using the "cp -a" command.
1563 $g->cp_r ($src, $dest);
1565 This copies a file or directory from "src" to "dest" recursively
1566 using the "cp -rP" command.
1567 Most users should use "$g->cp_a" instead. This command is useful
1569 when you don't want to preserve permissions, because the target
1570 filesystem does not support it (primarily when writing to DOS FAT
1571 filesystems).
1572 $g->cpio_out ($directory, $cpiofile [, format => $format]);
1574 This command packs the contents of directory and downloads it to
1575 local file "cpiofile".
1576 The optional "format" parameter can be used to select the format.
1578 Only the following formats are currently permitted:
1579 "newc"
1581 New (SVR4) portable format. This format happens to be
1582 compatible with the cpio-like format used by the Linux kernel
1583 for initramfs.
1584 This is the default format.
1586 "crc"
1588 New (SVR4) portable format with a checksum.
1589 $g->dd ($src, $dest);
1591 This command copies from one source device or file "src" to another
1592 destination device or file "dest". Normally you would use this to
1593 copy to or from a device or partition, for example to duplicate a
1594 filesystem.
1595 If the destination is a device, it must be as large or larger than
1597 the source file or device, otherwise the copy will fail. This
1598 command cannot do partial copies (see "$g->copy_device_to_device").
1599 This function is deprecated. In new code, use the
1601 "copy_device_to_device" call instead.
1602 Deprecated functions will not be removed from the API, but the fact
1604 that they are deprecated indicates that there are problems with
1605 correct use of these functions.
1606 $index = $g->device_index ($device);
1608 This function takes a device name (eg. "/dev/sdb") and returns the
1609 index of the device in the list of devices.
1610 Index numbers start from 0. The named device must exist, for
1612 example as a string returned from "$g->list_devices".
1613 See also "$g->list_devices", "$g->part_to_dev".
1615 $output = $g->df ();
1617 This command runs the "df" command to report disk space used.
1618 This command is mostly useful for interactive sessions. It is not
1620 intended that you try to parse the output string. Use
1621 "$g->statvfs" from programs.
1622 $output = $g->df_h ();
1624 This command runs the "df -h" command to report disk space used in
1625 human-readable format.
1626 This command is mostly useful for interactive sessions. It is not
1628 intended that you try to parse the output string. Use
1629 "$g->statvfs" from programs.
1630 $g->disk_create ($filename, $format, $size [, backingfile =>
1632 $backingfile] [, backingformat => $backingformat] [, preallocation =>
1633 $preallocation] [, compat => $compat] [, clustersize => $clustersize]);
1634 Create a blank disk image called filename (a host file) with format
1635 "format" (usually "raw" or "qcow2"). The size is "size" bytes.
1636 If used with the optional "backingfile" parameter, then a snapshot
1638 is created on top of the backing file. In this case, "size" must
1639 be passed as "-1". The size of the snapshot is the same as the
1640 size of the backing file, which is discovered automatically. You
1641 are encouraged to also pass "backingformat" to describe the format
1642 of "backingfile".
1643 If filename refers to a block device, then the device is formatted.
1645 The "size" is ignored since block devices have an intrinsic size.
1646 The other optional parameters are:
1648 "preallocation"
1650 If format is "raw", then this can be either "off" (or "sparse")
1651 or "full" to create a sparse or fully allocated file
1652 respectively. The default is "off".
1653 If format is "qcow2", then this can be "off" (or "sparse"),
1655 "metadata" or "full". Preallocating metadata can be faster
1656 when doing lots of writes, but uses more space. The default is
1657 "off".
1658 "compat"
1660 "qcow2" only: Pass the string 1.1 to use the advanced qcow2
1661 format supported by qemu X 1.1.
1662 "clustersize"
1664 "qcow2" only: Change the qcow2 cluster size. The default is
1665 65536 (bytes) and this setting may be any power of two between
1666 512 and 2097152.
1667 Note that this call does not add the new disk to the handle. You
1669 may need to call "$g->add_drive_opts" separately.
1670 $format = $g->disk_format ($filename);
1672 Detect and return the format of the disk image called filename.
1673 filename can also be a host device, etc. If the format of the
1674 image could not be detected, then "unknown" is returned.
1675 Note that detecting the disk format can be insecure under some
1677 circumstances. See "CVE-2010-3851" in guestfs(3).
1678 See also: "DISK IMAGE FORMATS" in guestfs(3)
1680 $backingfile = $g->disk_has_backing_file ($filename);
1682 Detect and return whether the disk image filename has a backing
1683 file.
1684 Note that detecting disk features can be insecure under some
1686 circumstances. See "CVE-2010-3851" in guestfs(3).
1687 $size = $g->disk_virtual_size ($filename);
1689 Detect and return the virtual size in bytes of the disk image
1690 called filename.
1691 Note that detecting disk features can be insecure under some
1693 circumstances. See "CVE-2010-3851" in guestfs(3).
1694 $kmsgs = $g->dmesg ();
1696 This returns the kernel messages ("dmesg" output) from the guest
1697 kernel. This is sometimes useful for extended debugging of
1698 problems.
1699 Another way to get the same information is to enable verbose
1701 messages with "$g->set_verbose" or by setting the environment
1702 variable "LIBGUESTFS_DEBUG=1" before running the program.
1703 $g->download ($remotefilename, $filename);
1705 Download file remotefilename and save it as filename on the local
1706 machine.
1707 filename can also be a named pipe.
1709 See also "$g->upload", "$g->cat".
1711 $g->download_blocks ($device, $start, $stop, $filename [, unallocated
1713 => $unallocated]);
1714 Download the data units from start address to stop from the disk
1715 partition (eg. /dev/sda1) and save them as filename on the local
1716 machine.
1717 The use of this API on sparse disk image formats such as QCOW, may
1719 result in large zero-filled files downloaded on the host.
1720 The size of a data unit varies across filesystem implementations.
1722 On NTFS filesystems data units are referred as clusters while on
1723 ExtX ones they are referred as fragments.
1724 If the optional "unallocated" flag is true (default is false), only
1726 the unallocated blocks will be extracted. This is useful to detect
1727 hidden data or to retrieve deleted files which data units have not
1728 been overwritten yet.
1729 This function depends on the feature "sleuthkit". See also
1731 "$g->feature-available".
1732 $g->download_inode ($device, $inode, $filename);
1734 Download a file given its inode from the disk partition (eg.
1735 /dev/sda1) and save it as filename on the local machine.
1736 It is not required to mount the disk to run this command.
1738 The command is capable of downloading deleted or inaccessible
1740 files.
1741 This function depends on the feature "sleuthkit". See also
1743 "$g->feature-available".
1744 $g->download_offset ($remotefilename, $filename, $offset, $size);
1746 Download file remotefilename and save it as filename on the local
1747 machine.
1748 remotefilename is read for "size" bytes starting at "offset" (this
1750 region must be within the file or device).
1751 Note that there is no limit on the amount of data that can be
1753 downloaded with this call, unlike with "$g->pread", and this call
1754 always reads the full amount unless an error occurs.
1755 See also "$g->download", "$g->pread".
1757 $g->drop_caches ($whattodrop);
1759 This instructs the guest kernel to drop its page cache, and/or
1760 dentries and inode caches. The parameter "whattodrop" tells the
1761 kernel what precisely to drop, see
1762 <http://linux-mm.org/Drop_Caches>
1763 Setting "whattodrop" to 3 should drop everything.
1765 This automatically calls sync(2) before the operation, so that the
1767 maximum guest memory is freed.
1768 $sizekb = $g->du ($path);
1770 This command runs the "du -s" command to estimate file space usage
1771 for "path".
1772 "path" can be a file or a directory. If "path" is a directory then
1774 the estimate includes the contents of the directory and all
1775 subdirectories (recursively).
1776 The result is the estimated size in kilobytes (ie. units of 1024
1778 bytes).
1779 $g->e2fsck ($device [, correct => $correct] [, forceall => $forceall]);
1781 This runs the ext2/ext3 filesystem checker on "device". It can
1782 take the following optional arguments:
1783 "correct"
1785 Automatically repair the file system. This option will cause
1786 e2fsck to automatically fix any filesystem problems that can be
1787 safely fixed without human intervention.
1788 This option may not be specified at the same time as the
1790 "forceall" option.
1791 "forceall"
1793 Assume an answer of XyesX to all questions; allows e2fsck to be
1794 used non-interactively.
1795 This option may not be specified at the same time as the
1797 "correct" option.
1798 $g->e2fsck_f ($device);
1800 This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
1801 checker on "device", noninteractively (-p), even if the filesystem
1802 appears to be clean (-f).
1803 This function is deprecated. In new code, use the "e2fsck" call
1805 instead.
1806 Deprecated functions will not be removed from the API, but the fact
1808 that they are deprecated indicates that there are problems with
1809 correct use of these functions.
1810 $output = $g->echo_daemon (\@words);
1812 This command concatenates the list of "words" passed with single
1813 spaces between them and returns the resulting string.
1814 You can use this command to test the connection through to the
1816 daemon.
1817 See also "$g->ping_daemon".
1819 @lines = $g->egrep ($regex, $path);
1821 This calls the external "egrep" program and returns the matching
1822 lines.
1823 Because of the message protocol, there is a transfer limit of
1825 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1826 guestfs(3).
1827 This function is deprecated. In new code, use the "grep" call
1829 instead.
1830 Deprecated functions will not be removed from the API, but the fact
1832 that they are deprecated indicates that there are problems with
1833 correct use of these functions.
1834 @lines = $g->egrepi ($regex, $path);
1836 This calls the external "egrep -i" program and returns the matching
1837 lines.
1838 Because of the message protocol, there is a transfer limit of
1840 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1841 guestfs(3).
1842 This function is deprecated. In new code, use the "grep" call
1844 instead.
1845 Deprecated functions will not be removed from the API, but the fact
1847 that they are deprecated indicates that there are problems with
1848 correct use of these functions.
1849 $equality = $g->equal ($file1, $file2);
1851 This compares the two files file1 and file2 and returns true if
1852 their content is exactly equal, or false otherwise.
1853 The external cmp(1) program is used for the comparison.
1855 $existsflag = $g->exists ($path);
1857 This returns "true" if and only if there is a file, directory (or
1858 anything) with the given "path" name.
1859 See also "$g->is_file", "$g->is_dir", "$g->stat".
1861 $g->extlinux ($directory);
1863 Install the SYSLINUX bootloader on the device mounted at directory.
1864 Unlike "$g->syslinux" which requires a FAT filesystem, this can be
1865 used on an ext2/3/4 or btrfs filesystem.
1866 The directory parameter can be either a mountpoint, or a directory
1868 within the mountpoint.
1869 You also have to mark the partition as "active"
1871 ("$g->part_set_bootable") and a Master Boot Record must be
1872 installed (eg. using "$g->pwrite_device") on the first sector of
1873 the whole disk. The SYSLINUX package comes with some suitable
1874 Master Boot Records. See the extlinux(1) man page for further
1875 information.
1876 Additional configuration can be supplied to SYSLINUX by placing a
1878 file called extlinux.conf on the filesystem under directory. For
1879 further information about the contents of this file, see
1880 extlinux(1).
1881 See also "$g->syslinux".
1883 This function depends on the feature "extlinux". See also
1885 "$g->feature-available".
1886 $g->fallocate ($path, $len);
1888 This command preallocates a file (containing zero bytes) named
1889 "path" of size "len" bytes. If the file exists already, it is
1890 overwritten.
1891 Do not confuse this with the guestfish-specific "alloc" command
1893 which allocates a file in the host and attaches it as a device.
1894 This function is deprecated. In new code, use the "fallocate64"
1896 call instead.
1897 Deprecated functions will not be removed from the API, but the fact
1899 that they are deprecated indicates that there are problems with
1900 correct use of these functions.
1901 $g->fallocate64 ($path, $len);
1903 This command preallocates a file (containing zero bytes) named
1904 "path" of size "len" bytes. If the file exists already, it is
1905 overwritten.
1906 Note that this call allocates disk blocks for the file. To create
1908 a sparse file use "$g->truncate_size" instead.
1909 The deprecated call "$g->fallocate" does the same, but owing to an
1911 oversight it only allowed 30 bit lengths to be specified,
1912 effectively limiting the maximum size of files created through that
1913 call to 1GB.
1914 Do not confuse this with the guestfish-specific "alloc" and
1916 "sparse" commands which create a file in the host and attach it as
1917 a device.
1918 $isavailable = $g->feature_available (\@groups);
1920 This is the same as "$g->available", but unlike that call it
1921 returns a simple true/false boolean result, instead of throwing an
1922 exception if a feature is not found. For other documentation see
1923 "$g->available".
1924 @lines = $g->fgrep ($pattern, $path);
1926 This calls the external "fgrep" program and returns the matching
1927 lines.
1928 Because of the message protocol, there is a transfer limit of
1930 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1931 guestfs(3).
1932 This function is deprecated. In new code, use the "grep" call
1934 instead.
1935 Deprecated functions will not be removed from the API, but the fact
1937 that they are deprecated indicates that there are problems with
1938 correct use of these functions.
1939 @lines = $g->fgrepi ($pattern, $path);
1941 This calls the external "fgrep -i" program and returns the matching
1942 lines.
1943 Because of the message protocol, there is a transfer limit of
1945 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
1946 guestfs(3).
1947 This function is deprecated. In new code, use the "grep" call
1949 instead.
1950 Deprecated functions will not be removed from the API, but the fact
1952 that they are deprecated indicates that there are problems with
1953 correct use of these functions.
1954 $description = $g->file ($path);
1956 This call uses the standard file(1) command to determine the type
1957 or contents of the file.
1958 This call will also transparently look inside various types of
1960 compressed file.
1961 The exact command which runs is "file -zb path". Note in
1963 particular that the filename is not prepended to the output (the -b
1964 option).
1965 The output depends on the output of the underlying file(1) command
1967 and it can change in future in ways beyond our control. In other
1968 words, the output is not guaranteed by the ABI.
1969 See also: file(1), "$g->vfs_type", "$g->lstat", "$g->is_file",
1971 "$g->is_blockdev" (etc), "$g->is_zero".
1972 $arch = $g->file_architecture ($filename);
1974 This detects the architecture of the binary filename, and returns
1975 it if known.
1976 Currently defined architectures are:
1978 "aarch64"
1980 64 bit ARM.
1981 "arm"
1983 32 bit ARM.
1984 "i386"
1986 This string is returned for all 32 bit i386, i486, i586, i686
1987 binaries irrespective of the precise processor requirements of
1988 the binary.
1989 "ia64"
1991 Intel Itanium.
1992 "ppc"
1994 32 bit Power PC.
1995 "ppc64"
1997 64 bit Power PC (big endian).
1998 "ppc64le"
2000 64 bit Power PC (little endian).
2001 "riscv32"
2003 "riscv64"
2004 "riscv128"
2005 RISC-V 32-, 64- or 128-bit variants.
2006 "s390"
2008 31 bit IBM S/390.
2009 "s390x"
2011 64 bit IBM S/390.
2012 "sparc"
2014 32 bit SPARC.
2015 "sparc64"
2017 64 bit SPARC V9 and above.
2018 "x86_64"
2020 64 bit x86-64.
2021 Libguestfs may return other architecture strings in future.
2023 The function works on at least the following types of files:
2025 · many types of Un*x and Linux binary
2027 · many types of Un*x and Linux shared library
2029 · Windows Win32 and Win64 binaries
2031 · Windows Win32 and Win64 DLLs
2033 Win32 binaries and DLLs return "i386".
2035 Win64 binaries and DLLs return "x86_64".
2037 · Linux kernel modules
2039 · Linux new-style initrd images
2041 · some non-x86 Linux vmlinuz kernels
2043 What it can't do currently:
2045 · static libraries (libfoo.a)
2047 · Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
2049 · x86 Linux vmlinuz kernels
2051 x86 vmlinuz images (bzImage format) consist of a mix of 16-,
2053 32- and compressed code, and are horribly hard to unpack. If
2054 you want to find the architecture of a kernel, use the
2055 architecture of the associated initrd or kernel module(s)
2056 instead.
2057 $size = $g->filesize ($file);
2059 This command returns the size of file in bytes.
2060 To get other stats about a file, use "$g->stat", "$g->lstat",
2062 "$g->is_dir", "$g->is_file" etc. To get the size of block devices,
2063 use "$g->blockdev_getsize64".
2064 $fsavail = $g->filesystem_available ($filesystem);
2066 Check whether libguestfs supports the named filesystem. The
2067 argument "filesystem" is a filesystem name, such as "ext3".
2068 You must call "$g->launch" before using this command.
2070 This is mainly useful as a negative test. If this returns true, it
2072 doesn't mean that a particular filesystem can be created or
2073 mounted, since filesystems can fail for other reasons such as it
2074 being a later version of the filesystem, or having incompatible
2075 features, or lacking the right mkfs.<fs> tool.
2076 See also "$g->available", "$g->feature_available", "AVAILABILITY"
2078 in guestfs(3).
2079 @dirents = $g->filesystem_walk ($device);
2081 Walk through the internal structures of a disk partition (eg.
2082 /dev/sda1) in order to return a list of all the files and
2083 directories stored within.
2084 It is not necessary to mount the disk partition to run this
2086 command.
2087 All entries in the filesystem are returned. This function can list
2089 deleted or unaccessible files. The entries are not sorted.
2090 The "tsk_dirent" structure contains the following fields.
2092 "tsk_inode"
2094 Filesystem reference number of the node. It might be 0 if the
2095 node has been deleted.
2096 "tsk_type"
2098 Basic file type information. See below for a detailed list of
2099 values.
2100 "tsk_size"
2102 File size in bytes. It might be "-1" if the node has been
2103 deleted.
2104 "tsk_name"
2106 The file path relative to its directory.
2107 "tsk_flags"
2109 Bitfield containing extra information regarding the entry. It
2110 contains the logical OR of the following values:
2111 0x0001
2113 If set to 1, the file is allocated and visible within the
2114 filesystem. Otherwise, the file has been deleted. Under
2115 certain circumstances, the function "download_inode" can be
2116 used to recover deleted files.
2117 0x0002
2119 Filesystem such as NTFS and Ext2 or greater, separate the
2120 file name from the metadata structure. The bit is set to 1
2121 when the file name is in an unallocated state and the
2122 metadata structure is in an allocated one. This generally
2123 implies the metadata has been reallocated to a new file.
2124 Therefore, information such as file type, file size,
2125 timestamps, number of links and symlink target might not
2126 correspond with the ones of the original deleted entry.
2127 0x0004
2129 The bit is set to 1 when the file is compressed using
2130 filesystem native compression support (NTFS). The API is
2131 not able to detect application level compression.
2132 "tsk_atime_sec"
2134 "tsk_atime_nsec"
2135 "tsk_mtime_sec"
2136 "tsk_mtime_nsec"
2137 "tsk_ctime_sec"
2138 "tsk_ctime_nsec"
2139 "tsk_crtime_sec"
2140 "tsk_crtime_nsec"
2141 Respectively, access, modification, last status change and
2142 creation time in Unix format in seconds and nanoseconds.
2143 "tsk_nlink"
2145 Number of file names pointing to this entry.
2146 "tsk_link"
2148 If the entry is a symbolic link, this field will contain the
2149 path to the target file.
2150 The "tsk_type" field will contain one of the following characters:
2152 'b' Block special
2154 'c' Char special
2156 'd' Directory
2158 'f' FIFO (named pipe)
2160 'l' Symbolic link
2162 'r' Regular file
2164 's' Socket
2166 'h' Shadow inode (Solaris)
2168 'w' Whiteout inode (BSD)
2170 'u' Unknown file type
2172 This function depends on the feature "libtsk". See also
2174 "$g->feature-available".
2175 $g->fill ($c, $len, $path);
2177 This command creates a new file called "path". The initial content
2178 of the file is "len" octets of "c", where "c" must be a number in
2179 the range "[0..255]".
2180 To fill a file with zero bytes (sparsely), it is much more
2182 efficient to use "$g->truncate_size". To create a file with a
2183 pattern of repeating bytes use "$g->fill_pattern".
2184 $g->fill_dir ($dir, $nr);
2186 This function, useful for testing filesystems, creates "nr" empty
2187 files in the directory "dir" with names 00000000 through "nr-1"
2188 (ie. each file name is 8 digits long padded with zeroes).
2189 $g->fill_pattern ($pattern, $len, $path);
2191 This function is like "$g->fill" except that it creates a new file
2192 of length "len" containing the repeating pattern of bytes in
2193 "pattern". The pattern is truncated if necessary to ensure the
2194 length of the file is exactly "len" bytes.
2195 @names = $g->find ($directory);
2197 This command lists out all files and directories, recursively,
2198 starting at directory. It is essentially equivalent to running the
2199 shell command "find directory -print" but some post-processing
2200 happens on the output, described below.
2201 This returns a list of strings without any prefix. Thus if the
2203 directory structure was:
2204 /tmp/a
2206 /tmp/b
2207 /tmp/c/d
2208 then the returned list from "$g->find" /tmp would be 4 elements:
2210 a
2212 b
2213 c
2214 c/d
2215 If directory is not a directory, then this command returns an
2217 error.
2218 The returned list is sorted.
2220 $g->find0 ($directory, $files);
2222 This command lists out all files and directories, recursively,
2223 starting at directory, placing the resulting list in the external
2224 file called files.
2225 This command works the same way as "$g->find" with the following
2227 exceptions:
2228 · The resulting list is written to an external file.
2230 · Items (filenames) in the result are separated by "\0"
2232 characters. See find(1) option -print0.
2233 · The result list is not sorted.
2235 @dirents = $g->find_inode ($device, $inode);
2237 Searches all the entries associated with the given inode.
2238 For each entry, a "tsk_dirent" structure is returned. See
2240 "filesystem_walk" for more information about "tsk_dirent"
2241 structures.
2242 This function depends on the feature "libtsk". See also
2244 "$g->feature-available".
2245 $device = $g->findfs_label ($label);
2247 This command searches the filesystems and returns the one which has
2248 the given label. An error is returned if no such filesystem can be
2249 found.
2250 To find the label of a filesystem, use "$g->vfs_label".
2252 $device = $g->findfs_uuid ($uuid);
2254 This command searches the filesystems and returns the one which has
2255 the given UUID. An error is returned if no such filesystem can be
2256 found.
2257 To find the UUID of a filesystem, use "$g->vfs_uuid".
2259 $status = $g->fsck ($fstype, $device);
2261 This runs the filesystem checker (fsck) on "device" which should
2262 have filesystem type "fstype".
2263 The returned integer is the status. See fsck(8) for the list of
2265 status codes from "fsck".
2266 Notes:
2268 · Multiple status codes can be summed together.
2270 · A non-zero return code can mean "success", for example if
2272 errors have been corrected on the filesystem.
2273 · Checking or repairing NTFS volumes is not supported (by linux-
2275 ntfs).
2276 This command is entirely equivalent to running "fsck -a -t fstype
2278 device".
2279 $g->fstrim ($mountpoint [, offset => $offset] [, length => $length] [,
2281 minimumfreeextent => $minimumfreeextent]);
2282 Trim the free space in the filesystem mounted on "mountpoint". The
2283 filesystem must be mounted read-write.
2284 The filesystem contents are not affected, but any free space in the
2286 filesystem is "trimmed", that is, given back to the host device,
2287 thus making disk images more sparse, allowing unused space in qcow2
2288 files to be reused, etc.
2289 This operation requires support in libguestfs, the mounted
2291 filesystem, the host filesystem, qemu and the host kernel. If this
2292 support isn't present it may give an error or even appear to run
2293 but do nothing.
2294 In the case where the kernel vfs driver does not support trimming,
2296 this call will fail with errno set to "ENOTSUP". Currently this
2297 happens when trying to trim FAT filesystems.
2298 See also "$g->zero_free_space". That is a slightly different
2300 operation that turns free space in the filesystem into zeroes. It
2301 is valid to call "$g->fstrim" either instead of, or after calling
2302 "$g->zero_free_space".
2303 This function depends on the feature "fstrim". See also
2305 "$g->feature-available".
2306 $append = $g->get_append ();
2308 Return the additional kernel options which are added to the
2309 libguestfs appliance kernel command line.
2310 If "NULL" then no options are added.
2312 $backend = $g->get_attach_method ();
2314 Return the current backend.
2315 See "$g->set_backend" and "BACKEND" in guestfs(3).
2317 This function is deprecated. In new code, use the "get_backend"
2319 call instead.
2320 Deprecated functions will not be removed from the API, but the fact
2322 that they are deprecated indicates that there are problems with
2323 correct use of these functions.
2324 $autosync = $g->get_autosync ();
2326 Get the autosync flag.
2327 $backend = $g->get_backend ();
2329 Return the current backend.
2330 This handle property was previously called the "attach method".
2332 See "$g->set_backend" and "BACKEND" in guestfs(3).
2334 $val = $g->get_backend_setting ($name);
2336 Find a backend setting string which is either "name" or begins with
2337 "name=". If "name", this returns the string "1". If "name=", this
2338 returns the part after the equals sign (which may be an empty
2339 string).
2340 If no such setting is found, this function throws an error. The
2342 errno (see "$g->last_errno") will be "ESRCH" in this case.
2343 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
2345 @settings = $g->get_backend_settings ();
2347 Return the current backend settings.
2348 This call returns all backend settings strings. If you want to
2350 find a single backend setting, see "$g->get_backend_setting".
2351 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
2353 $cachedir = $g->get_cachedir ();
2355 Get the directory used by the handle to store the appliance cache.
2356 $direct = $g->get_direct ();
2358 Return the direct appliance mode flag.
2359 This function is deprecated. In new code, use the
2361 "internal_get_console_socket" call instead.
2362 Deprecated functions will not be removed from the API, but the fact
2364 that they are deprecated indicates that there are problems with
2365 correct use of these functions.
2366 $attrs = $g->get_e2attrs ($file);
2368 This returns the file attributes associated with file.
2369 The attributes are a set of bits associated with each inode which
2371 affect the behaviour of the file. The attributes are returned as a
2372 string of letters (described below). The string may be empty,
2373 indicating that no file attributes are set for this file.
2374 These attributes are only present when the file is located on an
2376 ext2/3/4 filesystem. Using this call on other filesystem types
2377 will result in an error.
2378 The characters (file attributes) in the returned string are
2380 currently:
2381 'A' When the file is accessed, its atime is not modified.
2383 'a' The file is append-only.
2385 'c' The file is compressed on-disk.
2387 'D' (Directories only.) Changes to this directory are written
2389 synchronously to disk.
2390 'd' The file is not a candidate for backup (see dump(8)).
2392 'E' The file has compression errors.
2394 'e' The file is using extents.
2396 'h' The file is storing its blocks in units of the filesystem
2398 blocksize instead of sectors.
2399 'I' (Directories only.) The directory is using hashed trees.
2401 'i' The file is immutable. It cannot be modified, deleted or
2403 renamed. No link can be created to this file.
2404 'j' The file is data-journaled.
2406 's' When the file is deleted, all its blocks will be zeroed.
2408 'S' Changes to this file are written synchronously to disk.
2410 'T' (Directories only.) This is a hint to the block allocator that
2412 subdirectories contained in this directory should be spread
2413 across blocks. If not present, the block allocator will try to
2414 group subdirectories together.
2415 't' For a file, this disables tail-merging. (Not used by upstream
2417 implementations of ext2.)
2418 'u' When the file is deleted, its blocks will be saved, allowing
2420 the file to be undeleted.
2421 'X' The raw contents of the compressed file may be accessed.
2423 'Z' The compressed file is dirty.
2425 More file attributes may be added to this list later. Not all file
2427 attributes may be set for all kinds of files. For detailed
2428 information, consult the chattr(1) man page.
2429 See also "$g->set_e2attrs".
2431 Don't confuse these attributes with extended attributes (see
2433 "$g->getxattr").
2434 $generation = $g->get_e2generation ($file);
2436 This returns the ext2 file generation of a file. The generation
2437 (which used to be called the "version") is a number associated with
2438 an inode. This is most commonly used by NFS servers.
2439 The generation is only present when the file is located on an
2441 ext2/3/4 filesystem. Using this call on other filesystem types
2442 will result in an error.
2443 See "$g->set_e2generation".
2445 $label = $g->get_e2label ($device);
2447 This returns the ext2/3/4 filesystem label of the filesystem on
2448 "device".
2449 This function is deprecated. In new code, use the "vfs_label" call
2451 instead.
2452 Deprecated functions will not be removed from the API, but the fact
2454 that they are deprecated indicates that there are problems with
2455 correct use of these functions.
2456 $uuid = $g->get_e2uuid ($device);
2458 This returns the ext2/3/4 filesystem UUID of the filesystem on
2459 "device".
2460 This function is deprecated. In new code, use the "vfs_uuid" call
2462 instead.
2463 Deprecated functions will not be removed from the API, but the fact
2465 that they are deprecated indicates that there are problems with
2466 correct use of these functions.
2467 $hv = $g->get_hv ();
2469 Return the current hypervisor binary.
2470 This is always non-NULL. If it wasn't set already, then this will
2472 return the default qemu binary name.
2473 $identifier = $g->get_identifier ();
2475 Get the handle identifier. See "$g->set_identifier".
2476 $challenge = $g->get_libvirt_requested_credential_challenge ($index);
2478 Get the challenge (provided by libvirt) for the "index"'th
2479 requested credential. If libvirt did not provide a challenge, this
2480 returns the empty string "".
2481 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2483 example code.
2484 $defresult = $g->get_libvirt_requested_credential_defresult ($index);
2486 Get the default result (provided by libvirt) for the "index"'th
2487 requested credential. If libvirt did not provide a default result,
2488 this returns the empty string "".
2489 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2491 example code.
2492 $prompt = $g->get_libvirt_requested_credential_prompt ($index);
2494 Get the prompt (provided by libvirt) for the "index"'th requested
2495 credential. If libvirt did not provide a prompt, this returns the
2496 empty string "".
2497 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2499 example code.
2500 @creds = $g->get_libvirt_requested_credentials ();
2502 This should only be called during the event callback for events of
2503 type "GUESTFS_EVENT_LIBVIRT_AUTH".
2504 Return the list of credentials requested by libvirt. Possible
2506 values are a subset of the strings provided when you called
2507 "$g->set_libvirt_supported_credentials".
2508 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2510 example code.
2511 $memsize = $g->get_memsize ();
2513 This gets the memory size in megabytes allocated to the hypervisor.
2514 If "$g->set_memsize" was not called on this handle, and if
2516 "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
2517 default value for memsize.
2518 For more information on the architecture of libguestfs, see
2520 guestfs(3).
2521 $network = $g->get_network ();
2523 This returns the enable network flag.
2524 $path = $g->get_path ();
2526 Return the current search path.
2527 This is always non-NULL. If it wasn't set already, then this will
2529 return the default path.
2530 $pgroup = $g->get_pgroup ();
2532 This returns the process group flag.
2533 $pid = $g->get_pid ();
2535 Return the process ID of the hypervisor. If there is no hypervisor
2536 running, then this will return an error.
2537 This is an internal call used for debugging and testing.
2539 $program = $g->get_program ();
2541 Get the program name. See "$g->set_program".
2542 $hv = $g->get_qemu ();
2544 Return the current hypervisor binary (usually qemu).
2545 This is always non-NULL. If it wasn't set already, then this will
2547 return the default qemu binary name.
2548 This function is deprecated. In new code, use the "get_hv" call
2550 instead.
2551 Deprecated functions will not be removed from the API, but the fact
2553 that they are deprecated indicates that there are problems with
2554 correct use of these functions.
2555 $recoveryproc = $g->get_recovery_proc ();
2557 Return the recovery process enabled flag.
2558 $selinux = $g->get_selinux ();
2560 This returns the current setting of the selinux flag which is
2561 passed to the appliance at boot time. See "$g->set_selinux".
2562 For more information on the architecture of libguestfs, see
2564 guestfs(3).
2565 This function is deprecated. In new code, use the
2567 "selinux_relabel" call instead.
2568 Deprecated functions will not be removed from the API, but the fact
2570 that they are deprecated indicates that there are problems with
2571 correct use of these functions.
2572 $smp = $g->get_smp ();
2574 This returns the number of virtual CPUs assigned to the appliance.
2575 $sockdir = $g->get_sockdir ();
2577 Get the directory used by the handle to store temporary socket
2578 files.
2579 This is different from "$g->tmpdir", as we need shorter paths for
2581 sockets (due to the limited buffers of filenames for UNIX sockets),
2582 and "$g->tmpdir" may be too long for them.
2583 The environment variable "XDG_RUNTIME_DIR" controls the default
2585 value: If "XDG_RUNTIME_DIR" is set, then that is the default. Else
2586 /tmp is the default.
2587 $state = $g->get_state ();
2589 This returns the current state as an opaque integer. This is only
2590 useful for printing debug and internal error messages.
2591 For more information on states, see guestfs(3).
2593 $tmpdir = $g->get_tmpdir ();
2595 Get the directory used by the handle to store temporary files.
2596 $trace = $g->get_trace ();
2598 Return the command trace flag.
2599 $mask = $g->get_umask ();
2601 Return the current umask. By default the umask is 022 unless it
2602 has been set by calling "$g->umask".
2603 $verbose = $g->get_verbose ();
2605 This returns the verbose messages flag.
2606 $context = $g->getcon ();
2608 This gets the SELinux security context of the daemon.
2609 See the documentation about SELINUX in guestfs(3), and "$g->setcon"
2611 This function depends on the feature "selinux". See also
2613 "$g->feature-available".
2614 This function is deprecated. In new code, use the
2616 "selinux_relabel" call instead.
2617 Deprecated functions will not be removed from the API, but the fact
2619 that they are deprecated indicates that there are problems with
2620 correct use of these functions.
2621 $xattr = $g->getxattr ($path, $name);
2623 Get a single extended attribute from file "path" named "name".
2624 This call follows symlinks. If you want to lookup an extended
2625 attribute for the symlink itself, use "$g->lgetxattr".
2626 Normally it is better to get all extended attributes from a file in
2628 one go by calling "$g->getxattrs". However some Linux filesystem
2629 implementations are buggy and do not provide a way to list out
2630 attributes. For these filesystems (notably ntfs-3g) you have to
2631 know the names of the extended attributes you want in advance and
2632 call this function.
2633 Extended attribute values are blobs of binary data. If there is no
2635 extended attribute named "name", this returns an error.
2636 See also: "$g->getxattrs", "$g->lgetxattr", attr(5).
2638 This function depends on the feature "linuxxattrs". See also
2640 "$g->feature-available".
2641 @xattrs = $g->getxattrs ($path);
2643 This call lists the extended attributes of the file or directory
2644 "path".
2645 At the system call level, this is a combination of the listxattr(2)
2647 and getxattr(2) calls.
2648 See also: "$g->lgetxattrs", attr(5).
2650 This function depends on the feature "linuxxattrs". See also
2652 "$g->feature-available".
2653 @paths = $g->glob_expand ($pattern [, directoryslash =>
2655 $directoryslash]);
2656 This command searches for all the pathnames matching "pattern"
2657 according to the wildcard expansion rules used by the shell.
2658 If no paths match, then this returns an empty list (note: not an
2660 error).
2661 It is just a wrapper around the C glob(3) function with flags
2663 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
2664 "directoryslash" controls whether use the "GLOB_MARK" flag for
2666 glob(3), and it defaults to true. It can be explicitly set as off
2667 to return no trailing slashes in filenames of directories.
2668 Notice that there is no equivalent command for expanding a device
2670 name (eg. /dev/sd*). Use "$g->list_devices", "$g->list_partitions"
2671 etc functions instead.
2672 @paths = $g->glob_expand_opts ($pattern [, directoryslash =>
2674 $directoryslash]);
2675 This is an alias of "glob_expand".
2676 @lines = $g->grep ($regex, $path [, extended => $extended] [, fixed =>
2678 $fixed] [, insensitive => $insensitive] [, compressed => $compressed]);
2679 This calls the external "grep" program and returns the matching
2680 lines.
2681 The optional flags are:
2683 "extended"
2685 Use extended regular expressions. This is the same as using
2686 the -E flag.
2687 "fixed"
2689 Match fixed (don't use regular expressions). This is the same
2690 as using the -F flag.
2691 "insensitive"
2693 Match case-insensitive. This is the same as using the -i flag.
2694 "compressed"
2696 Use "zgrep" instead of "grep". This allows the input to be
2697 compress- or gzip-compressed.
2698 Because of the message protocol, there is a transfer limit of
2700 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2701 guestfs(3).
2702 @lines = $g->grep_opts ($regex, $path [, extended => $extended] [,
2704 fixed => $fixed] [, insensitive => $insensitive] [, compressed =>
2705 $compressed]);
2706 This is an alias of "grep".
2707 @lines = $g->grepi ($regex, $path);
2709 This calls the external "grep -i" program and returns the matching
2710 lines.
2711 Because of the message protocol, there is a transfer limit of
2713 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2714 guestfs(3).
2715 This function is deprecated. In new code, use the "grep" call
2717 instead.
2718 Deprecated functions will not be removed from the API, but the fact
2720 that they are deprecated indicates that there are problems with
2721 correct use of these functions.
2722 $g->grub_install ($root, $device);
2724 This command installs GRUB 1 (the Grand Unified Bootloader) on
2725 "device", with the root directory being "root".
2726 Notes:
2728 · There is currently no way in the API to install grub2, which is
2730 used by most modern Linux guests. It is possible to run the
2731 grub2 command from the guest, although see the caveats in
2732 "RUNNING COMMANDS" in guestfs(3).
2733 · This uses "grub-install" from the host. Unfortunately grub is
2735 not always compatible with itself, so this only works in rather
2736 narrow circumstances. Careful testing with each guest version
2737 is advisable.
2738 · If grub-install reports the error "No suitable drive was found
2740 in the generated device map." it may be that you need to
2741 create a /boot/grub/device.map file first that contains the
2742 mapping between grub device names and Linux device names. It
2743 is usually sufficient to create a file containing:
2744 (hd0) /dev/vda
2746 replacing /dev/vda with the name of the installation device.
2748 This function depends on the feature "grub". See also
2750 "$g->feature-available".
2751 @lines = $g->head ($path);
2753 This command returns up to the first 10 lines of a file as a list
2754 of strings.
2755 Because of the message protocol, there is a transfer limit of
2757 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2758 guestfs(3).
2759 @lines = $g->head_n ($nrlines, $path);
2761 If the parameter "nrlines" is a positive number, this returns the
2762 first "nrlines" lines of the file "path".
2763 If the parameter "nrlines" is a negative number, this returns lines
2765 from the file "path", excluding the last "nrlines" lines.
2766 If the parameter "nrlines" is zero, this returns an empty list.
2768 Because of the message protocol, there is a transfer limit of
2770 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2771 guestfs(3).
2772 $dump = $g->hexdump ($path);
2774 This runs "hexdump -C" on the given "path". The result is the
2775 human-readable, canonical hex dump of the file.
2776 Because of the message protocol, there is a transfer limit of
2778 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2779 guestfs(3).
2780 $g->hivex_close ();
2782 Close the current hivex handle.
2783 This is a wrapper around the hivex(3) call of the same name.
2785 This function depends on the feature "hivex". See also
2787 "$g->feature-available".
2788 $g->hivex_commit ($filename);
2790 Commit (write) changes to the hive.
2791 If the optional filename parameter is null, then the changes are
2793 written back to the same hive that was opened. If this is not null
2794 then they are written to the alternate filename given and the
2795 original hive is left untouched.
2796 This is a wrapper around the hivex(3) call of the same name.
2798 This function depends on the feature "hivex". See also
2800 "$g->feature-available".
2801 $nodeh = $g->hivex_node_add_child ($parent, $name);
2803 Add a child node to "parent" named "name".
2804 This is a wrapper around the hivex(3) call of the same name.
2806 This function depends on the feature "hivex". See also
2808 "$g->feature-available".
2809 @nodehs = $g->hivex_node_children ($nodeh);
2811 Return the list of nodes which are subkeys of "nodeh".
2812 This is a wrapper around the hivex(3) call of the same name.
2814 This function depends on the feature "hivex". See also
2816 "$g->feature-available".
2817 $g->hivex_node_delete_child ($nodeh);
2819 Delete "nodeh", recursively if necessary.
2820 This is a wrapper around the hivex(3) call of the same name.
2822 This function depends on the feature "hivex". See also
2824 "$g->feature-available".
2825 $child = $g->hivex_node_get_child ($nodeh, $name);
2827 Return the child of "nodeh" with the name "name", if it exists.
2828 This can return 0 meaning the name was not found.
2829 This is a wrapper around the hivex(3) call of the same name.
2831 This function depends on the feature "hivex". See also
2833 "$g->feature-available".
2834 $valueh = $g->hivex_node_get_value ($nodeh, $key);
2836 Return the value attached to "nodeh" which has the name "key", if
2837 it exists. This can return 0 meaning the key was not found.
2838 This is a wrapper around the hivex(3) call of the same name.
2840 This function depends on the feature "hivex". See also
2842 "$g->feature-available".
2843 $name = $g->hivex_node_name ($nodeh);
2845 Return the name of "nodeh".
2846 This is a wrapper around the hivex(3) call of the same name.
2848 This function depends on the feature "hivex". See also
2850 "$g->feature-available".
2851 $parent = $g->hivex_node_parent ($nodeh);
2853 Return the parent node of "nodeh".
2854 This is a wrapper around the hivex(3) call of the same name.
2856 This function depends on the feature "hivex". See also
2858 "$g->feature-available".
2859 $g->hivex_node_set_value ($nodeh, $key, $t, $val);
2861 Set or replace a single value under the node "nodeh". The "key" is
2862 the name, "t" is the type, and "val" is the data.
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 @valuehs = $g->hivex_node_values ($nodeh);
2870 Return the array of (key, datatype, data) tuples attached to
2871 "nodeh".
2872 This is a wrapper around the hivex(3) call of the same name.
2874 This function depends on the feature "hivex". See also
2876 "$g->feature-available".
2877 $g->hivex_open ($filename [, verbose => $verbose] [, debug => $debug]
2879 [, write => $write] [, unsafe => $unsafe]);
2880 Open the Windows Registry hive file named filename. If there was
2881 any previous hivex handle associated with this guestfs session,
2882 then it is closed.
2883 This is a wrapper around the hivex(3) call of the same name.
2885 This function depends on the feature "hivex". See also
2887 "$g->feature-available".
2888 $nodeh = $g->hivex_root ();
2890 Return the root node of the hive.
2891 This is a wrapper around the hivex(3) call of the same name.
2893 This function depends on the feature "hivex". See also
2895 "$g->feature-available".
2896 $key = $g->hivex_value_key ($valueh);
2898 Return the key (name) field of a (key, datatype, data) tuple.
2899 This is a wrapper around the hivex(3) call of the same name.
2901 This function depends on the feature "hivex". See also
2903 "$g->feature-available".
2904 $databuf = $g->hivex_value_string ($valueh);
2906 This calls "$g->hivex_value_value" (which returns the data field
2907 from a hivex value tuple). It then assumes that the field is a
2908 UTF-16LE string and converts the result to UTF-8 (or if this is not
2909 possible, it returns an error).
2910 This is useful for reading strings out of the Windows registry.
2912 However it is not foolproof because the registry is not strongly-
2913 typed and fields can contain arbitrary or unexpected data.
2914 This function depends on the feature "hivex". See also
2916 "$g->feature-available".
2917 $datatype = $g->hivex_value_type ($valueh);
2919 Return the data type field from a (key, datatype, data) tuple.
2920 This is a wrapper around the hivex(3) call of the same name.
2922 This function depends on the feature "hivex". See also
2924 "$g->feature-available".
2925 $databuf = $g->hivex_value_utf8 ($valueh);
2927 This calls "$g->hivex_value_value" (which returns the data field
2928 from a hivex value tuple). It then assumes that the field is a
2929 UTF-16LE string and converts the result to UTF-8 (or if this is not
2930 possible, it returns an error).
2931 This is useful for reading strings out of the Windows registry.
2933 However it is not foolproof because the registry is not strongly-
2934 typed and fields can contain arbitrary or unexpected data.
2935 This function depends on the feature "hivex". See also
2937 "$g->feature-available".
2938 This function is deprecated. In new code, use the
2940 "hivex_value_string" call instead.
2941 Deprecated functions will not be removed from the API, but the fact
2943 that they are deprecated indicates that there are problems with
2944 correct use of these functions.
2945 $databuf = $g->hivex_value_value ($valueh);
2947 Return the data field of a (key, datatype, data) tuple.
2948 This is a wrapper around the hivex(3) call of the same name.
2950 See also: "$g->hivex_value_utf8".
2952 This function depends on the feature "hivex". See also
2954 "$g->feature-available".
2955 $content = $g->initrd_cat ($initrdpath, $filename);
2957 This command unpacks the file filename from the initrd file called
2958 initrdpath. The filename must be given without the initial /
2959 character.
2960 For example, in guestfish you could use the following command to
2962 examine the boot script (usually called /init) contained in a Linux
2963 initrd or initramfs image:
2964 initrd-cat /boot/initrd-<version>.img init
2966 See also "$g->initrd_list".
2968 Because of the message protocol, there is a transfer limit of
2970 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
2971 guestfs(3).
2972 @filenames = $g->initrd_list ($path);
2974 This command lists out files contained in an initrd.
2975 The files are listed without any initial / character. The files
2977 are listed in the order they appear (not necessarily alphabetical).
2978 Directory names are listed as separate items.
2979 Old Linux kernels (2.4 and earlier) used a compressed ext2
2981 filesystem as initrd. We only support the newer initramfs format
2982 (compressed cpio files).
2983 $wd = $g->inotify_add_watch ($path, $mask);
2985 Watch "path" for the events listed in "mask".
2986 Note that if "path" is a directory then events within that
2988 directory are watched, but this does not happen recursively (in
2989 subdirectories).
2990 Note for non-C or non-Linux callers: the inotify events are defined
2992 by the Linux kernel ABI and are listed in
2993 /usr/include/sys/inotify.h.
2994 This function depends on the feature "inotify". See also
2996 "$g->feature-available".
2997 $g->inotify_close ();
2999 This closes the inotify handle which was previously opened by
3000 inotify_init. It removes all watches, throws away any pending
3001 events, and deallocates all resources.
3002 This function depends on the feature "inotify". See also
3004 "$g->feature-available".
3005 @paths = $g->inotify_files ();
3007 This function is a helpful wrapper around "$g->inotify_read" which
3008 just returns a list of pathnames of objects that were touched. The
3009 returned pathnames are sorted and deduplicated.
3010 This function depends on the feature "inotify". See also
3012 "$g->feature-available".
3013 $g->inotify_init ($maxevents);
3015 This command creates a new inotify handle. The inotify subsystem
3016 can be used to notify events which happen to objects in the guest
3017 filesystem.
3018 "maxevents" is the maximum number of events which will be queued up
3020 between calls to "$g->inotify_read" or "$g->inotify_files". If
3021 this is passed as 0, then the kernel (or previously set) default is
3022 used. For Linux 2.6.29 the default was 16384 events. Beyond this
3023 limit, the kernel throws away events, but records the fact that it
3024 threw them away by setting a flag "IN_Q_OVERFLOW" in the returned
3025 structure list (see "$g->inotify_read").
3026 Before any events are generated, you have to add some watches to
3028 the internal watch list. See: "$g->inotify_add_watch" and
3029 "$g->inotify_rm_watch".
3030 Queued up events should be read periodically by calling
3032 "$g->inotify_read" (or "$g->inotify_files" which is just a helpful
3033 wrapper around "$g->inotify_read"). If you don't read the events
3034 out often enough then you risk the internal queue overflowing.
3035 The handle should be closed after use by calling
3037 "$g->inotify_close". This also removes any watches automatically.
3038 See also inotify(7) for an overview of the inotify interface as
3040 exposed by the Linux kernel, which is roughly what we expose via
3041 libguestfs. Note that there is one global inotify handle per
3042 libguestfs instance.
3043 This function depends on the feature "inotify". See also
3045 "$g->feature-available".
3046 @events = $g->inotify_read ();
3048 Return the complete queue of events that have happened since the
3049 previous read call.
3050 If no events have happened, this returns an empty list.
3052 Note: In order to make sure that all events have been read, you
3054 must call this function repeatedly until it returns an empty list.
3055 The reason is that the call will read events up to the maximum
3056 appliance-to-host message size and leave remaining events in the
3057 queue.
3058 This function depends on the feature "inotify". See also
3060 "$g->feature-available".
3061 $g->inotify_rm_watch ($wd);
3063 Remove a previously defined inotify watch. See
3064 "$g->inotify_add_watch".
3065 This function depends on the feature "inotify". See also
3067 "$g->feature-available".
3068 $arch = $g->inspect_get_arch ($root);
3070 This returns the architecture of the inspected operating system.
3071 The possible return values are listed under
3072 "$g->file_architecture".
3073 If the architecture could not be determined, then the string
3075 "unknown" is returned.
3076 Please read "INSPECTION" in guestfs(3) for more details.
3078 $distro = $g->inspect_get_distro ($root);
3080 This returns the distro (distribution) of the inspected operating
3081 system.
3082 Currently defined distros are:
3084 "alpinelinux"
3086 Alpine Linux.
3087 "altlinux"
3089 ALT Linux.
3090 "archlinux"
3092 Arch Linux.
3093 "buildroot"
3095 Buildroot-derived distro, but not one we specifically
3096 recognize.
3097 "centos"
3099 CentOS.
3100 "cirros"
3102 Cirros.
3103 "coreos"
3105 CoreOS.
3106 "debian"
3108 Debian.
3109 "fedora"
3111 Fedora.
3112 "freebsd"
3114 FreeBSD.
3115 "freedos"
3117 FreeDOS.
3118 "frugalware"
3120 Frugalware.
3121 "gentoo"
3123 Gentoo.
3124 "linuxmint"
3126 Linux Mint.
3127 "mageia"
3129 Mageia.
3130 "mandriva"
3132 Mandriva.
3133 "meego"
3135 MeeGo.
3136 "msdos"
3138 Microsoft DOS.
3139 "neokylin"
3141 NeoKylin.
3142 "netbsd"
3144 NetBSD.
3145 "openbsd"
3147 OpenBSD.
3148 "opensuse"
3150 OpenSUSE.
3151 "oraclelinux"
3153 Oracle Linux.
3154 "pardus"
3156 Pardus.
3157 "pldlinux"
3159 PLD Linux.
3160 "redhat-based"
3162 Some Red Hat-derived distro.
3163 "rhel"
3165 Red Hat Enterprise Linux.
3166 "scientificlinux"
3168 Scientific Linux.
3169 "slackware"
3171 Slackware.
3172 "sles"
3174 SuSE Linux Enterprise Server or Desktop.
3175 "suse-based"
3177 Some openSuSE-derived distro.
3178 "ttylinux"
3180 ttylinux.
3181 "ubuntu"
3183 Ubuntu.
3184 "unknown"
3186 The distro could not be determined.
3187 "voidlinux"
3189 Void Linux.
3190 "windows"
3192 Windows does not have distributions. This string is returned
3193 if the OS type is Windows.
3194 Future versions of libguestfs may return other strings here. The
3196 caller should be prepared to handle any string.
3197 Please read "INSPECTION" in guestfs(3) for more details.
3199 %drives = $g->inspect_get_drive_mappings ($root);
3201 This call is useful for Windows which uses a primitive system of
3202 assigning drive letters (like C:\) to partitions. This inspection
3203 API examines the Windows Registry to find out how disks/partitions
3204 are mapped to drive letters, and returns a hash table as in the
3205 example below:
3206 C => /dev/vda2
3208 E => /dev/vdb1
3209 F => /dev/vdc1
3210 Note that keys are drive letters. For Windows, the key is case
3212 insensitive and just contains the drive letter, without the
3213 customary colon separator character.
3214 In future we may support other operating systems that also used
3216 drive letters, but the keys for those might not be case insensitive
3217 and might be longer than 1 character. For example in OS-9, hard
3218 drives were named "h0", "h1" etc.
3219 For Windows guests, currently only hard drive mappings are
3221 returned. Removable disks (eg. DVD-ROMs) are ignored.
3222 For guests that do not use drive mappings, or if the drive mappings
3224 could not be determined, this returns an empty hash table.
3225 Please read "INSPECTION" in guestfs(3) for more details. See also
3227 "$g->inspect_get_mountpoints", "$g->inspect_get_filesystems".
3228 @filesystems = $g->inspect_get_filesystems ($root);
3230 This returns a list of all the filesystems that we think are
3231 associated with this operating system. This includes the root
3232 filesystem, other ordinary filesystems, and non-mounted devices
3233 like swap partitions.
3234 In the case of a multi-boot virtual machine, it is possible for a
3236 filesystem to be shared between operating systems.
3237 Please read "INSPECTION" in guestfs(3) for more details. See also
3239 "$g->inspect_get_mountpoints".
3240 $format = $g->inspect_get_format ($root);
3242 Before libguestfs 1.38, there was some unreliable support for
3243 detecting installer CDs. This API would return:
3244 "installed"
3246 This is an installed operating system.
3247 "installer"
3249 The disk image being inspected is not an installed operating
3250 system, but a bootable install disk, live CD, or similar.
3251 "unknown"
3253 The format of this disk image is not known.
3254 In libguestfs X 1.38, this only returns "installed". Use libosinfo
3256 directly to detect installer CDs.
3257 Please read "INSPECTION" in guestfs(3) for more details.
3259 This function is deprecated. There is no replacement. Consult the
3261 API documentation in guestfs(3) for further information.
3262 Deprecated functions will not be removed from the API, but the fact
3264 that they are deprecated indicates that there are problems with
3265 correct use of these functions.
3266 $hostname = $g->inspect_get_hostname ($root);
3268 This function returns the hostname of the operating system as found
3269 by inspection of the guestXs configuration files.
3270 If the hostname could not be determined, then the string "unknown"
3272 is returned.
3273 Please read "INSPECTION" in guestfs(3) for more details.
3275 $icon = $g->inspect_get_icon ($root [, favicon => $favicon] [,
3277 highquality => $highquality]);
3278 This function returns an icon corresponding to the inspected
3279 operating system. The icon is returned as a buffer containing a
3280 PNG image (re-encoded to PNG if necessary).
3281 If it was not possible to get an icon this function returns a zero-
3283 length (non-NULL) buffer. Callers must check for this case.
3284 Libguestfs will start by looking for a file called /etc/favicon.png
3286 or C:\etc\favicon.png and if it has the correct format, the
3287 contents of this file will be returned. You can disable favicons
3288 by passing the optional "favicon" boolean as false (default is
3289 true).
3290 If finding the favicon fails, then we look in other places in the
3292 guest for a suitable icon.
3293 If the optional "highquality" boolean is true then only high
3295 quality icons are returned, which means only icons of high
3296 resolution with an alpha channel. The default (false) is to return
3297 any icon we can, even if it is of substandard quality.
3298 Notes:
3300 · Unlike most other inspection API calls, the guestXs disks must
3302 be mounted up before you call this, since it needs to read
3303 information from the guest filesystem during the call.
3304 · Security: The icon data comes from the untrusted guest, and
3306 should be treated with caution. PNG files have been known to
3307 contain exploits. Ensure that libpng (or other relevant
3308 libraries) are fully up to date before trying to process or
3309 display the icon.
3310 · The PNG image returned can be any size. It might not be
3312 square. Libguestfs tries to return the largest, highest
3313 quality icon available. The application must scale the icon to
3314 the required size.
3315 · Extracting icons from Windows guests requires the external
3317 "wrestool" program from the "icoutils" package, and several
3318 programs ("bmptopnm", "pnmtopng", "pamcut") from the "netpbm"
3319 package. These must be installed separately.
3320 · Operating system icons are usually trademarks. Seek legal
3322 advice before using trademarks in applications.
3323 $major = $g->inspect_get_major_version ($root);
3325 This returns the major version number of the inspected operating
3326 system.
3327 Windows uses a consistent versioning scheme which is not reflected
3329 in the popular public names used by the operating system. Notably
3330 the operating system known as "Windows 7" is really version 6.1
3331 (ie. major = 6, minor = 1). You can find out the real versions
3332 corresponding to releases of Windows by consulting Wikipedia or
3333 MSDN.
3334 If the version could not be determined, then 0 is returned.
3336 Please read "INSPECTION" in guestfs(3) for more details.
3338 $minor = $g->inspect_get_minor_version ($root);
3340 This returns the minor version number of the inspected operating
3341 system.
3342 If the version could not be determined, then 0 is returned.
3344 Please read "INSPECTION" in guestfs(3) for more details. See also
3346 "$g->inspect_get_major_version".
3347 %mountpoints = $g->inspect_get_mountpoints ($root);
3349 This returns a hash of where we think the filesystems associated
3350 with this operating system should be mounted. Callers should note
3351 that this is at best an educated guess made by reading
3352 configuration files such as /etc/fstab. In particular note that
3353 this may return filesystems which are non-existent or not mountable
3354 and callers should be prepared to handle or ignore failures if they
3355 try to mount them.
3356 Each element in the returned hashtable has a key which is the path
3358 of the mountpoint (eg. /boot) and a value which is the filesystem
3359 that would be mounted there (eg. /dev/sda1).
3360 Non-mounted devices such as swap devices are not returned in this
3362 list.
3363 For operating systems like Windows which still use drive letters,
3365 this call will only return an entry for the first drive "mounted
3366 on" /. For information about the mapping of drive letters to
3367 partitions, see "$g->inspect_get_drive_mappings".
3368 Please read "INSPECTION" in guestfs(3) for more details. See also
3370 "$g->inspect_get_filesystems".
3371 $id = $g->inspect_get_osinfo ($root);
3373 This function returns a possible short ID for libosinfo
3374 corresponding to the guest.
3375 Note: The returned ID is only a guess by libguestfs, and nothing
3377 ensures that it actually exists in osinfo-db.
3378 If no ID could not be determined, then the string "unknown" is
3380 returned.
3381 $packageformat = $g->inspect_get_package_format ($root);
3383 This function and "$g->inspect_get_package_management" return the
3384 package format and package management tool used by the inspected
3385 operating system. For example for Fedora these functions would
3386 return "rpm" (package format), and "yum" or "dnf" (package
3387 management).
3388 This returns the string "unknown" if we could not determine the
3390 package format or if the operating system does not have a real
3391 packaging system (eg. Windows).
3392 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
3394 "pkgsrc", "apk", "xbps". Future versions of libguestfs may return
3395 other strings.
3396 Please read "INSPECTION" in guestfs(3) for more details.
3398 $packagemanagement = $g->inspect_get_package_management ($root);
3400 "$g->inspect_get_package_format" and this function return the
3401 package format and package management tool used by the inspected
3402 operating system. For example for Fedora these functions would
3403 return "rpm" (package format), and "yum" or "dnf" (package
3404 management).
3405 This returns the string "unknown" if we could not determine the
3407 package management tool or if the operating system does not have a
3408 real packaging system (eg. Windows).
3409 Possible strings include: "yum", "dnf", "up2date", "apt" (for all
3411 Debian derivatives), "portage", "pisi", "pacman", "urpmi",
3412 "zypper", "apk", "xbps". Future versions of libguestfs may return
3413 other strings.
3414 Please read "INSPECTION" in guestfs(3) for more details.
3416 $product = $g->inspect_get_product_name ($root);
3418 This returns the product name of the inspected operating system.
3419 The product name is generally some freeform string which can be
3420 displayed to the user, but should not be parsed by programs.
3421 If the product name could not be determined, then the string
3423 "unknown" is returned.
3424 Please read "INSPECTION" in guestfs(3) for more details.
3426 $variant = $g->inspect_get_product_variant ($root);
3428 This returns the product variant of the inspected operating system.
3429 For Windows guests, this returns the contents of the Registry key
3431 "HKLM\Software\Microsoft\Windows NT\CurrentVersion"
3432 "InstallationType" which is usually a string such as "Client" or
3433 "Server" (other values are possible). This can be used to
3434 distinguish consumer and enterprise versions of Windows that have
3435 the same version number (for example, Windows 7 and Windows 2008
3436 Server are both version 6.1, but the former is "Client" and the
3437 latter is "Server").
3438 For enterprise Linux guests, in future we intend this to return the
3440 product variant such as "Desktop", "Server" and so on. But this is
3441 not implemented at present.
3442 If the product variant could not be determined, then the string
3444 "unknown" is returned.
3445 Please read "INSPECTION" in guestfs(3) for more details. See also
3447 "$g->inspect_get_product_name", "$g->inspect_get_major_version".
3448 @roots = $g->inspect_get_roots ();
3450 This function is a convenient way to get the list of root devices,
3451 as returned from a previous call to "$g->inspect_os", but without
3452 redoing the whole inspection process.
3453 This returns an empty list if either no root devices were found or
3455 the caller has not called "$g->inspect_os".
3456 Please read "INSPECTION" in guestfs(3) for more details.
3458 $name = $g->inspect_get_type ($root);
3460 This returns the type of the inspected operating system. Currently
3461 defined types are:
3462 "linux"
3464 Any Linux-based operating system.
3465 "windows"
3467 Any Microsoft Windows operating system.
3468 "freebsd"
3470 FreeBSD.
3471 "netbsd"
3473 NetBSD.
3474 "openbsd"
3476 OpenBSD.
3477 "hurd"
3479 GNU/Hurd.
3480 "dos"
3482 MS-DOS, FreeDOS and others.
3483 "minix"
3485 MINIX.
3486 "unknown"
3488 The operating system type could not be determined.
3489 Future versions of libguestfs may return other strings here. The
3491 caller should be prepared to handle any string.
3492 Please read "INSPECTION" in guestfs(3) for more details.
3494 $controlset = $g->inspect_get_windows_current_control_set ($root);
3496 This returns the Windows CurrentControlSet of the inspected guest.
3497 The CurrentControlSet is a registry key name such as
3498 "ControlSet001".
3499 This call assumes that the guest is Windows and that the Registry
3501 could be examined by inspection. If this is not the case then an
3502 error is returned.
3503 Please read "INSPECTION" in guestfs(3) for more details.
3505 $path = $g->inspect_get_windows_software_hive ($root);
3507 This returns the path to the hive (binary Windows Registry file)
3508 corresponding to HKLM\SOFTWARE.
3509 This call assumes that the guest is Windows and that the guest has
3511 a software hive file with the right name. If this is not the case
3512 then an error is returned. This call does not check that the hive
3513 is a valid Windows Registry hive.
3514 You can use "$g->hivex_open" to read or write to the hive.
3516 Please read "INSPECTION" in guestfs(3) for more details.
3518 $path = $g->inspect_get_windows_system_hive ($root);
3520 This returns the path to the hive (binary Windows Registry file)
3521 corresponding to HKLM\SYSTEM.
3522 This call assumes that the guest is Windows and that the guest has
3524 a system hive file with the right name. If this is not the case
3525 then an error is returned. This call does not check that the hive
3526 is a valid Windows Registry hive.
3527 You can use "$g->hivex_open" to read or write to the hive.
3529 Please read "INSPECTION" in guestfs(3) for more details.
3531 $systemroot = $g->inspect_get_windows_systemroot ($root);
3533 This returns the Windows systemroot of the inspected guest. The
3534 systemroot is a directory path such as /WINDOWS.
3535 This call assumes that the guest is Windows and that the systemroot
3537 could be determined by inspection. If this is not the case then an
3538 error is returned.
3539 Please read "INSPECTION" in guestfs(3) for more details.
3541 $live = $g->inspect_is_live ($root);
3543 This is deprecated and always returns "false".
3544 Please read "INSPECTION" in guestfs(3) for more details.
3546 This function is deprecated. There is no replacement. Consult the
3548 API documentation in guestfs(3) for further information.
3549 Deprecated functions will not be removed from the API, but the fact
3551 that they are deprecated indicates that there are problems with
3552 correct use of these functions.
3553 $multipart = $g->inspect_is_multipart ($root);
3555 This is deprecated and always returns "false".
3556 Please read "INSPECTION" in guestfs(3) for more details.
3558 This function is deprecated. There is no replacement. Consult the
3560 API documentation in guestfs(3) for further information.
3561 Deprecated functions will not be removed from the API, but the fact
3563 that they are deprecated indicates that there are problems with
3564 correct use of these functions.
3565 $netinst = $g->inspect_is_netinst ($root);
3567 This is deprecated and always returns "false".
3568 Please read "INSPECTION" in guestfs(3) for more details.
3570 This function is deprecated. There is no replacement. Consult the
3572 API documentation in guestfs(3) for further information.
3573 Deprecated functions will not be removed from the API, but the fact
3575 that they are deprecated indicates that there are problems with
3576 correct use of these functions.
3577 @applications = $g->inspect_list_applications ($root);
3579 Return the list of applications installed in the operating system.
3580 Note: This call works differently from other parts of the
3582 inspection API. You have to call "$g->inspect_os", then
3583 "$g->inspect_get_mountpoints", then mount up the disks, before
3584 calling this. Listing applications is a significantly more
3585 difficult operation which requires access to the full filesystem.
3586 Also note that unlike the other "$g->inspect_get_*" calls which are
3587 just returning data cached in the libguestfs handle, this call
3588 actually reads parts of the mounted filesystems during the call.
3589 This returns an empty list if the inspection code was not able to
3591 determine the list of applications.
3592 The application structure contains the following fields:
3594 "app_name"
3596 The name of the application. For Red Hat-derived and Debian-
3597 derived Linux guests, this is the package name.
3598 "app_display_name"
3600 The display name of the application, sometimes localized to the
3601 install language of the guest operating system.
3602 If unavailable this is returned as an empty string "". Callers
3604 needing to display something can use "app_name" instead.
3605 "app_epoch"
3607 For package managers which use epochs, this contains the epoch
3608 of the package (an integer). If unavailable, this is returned
3609 as 0.
3610 "app_version"
3612 The version string of the application or package. If
3613 unavailable this is returned as an empty string "".
3614 "app_release"
3616 The release string of the application or package, for package
3617 managers that use this. If unavailable this is returned as an
3618 empty string "".
3619 "app_install_path"
3621 The installation path of the application (on operating systems
3622 such as Windows which use installation paths). This path is in
3623 the format used by the guest operating system, it is not a
3624 libguestfs path.
3625 If unavailable this is returned as an empty string "".
3627 "app_trans_path"
3629 The install path translated into a libguestfs path. If
3630 unavailable this is returned as an empty string "".
3631 "app_publisher"
3633 The name of the publisher of the application, for package
3634 managers that use this. If unavailable this is returned as an
3635 empty string "".
3636 "app_url"
3638 The URL (eg. upstream URL) of the application. If unavailable
3639 this is returned as an empty string "".
3640 "app_source_package"
3642 For packaging systems which support this, the name of the
3643 source package. If unavailable this is returned as an empty
3644 string "".
3645 "app_summary"
3647 A short (usually one line) description of the application or
3648 package. If unavailable this is returned as an empty string
3649 "".
3650 "app_description"
3652 A longer description of the application or package. If
3653 unavailable this is returned as an empty string "".
3654 Please read "INSPECTION" in guestfs(3) for more details.
3656 This function is deprecated. In new code, use the
3658 "inspect_list_applications2" call instead.
3659 Deprecated functions will not be removed from the API, but the fact
3661 that they are deprecated indicates that there are problems with
3662 correct use of these functions.
3663 @applications2 = $g->inspect_list_applications2 ($root);
3665 Return the list of applications installed in the operating system.
3666 Note: This call works differently from other parts of the
3668 inspection API. You have to call "$g->inspect_os", then
3669 "$g->inspect_get_mountpoints", then mount up the disks, before
3670 calling this. Listing applications is a significantly more
3671 difficult operation which requires access to the full filesystem.
3672 Also note that unlike the other "$g->inspect_get_*" calls which are
3673 just returning data cached in the libguestfs handle, this call
3674 actually reads parts of the mounted filesystems during the call.
3675 This returns an empty list if the inspection code was not able to
3677 determine the list of applications.
3678 The application structure contains the following fields:
3680 "app2_name"
3682 The name of the application. For Red Hat-derived and Debian-
3683 derived Linux guests, this is the package name.
3684 "app2_display_name"
3686 The display name of the application, sometimes localized to the
3687 install language of the guest operating system.
3688 If unavailable this is returned as an empty string "". Callers
3690 needing to display something can use "app2_name" instead.
3691 "app2_epoch"
3693 For package managers which use epochs, this contains the epoch
3694 of the package (an integer). If unavailable, this is returned
3695 as 0.
3696 "app2_version"
3698 The version string of the application or package. If
3699 unavailable this is returned as an empty string "".
3700 "app2_release"
3702 The release string of the application or package, for package
3703 managers that use this. If unavailable this is returned as an
3704 empty string "".
3705 "app2_arch"
3707 The architecture string of the application or package, for
3708 package managers that use this. If unavailable this is
3709 returned as an empty string "".
3710 "app2_install_path"
3712 The installation path of the application (on operating systems
3713 such as Windows which use installation paths). This path is in
3714 the format used by the guest operating system, it is not a
3715 libguestfs path.
3716 If unavailable this is returned as an empty string "".
3718 "app2_trans_path"
3720 The install path translated into a libguestfs path. If
3721 unavailable this is returned as an empty string "".
3722 "app2_publisher"
3724 The name of the publisher of the application, for package
3725 managers that use this. If unavailable this is returned as an
3726 empty string "".
3727 "app2_url"
3729 The URL (eg. upstream URL) of the application. If unavailable
3730 this is returned as an empty string "".
3731 "app2_source_package"
3733 For packaging systems which support this, the name of the
3734 source package. If unavailable this is returned as an empty
3735 string "".
3736 "app2_summary"
3738 A short (usually one line) description of the application or
3739 package. If unavailable this is returned as an empty string
3740 "".
3741 "app2_description"
3743 A longer description of the application or package. If
3744 unavailable this is returned as an empty string "".
3745 Please read "INSPECTION" in guestfs(3) for more details.
3747 @roots = $g->inspect_os ();
3749 This function uses other libguestfs functions and certain
3750 heuristics to inspect the disk(s) (usually disks belonging to a
3751 virtual machine), looking for operating systems.
3752 The list returned is empty if no operating systems were found.
3754 If one operating system was found, then this returns a list with a
3756 single element, which is the name of the root filesystem of this
3757 operating system. It is also possible for this function to return
3758 a list containing more than one element, indicating a dual-boot or
3759 multi-boot virtual machine, with each element being the root
3760 filesystem of one of the operating systems.
3761 You can pass the root string(s) returned to other
3763 "$g->inspect_get_*" functions in order to query further information
3764 about each operating system, such as the name and version.
3765 This function uses other libguestfs features such as "$g->mount_ro"
3767 and "$g->umount_all" in order to mount and unmount filesystems and
3768 look at the contents. This should be called with no disks
3769 currently mounted. The function may also use Augeas, so any
3770 existing Augeas handle will be closed.
3771 This function cannot decrypt encrypted disks. The caller must do
3773 that first (supplying the necessary keys) if the disk is encrypted.
3774 Please read "INSPECTION" in guestfs(3) for more details.
3776 See also "$g->list_filesystems".
3778 $flag = $g->is_blockdev ($path [, followsymlinks => $followsymlinks]);
3780 This returns "true" if and only if there is a block device with the
3781 given "path" name.
3782 If the optional flag "followsymlinks" is true, then a symlink (or
3784 chain of symlinks) that ends with a block device also causes the
3785 function to return true.
3786 This call only looks at files within the guest filesystem.
3788 Libguestfs partitions and block devices (eg. /dev/sda) cannot be
3789 used as the "path" parameter of this call.
3790 See also "$g->stat".
3792 $flag = $g->is_blockdev_opts ($path [, followsymlinks =>
3794 $followsymlinks]);
3795 This is an alias of "is_blockdev".
3796 $busy = $g->is_busy ();
3798 This always returns false. This function is deprecated with no
3799 replacement. Do not use this function.
3800 For more information on states, see guestfs(3).
3802 $flag = $g->is_chardev ($path [, followsymlinks => $followsymlinks]);
3804 This returns "true" if and only if there is a character device with
3805 the given "path" name.
3806 If the optional flag "followsymlinks" is true, then a symlink (or
3808 chain of symlinks) that ends with a chardev also causes the
3809 function to return true.
3810 See also "$g->stat".
3812 $flag = $g->is_chardev_opts ($path [, followsymlinks =>
3814 $followsymlinks]);
3815 This is an alias of "is_chardev".
3816 $config = $g->is_config ();
3818 This returns true iff this handle is being configured (in the
3819 "CONFIG" state).
3820 For more information on states, see guestfs(3).
3822 $dirflag = $g->is_dir ($path [, followsymlinks => $followsymlinks]);
3824 This returns "true" if and only if there is a directory with the
3825 given "path" name. Note that it returns false for other objects
3826 like files.
3827 If the optional flag "followsymlinks" is true, then a symlink (or
3829 chain of symlinks) that ends with a directory also causes the
3830 function to return true.
3831 See also "$g->stat".
3833 $dirflag = $g->is_dir_opts ($path [, followsymlinks =>
3835 $followsymlinks]);
3836 This is an alias of "is_dir".
3837 $flag = $g->is_fifo ($path [, followsymlinks => $followsymlinks]);
3839 This returns "true" if and only if there is a FIFO (named pipe)
3840 with the given "path" name.
3841 If the optional flag "followsymlinks" is true, then a symlink (or
3843 chain of symlinks) that ends with a FIFO also causes the function
3844 to return true.
3845 See also "$g->stat".
3847 $flag = $g->is_fifo_opts ($path [, followsymlinks => $followsymlinks]);
3849 This is an alias of "is_fifo".
3850 $fileflag = $g->is_file ($path [, followsymlinks => $followsymlinks]);
3852 This returns "true" if and only if there is a regular file with the
3853 given "path" name. Note that it returns false for other objects
3854 like directories.
3855 If the optional flag "followsymlinks" is true, then a symlink (or
3857 chain of symlinks) that ends with a file also causes the function
3858 to return true.
3859 See also "$g->stat".
3861 $fileflag = $g->is_file_opts ($path [, followsymlinks =>
3863 $followsymlinks]);
3864 This is an alias of "is_file".
3865 $launching = $g->is_launching ();
3867 This returns true iff this handle is launching the subprocess (in
3868 the "LAUNCHING" state).
3869 For more information on states, see guestfs(3).
3871 $lvflag = $g->is_lv ($mountable);
3873 This command tests whether "mountable" is a logical volume, and
3874 returns true iff this is the case.
3875 $ready = $g->is_ready ();
3877 This returns true iff this handle is ready to accept commands (in
3878 the "READY" state).
3879 For more information on states, see guestfs(3).
3881 $flag = $g->is_socket ($path [, followsymlinks => $followsymlinks]);
3883 This returns "true" if and only if there is a Unix domain socket
3884 with the given "path" name.
3885 If the optional flag "followsymlinks" is true, then a symlink (or
3887 chain of symlinks) that ends with a socket also causes the function
3888 to return true.
3889 See also "$g->stat".
3891 $flag = $g->is_socket_opts ($path [, followsymlinks =>
3893 $followsymlinks]);
3894 This is an alias of "is_socket".
3895 $flag = $g->is_symlink ($path);
3897 This returns "true" if and only if there is a symbolic link with
3898 the given "path" name.
3899 See also "$g->stat".
3901 $flag = $g->is_whole_device ($device);
3903 This returns "true" if and only if "device" refers to a whole block
3904 device. That is, not a partition or a logical device.
3905 $zeroflag = $g->is_zero ($path);
3907 This returns true iff the file exists and the file is empty or it
3908 contains all zero bytes.
3909 $zeroflag = $g->is_zero_device ($device);
3911 This returns true iff the device exists and contains all zero
3912 bytes.
3913 Note that for large devices this can take a long time to run.
3915 %isodata = $g->isoinfo ($isofile);
3917 This is the same as "$g->isoinfo_device" except that it works for
3918 an ISO file located inside some other mounted filesystem. Note
3919 that in the common case where you have added an ISO file as a
3920 libguestfs device, you would not call this. Instead you would call
3921 "$g->isoinfo_device".
3922 %isodata = $g->isoinfo_device ($device);
3924 "device" is an ISO device. This returns a struct of information
3925 read from the primary volume descriptor (the ISO equivalent of the
3926 superblock) of the device.
3927 Usually it is more efficient to use the isoinfo(1) command with the
3929 -d option on the host to analyze ISO files, instead of going
3930 through libguestfs.
3931 For information on the primary volume descriptor fields, see
3933 <http://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor>
3934 $g->journal_close ();
3936 Close the journal handle.
3937 This function depends on the feature "journal". See also
3939 "$g->feature-available".
3940 @fields = $g->journal_get ();
3942 Read the current journal entry. This returns all the fields in the
3943 journal as a set of "(attrname, attrval)" pairs. The "attrname" is
3944 the field name (a string).
3945 The "attrval" is the field value (a binary blob, often but not
3947 always a string). Please note that "attrval" is a byte array, not
3948 a \0-terminated C string.
3949 The length of data may be truncated to the data threshold (see:
3951 "$g->journal_set_data_threshold",
3952 "$g->journal_get_data_threshold").
3953 If you set the data threshold to unlimited (0) then this call can
3955 read a journal entry of any size, ie. it is not limited by the
3956 libguestfs protocol.
3957 This function depends on the feature "journal". See also
3959 "$g->feature-available".
3960 $threshold = $g->journal_get_data_threshold ();
3962 Get the current data threshold for reading journal entries. This
3963 is a hint to the journal that it may truncate data fields to this
3964 size when reading them (note also that it may not truncate them).
3965 If this returns 0, then the threshold is unlimited.
3966 See also "$g->journal_set_data_threshold".
3968 This function depends on the feature "journal". See also
3970 "$g->feature-available".
3971 $usec = $g->journal_get_realtime_usec ();
3973 Get the realtime (wallclock) timestamp of the current journal
3974 entry.
3975 This function depends on the feature "journal". See also
3977 "$g->feature-available".
3978 $more = $g->journal_next ();
3980 Move to the next journal entry. You have to call this at least
3981 once after opening the handle before you are able to read data.
3982 The returned boolean tells you if there are any more journal
3984 records to read. "true" means you can read the next record (eg.
3985 using "$g->journal_get"), and "false" means you have reached the
3986 end of the journal.
3987 This function depends on the feature "journal". See also
3989 "$g->feature-available".
3990 $g->journal_open ($directory);
3992 Open the systemd journal located in directory. Any previously
3993 opened journal handle is closed.
3994 The contents of the journal can be read using "$g->journal_next"
3996 and "$g->journal_get".
3997 After you have finished using the journal, you should close the
3999 handle by calling "$g->journal_close".
4000 This function depends on the feature "journal". See also
4002 "$g->feature-available".
4003 $g->journal_set_data_threshold ($threshold);
4005 Set the data threshold for reading journal entries. This is a hint
4006 to the journal that it may truncate data fields to this size when
4007 reading them (note also that it may not truncate them). If you set
4008 this to 0, then the threshold is unlimited.
4009 See also "$g->journal_get_data_threshold".
4011 This function depends on the feature "journal". See also
4013 "$g->feature-available".
4014 $rskip = $g->journal_skip ($skip);
4016 Skip forwards ("skip X 0") or backwards ("skip < 0") in the
4017 journal.
4018 The number of entries actually skipped is returned (note
4020 "rskip X 0"). If this is not the same as the absolute value of the
4021 skip parameter ("|skip|") you passed in then it means you have
4022 reached the end or the start of the journal.
4023 This function depends on the feature "journal". See also
4025 "$g->feature-available".
4026 $g->kill_subprocess ();
4028 This kills the hypervisor.
4029 Do not call this. See: "$g->shutdown" instead.
4031 This function is deprecated. In new code, use the "shutdown" call
4033 instead.
4034 Deprecated functions will not be removed from the API, but the fact
4036 that they are deprecated indicates that there are problems with
4037 correct use of these functions.
4038 $g->launch ();
4040 You should call this after configuring the handle (eg. adding
4041 drives) but before performing any actions.
4042 Do not call "$g->launch" twice on the same handle. Although it
4044 will not give an error (for historical reasons), the precise
4045 behaviour when you do this is not well defined. Handles are very
4046 cheap to create, so create a new one for each launch.
4047 $g->lchown ($owner, $group, $path);
4049 Change the file owner to "owner" and group to "group". This is
4050 like "$g->chown" but if "path" is a symlink then the link itself is
4051 changed, not the target.
4052 Only numeric uid and gid are supported. If you want to use names,
4054 you will need to locate and parse the password file yourself
4055 (Augeas support makes this relatively easy).
4056 $g->ldmtool_create_all ();
4058 This function scans all block devices looking for Windows dynamic
4059 disk volumes and partitions, and creates devices for any that were
4060 found.
4061 Call "$g->list_ldm_volumes" and "$g->list_ldm_partitions" to return
4063 all devices.
4064 Note that you don't normally need to call this explicitly, since it
4066 is done automatically at "$g->launch" time. However you might want
4067 to call this function if you have hotplugged disks or have just
4068 created a Windows dynamic disk.
4069 This function depends on the feature "ldm". See also
4071 "$g->feature-available".
4072 @disks = $g->ldmtool_diskgroup_disks ($diskgroup);
4074 Return the disks in a Windows dynamic disk group. The "diskgroup"
4075 parameter should be the GUID of a disk group, one element from the
4076 list returned by "$g->ldmtool_scan".
4077 This function depends on the feature "ldm". See also
4079 "$g->feature-available".
4080 $name = $g->ldmtool_diskgroup_name ($diskgroup);
4082 Return the name of a Windows dynamic disk group. The "diskgroup"
4083 parameter should be the GUID of a disk group, one element from the
4084 list returned by "$g->ldmtool_scan".
4085 This function depends on the feature "ldm". See also
4087 "$g->feature-available".
4088 @volumes = $g->ldmtool_diskgroup_volumes ($diskgroup);
4090 Return the volumes in a Windows dynamic disk group. The
4091 "diskgroup" parameter should be the GUID of a disk group, one
4092 element from the list returned by "$g->ldmtool_scan".
4093 This function depends on the feature "ldm". See also
4095 "$g->feature-available".
4096 $g->ldmtool_remove_all ();
4098 This is essentially the opposite of "$g->ldmtool_create_all". It
4099 removes the device mapper mappings for all Windows dynamic disk
4100 volumes
4101 This function depends on the feature "ldm". See also
4103 "$g->feature-available".
4104 @guids = $g->ldmtool_scan ();
4106 This function scans for Windows dynamic disks. It returns a list
4107 of identifiers (GUIDs) for all disk groups that were found. These
4108 identifiers can be passed to other "$g->ldmtool_*" functions.
4109 This function scans all block devices. To scan a subset of block
4111 devices, call "$g->ldmtool_scan_devices" instead.
4112 This function depends on the feature "ldm". See also
4114 "$g->feature-available".
4115 @guids = $g->ldmtool_scan_devices (\@devices);
4117 This function scans for Windows dynamic disks. It returns a list
4118 of identifiers (GUIDs) for all disk groups that were found. These
4119 identifiers can be passed to other "$g->ldmtool_*" functions.
4120 The parameter "devices" is a list of block devices which are
4122 scanned. If this list is empty, all block devices are scanned.
4123 This function depends on the feature "ldm". See also
4125 "$g->feature-available".
4126 $hint = $g->ldmtool_volume_hint ($diskgroup, $volume);
4128 Return the hint field of the volume named "volume" in the disk
4129 group with GUID "diskgroup". This may not be defined, in which
4130 case the empty string is returned. The hint field is often, though
4131 not always, the name of a Windows drive, eg. "E:".
4132 This function depends on the feature "ldm". See also
4134 "$g->feature-available".
4135 @partitions = $g->ldmtool_volume_partitions ($diskgroup, $volume);
4137 Return the list of partitions in the volume named "volume" in the
4138 disk group with GUID "diskgroup".
4139 This function depends on the feature "ldm". See also
4141 "$g->feature-available".
4142 $voltype = $g->ldmtool_volume_type ($diskgroup, $volume);
4144 Return the type of the volume named "volume" in the disk group with
4145 GUID "diskgroup".
4146 Possible volume types that can be returned here include: "simple",
4148 "spanned", "striped", "mirrored", "raid5". Other types may also be
4149 returned.
4150 This function depends on the feature "ldm". See also
4152 "$g->feature-available".
4153 $xattr = $g->lgetxattr ($path, $name);
4155 Get a single extended attribute from file "path" named "name". If
4156 "path" is a symlink, then this call returns an extended attribute
4157 from the symlink.
4158 Normally it is better to get all extended attributes from a file in
4160 one go by calling "$g->getxattrs". However some Linux filesystem
4161 implementations are buggy and do not provide a way to list out
4162 attributes. For these filesystems (notably ntfs-3g) you have to
4163 know the names of the extended attributes you want in advance and
4164 call this function.
4165 Extended attribute values are blobs of binary data. If there is no
4167 extended attribute named "name", this returns an error.
4168 See also: "$g->lgetxattrs", "$g->getxattr", attr(5).
4170 This function depends on the feature "linuxxattrs". See also
4172 "$g->feature-available".
4173 @xattrs = $g->lgetxattrs ($path);
4175 This is the same as "$g->getxattrs", but if "path" is a symbolic
4176 link, then it returns the extended attributes of the link itself.
4177 This function depends on the feature "linuxxattrs". See also
4179 "$g->feature-available".
4180 @devices = $g->list_devices ();
4182 List all the block devices.
4183 The full block device names are returned, eg. /dev/sda.
4185 See also "$g->list_filesystems".
4187 %labels = $g->list_disk_labels ();
4189 If you add drives using the optional "label" parameter of
4190 "$g->add_drive_opts", you can use this call to map between disk
4191 labels, and raw block device and partition names (like /dev/sda and
4192 /dev/sda1).
4193 This returns a hashtable, where keys are the disk labels (without
4195 the /dev/disk/guestfs prefix), and the values are the full raw
4196 block device and partition names (eg. /dev/sda and /dev/sda1).
4197 @devices = $g->list_dm_devices ();
4199 List all device mapper devices.
4200 The returned list contains /dev/mapper/* devices, eg. ones created
4202 by a previous call to "$g->luks_open".
4203 Device mapper devices which correspond to logical volumes are not
4205 returned in this list. Call "$g->lvs" if you want to list logical
4206 volumes.
4207 %fses = $g->list_filesystems ();
4209 This inspection command looks for filesystems on partitions, block
4210 devices and logical volumes, returning a list of "mountables"
4211 containing filesystems and their type.
4212 The return value is a hash, where the keys are the devices
4214 containing filesystems, and the values are the filesystem types.
4215 For example:
4216 "/dev/sda1" => "ntfs"
4218 "/dev/sda2" => "ext2"
4219 "/dev/vg_guest/lv_root" => "ext4"
4220 "/dev/vg_guest/lv_swap" => "swap"
4221 The key is not necessarily a block device. It may also be an opaque
4223 XmountableX string which can be passed to "$g->mount".
4224 The value can have the special value "unknown", meaning the content
4226 of the device is undetermined or empty. "swap" means a Linux swap
4227 partition.
4228 In libguestfs X 1.36 this command ran other libguestfs commands,
4230 which might have included "$g->mount" and "$g->umount", and
4231 therefore you had to use this soon after launch and only when
4232 nothing else was mounted. This restriction is removed in
4233 libguestfs X 1.38.
4234 Not all of the filesystems returned will be mountable. In
4236 particular, swap partitions are returned in the list. Also this
4237 command does not check that each filesystem found is valid and
4238 mountable, and some filesystems might be mountable but require
4239 special options. Filesystems may not all belong to a single
4240 logical operating system (use "$g->inspect_os" to look for OSes).
4241 @devices = $g->list_ldm_partitions ();
4243 This function returns all Windows dynamic disk partitions that were
4244 found at launch time. It returns a list of device names.
4245 This function depends on the feature "ldm". See also
4247 "$g->feature-available".
4248 @devices = $g->list_ldm_volumes ();
4250 This function returns all Windows dynamic disk volumes that were
4251 found at launch time. It returns a list of device names.
4252 This function depends on the feature "ldm". See also
4254 "$g->feature-available".
4255 @devices = $g->list_md_devices ();
4257 List all Linux md devices.
4258 @partitions = $g->list_partitions ();
4260 List all the partitions detected on all block devices.
4261 The full partition device names are returned, eg. /dev/sda1
4263 This does not return logical volumes. For that you will need to
4265 call "$g->lvs".
4266 See also "$g->list_filesystems".
4268 $listing = $g->ll ($directory);
4270 List the files in directory (relative to the root directory, there
4271 is no cwd) in the format of 'ls -la'.
4272 This command is mostly useful for interactive sessions. It is not
4274 intended that you try to parse the output string.
4275 $listing = $g->llz ($directory);
4277 List the files in directory in the format of 'ls -laZ'.
4278 This command is mostly useful for interactive sessions. It is not
4280 intended that you try to parse the output string.
4281 This function is deprecated. In new code, use the "lgetxattrs"
4283 call instead.
4284 Deprecated functions will not be removed from the API, but the fact
4286 that they are deprecated indicates that there are problems with
4287 correct use of these functions.
4288 $g->ln ($target, $linkname);
4290 This command creates a hard link using the "ln" command.
4291 $g->ln_f ($target, $linkname);
4293 This command creates a hard link using the "ln -f" command. The -f
4294 option removes the link ("linkname") if it exists already.
4295 $g->ln_s ($target, $linkname);
4297 This command creates a symbolic link using the "ln -s" command.
4298 $g->ln_sf ($target, $linkname);
4300 This command creates a symbolic link using the "ln -sf" command,
4301 The -f option removes the link ("linkname") if it exists already.
4302 $g->lremovexattr ($xattr, $path);
4304 This is the same as "$g->removexattr", but if "path" is a symbolic
4305 link, then it removes an extended attribute of the link itself.
4306 This function depends on the feature "linuxxattrs". See also
4308 "$g->feature-available".
4309 @listing = $g->ls ($directory);
4311 List the files in directory (relative to the root directory, there
4312 is no cwd). The '.' and '..' entries are not returned, but hidden
4313 files are shown.
4314 $g->ls0 ($dir, $filenames);
4316 This specialized command is used to get a listing of the filenames
4317 in the directory "dir". The list of filenames is written to the
4318 local file filenames (on the host).
4319 In the output file, the filenames are separated by "\0" characters.
4321 "." and ".." are not returned. The filenames are not sorted.
4323 $g->lsetxattr ($xattr, $val, $vallen, $path);
4325 This is the same as "$g->setxattr", but if "path" is a symbolic
4326 link, then it sets an extended attribute of the link itself.
4327 This function depends on the feature "linuxxattrs". See also
4329 "$g->feature-available".
4330 %statbuf = $g->lstat ($path);
4332 Returns file information for the given "path".
4333 This is the same as "$g->stat" except that if "path" is a symbolic
4335 link, then the link is stat-ed, not the file it refers to.
4336 This is the same as the lstat(2) system call.
4338 This function is deprecated. In new code, use the "lstatns" call
4340 instead.
4341 Deprecated functions will not be removed from the API, but the fact
4343 that they are deprecated indicates that there are problems with
4344 correct use of these functions.
4345 @statbufs = $g->lstatlist ($path, \@names);
4347 This call allows you to perform the "$g->lstat" operation on
4348 multiple files, where all files are in the directory "path".
4349 "names" is the list of files from this directory.
4350 On return you get a list of stat structs, with a one-to-one
4352 correspondence to the "names" list. If any name did not exist or
4353 could not be lstat'd, then the "st_ino" field of that structure is
4354 set to "-1".
4355 This call is intended for programs that want to efficiently list a
4357 directory contents without making many round-trips. See also
4358 "$g->lxattrlist" for a similarly efficient call for getting
4359 extended attributes.
4360 This function is deprecated. In new code, use the "lstatnslist"
4362 call instead.
4363 Deprecated functions will not be removed from the API, but the fact
4365 that they are deprecated indicates that there are problems with
4366 correct use of these functions.
4367 %statbuf = $g->lstatns ($path);
4369 Returns file information for the given "path".
4370 This is the same as "$g->statns" except that if "path" is a
4372 symbolic link, then the link is stat-ed, not the file it refers to.
4373 This is the same as the lstat(2) system call.
4375 @statbufs = $g->lstatnslist ($path, \@names);
4377 This call allows you to perform the "$g->lstatns" operation on
4378 multiple files, where all files are in the directory "path".
4379 "names" is the list of files from this directory.
4380 On return you get a list of stat structs, with a one-to-one
4382 correspondence to the "names" list. If any name did not exist or
4383 could not be lstat'd, then the "st_ino" field of that structure is
4384 set to "-1".
4385 This call is intended for programs that want to efficiently list a
4387 directory contents without making many round-trips. See also
4388 "$g->lxattrlist" for a similarly efficient call for getting
4389 extended attributes.
4390 $g->luks_add_key ($device, $key, $newkey, $keyslot);
4392 This command adds a new key on LUKS device "device". "key" is any
4393 existing key, and is used to access the device. "newkey" is the
4394 new key to add. "keyslot" is the key slot that will be replaced.
4395 Note that if "keyslot" already contains a key, then this command
4397 will fail. You have to use "$g->luks_kill_slot" first to remove
4398 that key.
4399 This function depends on the feature "luks". See also
4401 "$g->feature-available".
4402 $g->luks_close ($device);
4404 This closes a LUKS device that was created earlier by
4405 "$g->luks_open" or "$g->luks_open_ro". The "device" parameter must
4406 be the name of the LUKS mapping device (ie. /dev/mapper/mapname)
4407 and not the name of the underlying block device.
4408 This function depends on the feature "luks". See also
4410 "$g->feature-available".
4411 $g->luks_format ($device, $key, $keyslot);
4413 This command erases existing data on "device" and formats the
4414 device as a LUKS encrypted device. "key" is the initial key, which
4415 is added to key slot "slot". (LUKS supports 8 key slots, numbered
4416 0-7).
4417 This function depends on the feature "luks". See also
4419 "$g->feature-available".
4420 $g->luks_format_cipher ($device, $key, $keyslot, $cipher);
4422 This command is the same as "$g->luks_format" but it also allows
4423 you to set the "cipher" used.
4424 This function depends on the feature "luks". See also
4426 "$g->feature-available".
4427 $g->luks_kill_slot ($device, $key, $keyslot);
4429 This command deletes the key in key slot "keyslot" from the
4430 encrypted LUKS device "device". "key" must be one of the other
4431 keys.
4432 This function depends on the feature "luks". See also
4434 "$g->feature-available".
4435 $g->luks_open ($device, $key, $mapname);
4437 This command opens a block device which has been encrypted
4438 according to the Linux Unified Key Setup (LUKS) standard.
4439 "device" is the encrypted block device or partition.
4441 The caller must supply one of the keys associated with the LUKS
4443 block device, in the "key" parameter.
4444 This creates a new block device called /dev/mapper/mapname. Reads
4446 and writes to this block device are decrypted from and encrypted to
4447 the underlying "device" respectively.
4448 If this block device contains LVM volume groups, then calling
4450 "$g->vgscan" followed by "$g->vg_activate_all" will make them
4451 visible.
4452 Use "$g->list_dm_devices" to list all device mapper devices.
4454 This function depends on the feature "luks". See also
4456 "$g->feature-available".
4457 $g->luks_open_ro ($device, $key, $mapname);
4459 This is the same as "$g->luks_open" except that a read-only mapping
4460 is created.
4461 This function depends on the feature "luks". See also
4463 "$g->feature-available".
4464 $g->lvcreate ($logvol, $volgroup, $mbytes);
4466 This creates an LVM logical volume called "logvol" on the volume
4467 group "volgroup", with "size" megabytes.
4468 This function depends on the feature "lvm2". See also
4470 "$g->feature-available".
4471 $g->lvcreate_free ($logvol, $volgroup, $percent);
4473 Create an LVM logical volume called /dev/volgroup/logvol, using
4474 approximately "percent" % of the free space remaining in the volume
4475 group. Most usefully, when "percent" is 100 this will create the
4476 largest possible LV.
4477 This function depends on the feature "lvm2". See also
4479 "$g->feature-available".
4480 $lv = $g->lvm_canonical_lv_name ($lvname);
4482 This converts alternative naming schemes for LVs that you might
4483 find to the canonical name. For example, /dev/mapper/VG-LV is
4484 converted to /dev/VG/LV.
4485 This command returns an error if the "lvname" parameter does not
4487 refer to a logical volume.
4488 See also "$g->is_lv", "$g->canonical_device_name".
4490 $g->lvm_clear_filter ();
4492 This undoes the effect of "$g->lvm_set_filter". LVM will be able
4493 to see every block device.
4494 This command also clears the LVM cache and performs a volume group
4496 scan.
4497 $g->lvm_remove_all ();
4499 This command removes all LVM logical volumes, volume groups and
4500 physical volumes.
4501 This function depends on the feature "lvm2". See also
4503 "$g->feature-available".
4504 $g->lvm_set_filter (\@devices);
4506 This sets the LVM device filter so that LVM will only be able to
4507 "see" the block devices in the list "devices", and will ignore all
4508 other attached block devices.
4509 Where disk image(s) contain duplicate PVs or VGs, this command is
4511 useful to get LVM to ignore the duplicates, otherwise LVM can get
4512 confused. Note also there are two types of duplication possible:
4513 either cloned PVs/VGs which have identical UUIDs; or VGs that are
4514 not cloned but just happen to have the same name. In normal
4515 operation you cannot create this situation, but you can do it
4516 outside LVM, eg. by cloning disk images or by bit twiddling inside
4517 the LVM metadata.
4518 This command also clears the LVM cache and performs a volume group
4520 scan.
4521 You can filter whole block devices or individual partitions.
4523 You cannot use this if any VG is currently in use (eg. contains a
4525 mounted filesystem), even if you are not filtering out that VG.
4526 This function depends on the feature "lvm2". See also
4528 "$g->feature-available".
4529 $g->lvremove ($device);
4531 Remove an LVM logical volume "device", where "device" is the path
4532 to the LV, such as /dev/VG/LV.
4533 You can also remove all LVs in a volume group by specifying the VG
4535 name, /dev/VG.
4536 This function depends on the feature "lvm2". See also
4538 "$g->feature-available".
4539 $g->lvrename ($logvol, $newlogvol);
4541 Rename a logical volume "logvol" with the new name "newlogvol".
4542 $g->lvresize ($device, $mbytes);
4544 This resizes (expands or shrinks) an existing LVM logical volume to
4545 "mbytes". When reducing, data in the reduced part is lost.
4546 This function depends on the feature "lvm2". See also
4548 "$g->feature-available".
4549 $g->lvresize_free ($lv, $percent);
4551 This expands an existing logical volume "lv" so that it fills "pc"%
4552 of the remaining free space in the volume group. Commonly you
4553 would call this with pc = 100 which expands the logical volume as
4554 much as possible, using all remaining free space in the volume
4555 group.
4556 This function depends on the feature "lvm2". See also
4558 "$g->feature-available".
4559 @logvols = $g->lvs ();
4561 List all the logical volumes detected. This is the equivalent of
4562 the lvs(8) command.
4563 This returns a list of the logical volume device names (eg.
4565 /dev/VolGroup00/LogVol00).
4566 See also "$g->lvs_full", "$g->list_filesystems".
4568 This function depends on the feature "lvm2". See also
4570 "$g->feature-available".
4571 @logvols = $g->lvs_full ();
4573 List all the logical volumes detected. This is the equivalent of
4574 the lvs(8) command. The "full" version includes all fields.
4575 This function depends on the feature "lvm2". See also
4577 "$g->feature-available".
4578 $uuid = $g->lvuuid ($device);
4580 This command returns the UUID of the LVM LV "device".
4581 @xattrs = $g->lxattrlist ($path, \@names);
4583 This call allows you to get the extended attributes of multiple
4584 files, where all files are in the directory "path". "names" is the
4585 list of files from this directory.
4586 On return you get a flat list of xattr structs which must be
4588 interpreted sequentially. The first xattr struct always has a
4589 zero-length "attrname". "attrval" in this struct is zero-length to
4590 indicate there was an error doing "lgetxattr" for this file, or is
4591 a C string which is a decimal number (the number of following
4592 attributes for this file, which could be "0"). Then after the
4593 first xattr struct are the zero or more attributes for the first
4594 named file. This repeats for the second and subsequent files.
4595 This call is intended for programs that want to efficiently list a
4597 directory contents without making many round-trips. See also
4598 "$g->lstatlist" for a similarly efficient call for getting standard
4599 stats.
4600 This function depends on the feature "linuxxattrs". See also
4602 "$g->feature-available".
4603 $disks = $g->max_disks ();
4605 Return the maximum number of disks that may be added to a handle
4606 (eg. by "$g->add_drive_opts" and similar calls).
4607 This function was added in libguestfs 1.19.7. In previous versions
4609 of libguestfs the limit was 25.
4610 See "MAXIMUM NUMBER OF DISKS" in guestfs(3) for additional
4612 information on this topic.
4613 $g->md_create ($name, \@devices [, missingbitmap => $missingbitmap] [,
4615 nrdevices => $nrdevices] [, spare => $spare] [, chunk => $chunk] [,
4616 level => $level]);
4617 Create a Linux md (RAID) device named "name" on the devices in the
4618 list "devices".
4619 The optional parameters are:
4621 "missingbitmap"
4623 A bitmap of missing devices. If a bit is set it means that a
4624 missing device is added to the array. The least significant
4625 bit corresponds to the first device in the array.
4626 As examples:
4628 If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
4630 resulting array would be "[<missing>, "/dev/sda"]".
4631 If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
4633 resulting array would be "["/dev/sda", <missing>]".
4634 This defaults to 0 (no missing devices).
4636 The length of "devices" + the number of bits set in
4638 "missingbitmap" must equal "nrdevices" + "spare".
4639 "nrdevices"
4641 The number of active RAID devices.
4642 If not set, this defaults to the length of "devices" plus the
4644 number of bits set in "missingbitmap".
4645 "spare"
4647 The number of spare devices.
4648 If not set, this defaults to 0.
4650 "chunk"
4652 The chunk size in bytes.
4653 "level"
4655 The RAID level, which can be one of: linear, raid0, 0, stripe,
4656 raid1, 1, mirror, raid4, 4, raid5, 5, raid6, 6, raid10, 10.
4657 Some of these are synonymous, and more levels may be added in
4658 future.
4659 If not set, this defaults to "raid1".
4661 This function depends on the feature "mdadm". See also
4663 "$g->feature-available".
4664 %info = $g->md_detail ($md);
4666 This command exposes the output of 'mdadm -DY <md>'. The following
4667 fields are usually present in the returned hash. Other fields may
4668 also be present.
4669 "level"
4671 The raid level of the MD device.
4672 "devices"
4674 The number of underlying devices in the MD device.
4675 "metadata"
4677 The metadata version used.
4678 "uuid"
4680 The UUID of the MD device.
4681 "name"
4683 The name of the MD device.
4684 This function depends on the feature "mdadm". See also
4686 "$g->feature-available".
4687 @devices = $g->md_stat ($md);
4689 This call returns a list of the underlying devices which make up
4690 the single software RAID array device "md".
4691 To get a list of software RAID devices, call "$g->list_md_devices".
4693 Each structure returned corresponds to one device along with
4695 additional status information:
4696 "mdstat_device"
4698 The name of the underlying device.
4699 "mdstat_index"
4701 The index of this device within the array.
4702 "mdstat_flags"
4704 Flags associated with this device. This is a string containing
4705 (in no specific order) zero or more of the following flags:
4706 "W" write-mostly
4708 "F" device is faulty
4710 "S" device is a RAID spare
4712 "R" replacement
4714 This function depends on the feature "mdadm". See also
4716 "$g->feature-available".
4717 $g->md_stop ($md);
4719 This command deactivates the MD array named "md". The device is
4720 stopped, but it is not destroyed or zeroed.
4721 This function depends on the feature "mdadm". See also
4723 "$g->feature-available".
4724 $g->mkdir ($path);
4726 Create a directory named "path".
4727 $g->mkdir_mode ($path, $mode);
4729 This command creates a directory, setting the initial permissions
4730 of the directory to "mode".
4731 For common Linux filesystems, the actual mode which is set will be
4733 "mode & ~umask & 01777". Non-native-Linux filesystems may
4734 interpret the mode in other ways.
4735 See also "$g->mkdir", "$g->umask"
4737 $g->mkdir_p ($path);
4739 Create a directory named "path", creating any parent directories as
4740 necessary. This is like the "mkdir -p" shell command.
4741 $dir = $g->mkdtemp ($tmpl);
4743 This command creates a temporary directory. The "tmpl" parameter
4744 should be a full pathname for the temporary directory name with the
4745 final six characters being "XXXXXX".
4746 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the
4748 second one being suitable for Windows filesystems.
4749 The name of the temporary directory that was created is returned.
4751 The temporary directory is created with mode 0700 and is owned by
4753 root.
4754 The caller is responsible for deleting the temporary directory and
4756 its contents after use.
4757 See also: mkdtemp(3)
4759 $g->mke2fs ($device [, blockscount => $blockscount] [, blocksize =>
4761 $blocksize] [, fragsize => $fragsize] [, blockspergroup =>
4762 $blockspergroup] [, numberofgroups => $numberofgroups] [, bytesperinode
4763 => $bytesperinode] [, inodesize => $inodesize] [, journalsize =>
4764 $journalsize] [, numberofinodes => $numberofinodes] [, stridesize =>
4765 $stridesize] [, stripewidth => $stripewidth] [, maxonlineresize =>
4766 $maxonlineresize] [, reservedblockspercentage =>
4767 $reservedblockspercentage] [, mmpupdateinterval => $mmpupdateinterval]
4768 [, journaldevice => $journaldevice] [, label => $label] [,
4769 lastmounteddir => $lastmounteddir] [, creatoros => $creatoros] [,
4770 fstype => $fstype] [, usagetype => $usagetype] [, uuid => $uuid] [,
4771 forcecreate => $forcecreate] [, writesbandgrouponly =>
4772 $writesbandgrouponly] [, lazyitableinit => $lazyitableinit] [,
4773 lazyjournalinit => $lazyjournalinit] [, testfs => $testfs] [, discard
4774 => $discard] [, quotatype => $quotatype] [, extent => $extent] [,
4775 filetype => $filetype] [, flexbg => $flexbg] [, hasjournal =>
4776 $hasjournal] [, journaldev => $journaldev] [, largefile => $largefile]
4777 [, quota => $quota] [, resizeinode => $resizeinode] [, sparsesuper =>
4778 $sparsesuper] [, uninitbg => $uninitbg]);
4779 "mke2fs" is used to create an ext2, ext3, or ext4 filesystem on
4780 "device".
4781 The optional "blockscount" is the size of the filesystem in blocks.
4783 If omitted it defaults to the size of "device". Note if the
4784 filesystem is too small to contain a journal, "mke2fs" will
4785 silently create an ext2 filesystem instead.
4786 $g->mke2fs_J ($fstype, $blocksize, $device, $journal);
4788 This creates an ext2/3/4 filesystem on "device" with an external
4789 journal on "journal". It is equivalent to the command:
4790 mke2fs -t fstype -b blocksize -J device=<journal> <device>
4792 See also "$g->mke2journal".
4794 This function is deprecated. In new code, use the "mke2fs" call
4796 instead.
4797 Deprecated functions will not be removed from the API, but the fact
4799 that they are deprecated indicates that there are problems with
4800 correct use of these functions.
4801 $g->mke2fs_JL ($fstype, $blocksize, $device, $label);
4803 This creates an ext2/3/4 filesystem on "device" with an external
4804 journal on the journal labeled "label".
4805 See also "$g->mke2journal_L".
4807 This function is deprecated. In new code, use the "mke2fs" call
4809 instead.
4810 Deprecated functions will not be removed from the API, but the fact
4812 that they are deprecated indicates that there are problems with
4813 correct use of these functions.
4814 $g->mke2fs_JU ($fstype, $blocksize, $device, $uuid);
4816 This creates an ext2/3/4 filesystem on "device" with an external
4817 journal on the journal with UUID "uuid".
4818 See also "$g->mke2journal_U".
4820 This function depends on the feature "linuxfsuuid". See also
4822 "$g->feature-available".
4823 This function is deprecated. In new code, use the "mke2fs" call
4825 instead.
4826 Deprecated functions will not be removed from the API, but the fact
4828 that they are deprecated indicates that there are problems with
4829 correct use of these functions.
4830 $g->mke2journal ($blocksize, $device);
4832 This creates an ext2 external journal on "device". It is
4833 equivalent to the command:
4834 mke2fs -O journal_dev -b blocksize device
4836 This function is deprecated. In new code, use the "mke2fs" call
4838 instead.
4839 Deprecated functions will not be removed from the API, but the fact
4841 that they are deprecated indicates that there are problems with
4842 correct use of these functions.
4843 $g->mke2journal_L ($blocksize, $label, $device);
4845 This creates an ext2 external journal on "device" with label
4846 "label".
4847 This function is deprecated. In new code, use the "mke2fs" call
4849 instead.
4850 Deprecated functions will not be removed from the API, but the fact
4852 that they are deprecated indicates that there are problems with
4853 correct use of these functions.
4854 $g->mke2journal_U ($blocksize, $uuid, $device);
4856 This creates an ext2 external journal on "device" with UUID "uuid".
4857 This function depends on the feature "linuxfsuuid". See also
4859 "$g->feature-available".
4860 This function is deprecated. In new code, use the "mke2fs" call
4862 instead.
4863 Deprecated functions will not be removed from the API, but the fact
4865 that they are deprecated indicates that there are problems with
4866 correct use of these functions.
4867 $g->mkfifo ($mode, $path);
4869 This call creates a FIFO (named pipe) called "path" with mode
4870 "mode". It is just a convenient wrapper around "$g->mknod".
4871 Unlike with "$g->mknod", "mode" must contain only permissions bits.
4873 The mode actually set is affected by the umask.
4875 This function depends on the feature "mknod". See also
4877 "$g->feature-available".
4878 $g->mkfs ($fstype, $device [, blocksize => $blocksize] [, features =>
4880 $features] [, inode => $inode] [, sectorsize => $sectorsize] [, label
4881 => $label]);
4882 This function creates a filesystem on "device". The filesystem
4883 type is "fstype", for example "ext3".
4884 The optional arguments are:
4886 "blocksize"
4888 The filesystem block size. Supported block sizes depend on the
4889 filesystem type, but typically they are 1024, 2048 or 4096 for
4890 Linux ext2/3 filesystems.
4891 For VFAT and NTFS the "blocksize" parameter is treated as the
4893 requested cluster size.
4894 For UFS block sizes, please see mkfs.ufs(8).
4896 "features"
4898 This passes the -O parameter to the external mkfs program.
4899 For certain filesystem types, this allows extra filesystem
4901 features to be selected. See mke2fs(8) and mkfs.ufs(8) for
4902 more details.
4903 You cannot use this optional parameter with the "gfs" or "gfs2"
4905 filesystem type.
4906 "inode"
4908 This passes the -I parameter to the external mke2fs(8) program
4909 which sets the inode size (only for ext2/3/4 filesystems at
4910 present).
4911 "sectorsize"
4913 This passes the -S parameter to external mkfs.ufs(8) program,
4914 which sets sector size for ufs filesystem.
4915 $g->mkfs_opts ($fstype, $device [, blocksize => $blocksize] [, features
4917 => $features] [, inode => $inode] [, sectorsize => $sectorsize] [,
4918 label => $label]);
4919 This is an alias of "mkfs".
4920 $g->mkfs_b ($fstype, $blocksize, $device);
4922 This call is similar to "$g->mkfs", but it allows you to control
4923 the block size of the resulting filesystem. Supported block sizes
4924 depend on the filesystem type, but typically they are 1024, 2048 or
4925 4096 only.
4926 For VFAT and NTFS the "blocksize" parameter is treated as the
4928 requested cluster size.
4929 This function is deprecated. In new code, use the "mkfs" call
4931 instead.
4932 Deprecated functions will not be removed from the API, but the fact
4934 that they are deprecated indicates that there are problems with
4935 correct use of these functions.
4936 $g->mkfs_btrfs (\@devices [, allocstart => $allocstart] [, bytecount =>
4938 $bytecount] [, datatype => $datatype] [, leafsize => $leafsize] [,
4939 label => $label] [, metadata => $metadata] [, nodesize => $nodesize] [,
4940 sectorsize => $sectorsize]);
4941 Create a btrfs filesystem, allowing all configurables to be set.
4942 For more information on the optional arguments, see mkfs.btrfs(8).
4943 Since btrfs filesystems can span multiple devices, this takes a
4945 non-empty list of devices.
4946 To create general filesystems, use "$g->mkfs".
4948 This function depends on the feature "btrfs". See also
4950 "$g->feature-available".
4951 $g->mklost_and_found ($mountpoint);
4953 Make the "lost+found" directory, normally in the root directory of
4954 an ext2/3/4 filesystem. "mountpoint" is the directory under which
4955 we try to create the "lost+found" directory.
4956 $g->mkmountpoint ($exemptpath);
4958 "$g->mkmountpoint" and "$g->rmmountpoint" are specialized calls
4959 that can be used to create extra mountpoints before mounting the
4960 first filesystem.
4961 These calls are only necessary in some very limited circumstances,
4963 mainly the case where you want to mount a mix of unrelated and/or
4964 read-only filesystems together.
4965 For example, live CDs often contain a "Russian doll" nest of
4967 filesystems, an ISO outer layer, with a squashfs image inside, with
4968 an ext2/3 image inside that. You can unpack this as follows in
4969 guestfish:
4970 add-ro Fedora-11-i686-Live.iso
4972 run
4973 mkmountpoint /cd
4974 mkmountpoint /sqsh
4975 mkmountpoint /ext3fs
4976 mount /dev/sda /cd
4977 mount-loop /cd/LiveOS/squashfs.img /sqsh
4978 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
4979 The inner filesystem is now unpacked under the /ext3fs mountpoint.
4981 "$g->mkmountpoint" is not compatible with "$g->umount_all". You
4983 may get unexpected errors if you try to mix these calls. It is
4984 safest to manually unmount filesystems and remove mountpoints after
4985 use.
4986 "$g->umount_all" unmounts filesystems by sorting the paths longest
4988 first, so for this to work for manual mountpoints, you must ensure
4989 that the innermost mountpoints have the longest pathnames, as in
4990 the example code above.
4991 For more details see
4993 <https://bugzilla.redhat.com/show_bug.cgi?id=599503>
4994 Autosync [see "$g->set_autosync", this is set by default on
4996 handles] can cause "$g->umount_all" to be called when the handle is
4997 closed which can also trigger these issues.
4998 $g->mknod ($mode, $devmajor, $devminor, $path);
5000 This call creates block or character special devices, or named
5001 pipes (FIFOs).
5002 The "mode" parameter should be the mode, using the standard
5004 constants. "devmajor" and "devminor" are the device major and
5005 minor numbers, only used when creating block and character special
5006 devices.
5007 Note that, just like mknod(2), the mode must be bitwise OR'd with
5009 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just
5010 creates a regular file). These constants are available in the
5011 standard Linux header files, or you can use "$g->mknod_b",
5012 "$g->mknod_c" or "$g->mkfifo" which are wrappers around this
5013 command which bitwise OR in the appropriate constant for you.
5014 The mode actually set is affected by the umask.
5016 This function depends on the feature "mknod". See also
5018 "$g->feature-available".
5019 $g->mknod_b ($mode, $devmajor, $devminor, $path);
5021 This call creates a block device node called "path" with mode
5022 "mode" and device major/minor "devmajor" and "devminor". It is
5023 just a convenient wrapper around "$g->mknod".
5024 Unlike with "$g->mknod", "mode" must contain only permissions bits.
5026 The mode actually set is affected by the umask.
5028 This function depends on the feature "mknod". See also
5030 "$g->feature-available".
5031 $g->mknod_c ($mode, $devmajor, $devminor, $path);
5033 This call creates a char device node called "path" with mode "mode"
5034 and device major/minor "devmajor" and "devminor". It is just a
5035 convenient wrapper around "$g->mknod".
5036 Unlike with "$g->mknod", "mode" must contain only permissions bits.
5038 The mode actually set is affected by the umask.
5040 This function depends on the feature "mknod". See also
5042 "$g->feature-available".
5043 $g->mksquashfs ($path, $filename [, compress => $compress] [, excludes
5045 => $excludes]);
5046 Create a squashfs filesystem for the specified "path".
5047 The optional "compress" flag controls compression. If not given,
5049 then the output compressed using "gzip". Otherwise one of the
5050 following strings may be given to select the compression type of
5051 the squashfs: "gzip", "lzma", "lzo", "lz4", "xz".
5052 The other optional arguments are:
5054 "excludes"
5056 A list of wildcards. Files are excluded if they match any of
5057 the wildcards.
5058 Please note that this API may fail when used to compress
5060 directories with large files, such as the resulting squashfs will
5061 be over 3GB big.
5062 This function depends on the feature "squashfs". See also
5064 "$g->feature-available".
5065 $g->mkswap ($device [, label => $label] [, uuid => $uuid]);
5067 Create a Linux swap partition on "device".
5068 The option arguments "label" and "uuid" allow you to set the label
5070 and/or UUID of the new swap partition.
5071 $g->mkswap_opts ($device [, label => $label] [, uuid => $uuid]);
5073 This is an alias of "mkswap".
5074 $g->mkswap_L ($label, $device);
5076 Create a swap partition on "device" with label "label".
5077 Note that you cannot attach a swap label to a block device (eg.
5079 /dev/sda), just to a partition. This appears to be a limitation of
5080 the kernel or swap tools.
5081 This function is deprecated. In new code, use the "mkswap" call
5083 instead.
5084 Deprecated functions will not be removed from the API, but the fact
5086 that they are deprecated indicates that there are problems with
5087 correct use of these functions.
5088 $g->mkswap_U ($uuid, $device);
5090 Create a swap partition on "device" with UUID "uuid".
5091 This function depends on the feature "linuxfsuuid". See also
5093 "$g->feature-available".
5094 This function is deprecated. In new code, use the "mkswap" call
5096 instead.
5097 Deprecated functions will not be removed from the API, but the fact
5099 that they are deprecated indicates that there are problems with
5100 correct use of these functions.
5101 $g->mkswap_file ($path);
5103 Create a swap file.
5104 This command just writes a swap file signature to an existing file.
5106 To create the file itself, use something like "$g->fallocate".
5107 $path = $g->mktemp ($tmpl [, suffix => $suffix]);
5109 This command creates a temporary file. The "tmpl" parameter should
5110 be a full pathname for the temporary directory name with the final
5111 six characters being "XXXXXX".
5112 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the
5114 second one being suitable for Windows filesystems.
5115 The name of the temporary file that was created is returned.
5117 The temporary file is created with mode 0600 and is owned by root.
5119 The caller is responsible for deleting the temporary file after
5121 use.
5122 If the optional "suffix" parameter is given, then the suffix (eg.
5124 ".txt") is appended to the temporary name.
5125 See also: "$g->mkdtemp".
5127 $g->modprobe ($modulename);
5129 This loads a kernel module in the appliance.
5130 This function depends on the feature "linuxmodules". See also
5132 "$g->feature-available".
5133 $g->mount ($mountable, $mountpoint);
5135 Mount a guest disk at a position in the filesystem. Block devices
5136 are named /dev/sda, /dev/sdb and so on, as they were added to the
5137 guest. If those block devices contain partitions, they will have
5138 the usual names (eg. /dev/sda1). Also LVM /dev/VG/LV-style names
5139 can be used, or XmountableX strings returned by
5140 "$g->list_filesystems" or "$g->inspect_get_mountpoints".
5141 The rules are the same as for mount(2): A filesystem must first be
5143 mounted on / before others can be mounted. Other filesystems can
5144 only be mounted on directories which already exist.
5145 The mounted filesystem is writable, if we have sufficient
5147 permissions on the underlying device.
5148 Before libguestfs 1.13.16, this call implicitly added the options
5150 "sync" and "noatime". The "sync" option greatly slowed writes and
5151 caused many problems for users. If your program might need to work
5152 with older versions of libguestfs, use "$g->mount_options" instead
5153 (using an empty string for the first parameter if you don't want
5154 any options).
5155 $g->mount_local ($localmountpoint [, readonly => $readonly] [, options
5157 => $options] [, cachetimeout => $cachetimeout] [, debugcalls =>
5158 $debugcalls]);
5159 This call exports the libguestfs-accessible filesystem to a local
5160 mountpoint (directory) called "localmountpoint". Ordinary reads
5161 and writes to files and directories under "localmountpoint" are
5162 redirected through libguestfs.
5163 If the optional "readonly" flag is set to true, then writes to the
5165 filesystem return error "EROFS".
5166 "options" is a comma-separated list of mount options. See
5168 guestmount(1) for some useful options.
5169 "cachetimeout" sets the timeout (in seconds) for cached directory
5171 entries. The default is 60 seconds. See guestmount(1) for further
5172 information.
5173 If "debugcalls" is set to true, then additional debugging
5175 information is generated for every FUSE call.
5176 When "$g->mount_local" returns, the filesystem is ready, but is not
5178 processing requests (access to it will block). You have to call
5179 "$g->mount_local_run" to run the main loop.
5180 See "MOUNT LOCAL" in guestfs(3) for full documentation.
5182 $g->mount_local_run ();
5184 Run the main loop which translates kernel calls to libguestfs
5185 calls.
5186 This should only be called after "$g->mount_local" returns
5188 successfully. The call will not return until the filesystem is
5189 unmounted.
5190 Note you must not make concurrent libguestfs calls on the same
5192 handle from another thread.
5193 You may call this from a different thread than the one which called
5195 "$g->mount_local", subject to the usual rules for threads and
5196 libguestfs (see "MULTIPLE HANDLES AND MULTIPLE THREADS" in
5197 guestfs(3)).
5198 See "MOUNT LOCAL" in guestfs(3) for full documentation.
5200 $g->mount_loop ($file, $mountpoint);
5202 This command lets you mount file (a filesystem image in a file) on
5203 a mount point. It is entirely equivalent to the command "mount -o
5204 loop file mountpoint".
5205 $g->mount_options ($options, $mountable, $mountpoint);
5207 This is the same as the "$g->mount" command, but it allows you to
5208 set the mount options as for the mount(8) -o flag.
5209 If the "options" parameter is an empty string, then no options are
5211 passed (all options default to whatever the filesystem uses).
5212 $g->mount_ro ($mountable, $mountpoint);
5214 This is the same as the "$g->mount" command, but it mounts the
5215 filesystem with the read-only (-o ro) flag.
5216 $g->mount_vfs ($options, $vfstype, $mountable, $mountpoint);
5218 This is the same as the "$g->mount" command, but it allows you to
5219 set both the mount options and the vfstype as for the mount(8) -o
5220 and -t flags.
5221 $device = $g->mountable_device ($mountable);
5223 Returns the device name of a mountable. In quite a lot of cases,
5224 the mountable is the device name.
5225 However this doesn't apply for btrfs subvolumes, where the
5227 mountable is a combination of both the device name and the
5228 subvolume path (see also "$g->mountable_subvolume" to extract the
5229 subvolume path of the mountable if any).
5230 $subvolume = $g->mountable_subvolume ($mountable);
5232 Returns the subvolume path of a mountable. Btrfs subvolumes
5233 mountables are a combination of both the device name and the
5234 subvolume path (see also "$g->mountable_device" to extract the
5235 device of the mountable).
5236 If the mountable does not represent a btrfs subvolume, then this
5238 function fails and the "errno" is set to "EINVAL".
5239 %mps = $g->mountpoints ();
5241 This call is similar to "$g->mounts". That call returns a list of
5242 devices. This one returns a hash table (map) of device name to
5243 directory where the device is mounted.
5244 @devices = $g->mounts ();
5246 This returns the list of currently mounted filesystems. It returns
5247 the list of devices (eg. /dev/sda1, /dev/VG/LV).
5248 Some internal mounts are not shown.
5250 See also: "$g->mountpoints"
5252 $g->mv ($src, $dest);
5254 This moves a file from "src" to "dest" where "dest" is either a
5255 destination filename or destination directory.
5256 See also: "$g->rename".
5258 $nrdisks = $g->nr_devices ();
5260 This returns the number of whole block devices that were added.
5261 This is the same as the number of devices that would be returned if
5262 you called "$g->list_devices".
5263 To find out the maximum number of devices that could be added, call
5265 "$g->max_disks".
5266 $status = $g->ntfs_3g_probe ($rw, $device);
5268 This command runs the ntfs-3g.probe(8) command which probes an NTFS
5269 "device" for mountability. (Not all NTFS volumes can be mounted
5270 read-write, and some cannot be mounted at all).
5271 "rw" is a boolean flag. Set it to true if you want to test if the
5273 volume can be mounted read-write. Set it to false if you want to
5274 test if the volume can be mounted read-only.
5275 The return value is an integer which 0 if the operation would
5277 succeed, or some non-zero value documented in the ntfs-3g.probe(8)
5278 manual page.
5279 This function depends on the feature "ntfs3g". See also
5281 "$g->feature-available".
5282 $g->ntfscat_i ($device, $inode, $filename);
5284 Download a file given its inode from a NTFS filesystem and save it
5285 as filename on the local machine.
5286 This allows to download some otherwise inaccessible files such as
5288 the ones within the $Extend folder.
5289 The filesystem from which to extract the file must be unmounted,
5291 otherwise the call will fail.
5292 $g->ntfsclone_in ($backupfile, $device);
5294 Restore the "backupfile" (from a previous call to
5295 "$g->ntfsclone_out") to "device", overwriting any existing contents
5296 of this device.
5297 This function depends on the feature "ntfs3g". See also
5299 "$g->feature-available".
5300 $g->ntfsclone_out ($device, $backupfile [, metadataonly =>
5302 $metadataonly] [, rescue => $rescue] [, ignorefscheck =>
5303 $ignorefscheck] [, preservetimestamps => $preservetimestamps] [, force
5304 => $force]);
5305 Stream the NTFS filesystem "device" to the local file "backupfile".
5306 The format used for the backup file is a special format used by the
5307 ntfsclone(8) tool.
5308 If the optional "metadataonly" flag is true, then only the metadata
5310 is saved, losing all the user data (this is useful for diagnosing
5311 some filesystem problems).
5312 The optional "rescue", "ignorefscheck", "preservetimestamps" and
5314 "force" flags have precise meanings detailed in the ntfsclone(8)
5315 man page.
5316 Use "$g->ntfsclone_in" to restore the file back to a libguestfs
5318 device.
5319 This function depends on the feature "ntfs3g". See also
5321 "$g->feature-available".
5322 $g->ntfsfix ($device [, clearbadsectors => $clearbadsectors]);
5324 This command repairs some fundamental NTFS inconsistencies, resets
5325 the NTFS journal file, and schedules an NTFS consistency check for
5326 the first boot into Windows.
5327 This is not an equivalent of Windows "chkdsk". It does not scan
5329 the filesystem for inconsistencies.
5330 The optional "clearbadsectors" flag clears the list of bad sectors.
5332 This is useful after cloning a disk with bad sectors to a new disk.
5333 This function depends on the feature "ntfs3g". See also
5335 "$g->feature-available".
5336 $g->ntfsresize ($device [, size => $size] [, force => $force]);
5338 This command resizes an NTFS filesystem, expanding or shrinking it
5339 to the size of the underlying device.
5340 The optional parameters are:
5342 "size"
5344 The new size (in bytes) of the filesystem. If omitted, the
5345 filesystem is resized to fit the container (eg. partition).
5346 "force"
5348 If this option is true, then force the resize of the filesystem
5349 even if the filesystem is marked as requiring a consistency
5350 check.
5351 After the resize operation, the filesystem is always marked as
5353 requiring a consistency check (for safety). You have to boot
5354 into Windows to perform this check and clear this condition.
5355 If you don't set the "force" option then it is not possible to
5356 call "$g->ntfsresize" multiple times on a single filesystem
5357 without booting into Windows between each resize.
5358 See also ntfsresize(8).
5360 This function depends on the feature "ntfsprogs". See also
5362 "$g->feature-available".
5363 $g->ntfsresize_opts ($device [, size => $size] [, force => $force]);
5365 This is an alias of "ntfsresize".
5366 $g->ntfsresize_size ($device, $size);
5368 This command is the same as "$g->ntfsresize" except that it allows
5369 you to specify the new size (in bytes) explicitly.
5370 This function depends on the feature "ntfsprogs". See also
5372 "$g->feature-available".
5373 This function is deprecated. In new code, use the "ntfsresize"
5375 call instead.
5376 Deprecated functions will not be removed from the API, but the fact
5378 that they are deprecated indicates that there are problems with
5379 correct use of these functions.
5380 $g->parse_environment ();
5382 Parse the programXs environment and set flags in the handle
5383 accordingly. For example if "LIBGUESTFS_DEBUG=1" then the
5384 XverboseX flag is set in the handle.
5385 Most programs do not need to call this. It is done implicitly when
5387 you call "$g->create".
5388 See "ENVIRONMENT VARIABLES" in guestfs(3) for a list of environment
5390 variables that can affect libguestfs handles. See also
5391 "guestfs_create_flags" in guestfs(3), and
5392 "$g->parse_environment_list".
5393 $g->parse_environment_list (\@environment);
5395 Parse the list of strings in the argument "environment" and set
5396 flags in the handle accordingly. For example if
5397 "LIBGUESTFS_DEBUG=1" is a string in the list, then the XverboseX
5398 flag is set in the handle.
5399 This is the same as "$g->parse_environment" except that it parses
5401 an explicit list of strings instead of the program's environment.
5402 $g->part_add ($device, $prlogex, $startsect, $endsect);
5404 This command adds a partition to "device". If there is no
5405 partition table on the device, call "$g->part_init" first.
5406 The "prlogex" parameter is the type of partition. Normally you
5408 should pass "p" or "primary" here, but MBR partition tables also
5409 support "l" (or "logical") and "e" (or "extended") partition types.
5410 "startsect" and "endsect" are the start and end of the partition in
5412 sectors. "endsect" may be negative, which means it counts
5413 backwards from the end of the disk ("-1" is the last sector).
5414 Creating a partition which covers the whole disk is not so easy.
5416 Use "$g->part_disk" to do that.
5417 $g->part_del ($device, $partnum);
5419 This command deletes the partition numbered "partnum" on "device".
5420 Note that in the case of MBR partitioning, deleting an extended
5422 partition also deletes any logical partitions it contains.
5423 $g->part_disk ($device, $parttype);
5425 This command is simply a combination of "$g->part_init" followed by
5426 "$g->part_add" to create a single primary partition covering the
5427 whole disk.
5428 "parttype" is the partition table type, usually "mbr" or "gpt", but
5430 other possible values are described in "$g->part_init".
5431 $g->part_expand_gpt ($device);
5433 Move backup GPT data structures to the end of the disk. This is
5434 useful in case of in-place image expand since disk space after
5435 backup GPT header is not usable. This is equivalent to "sgdisk
5436 -e".
5437 See also sgdisk(8).
5439 This function depends on the feature "gdisk". See also
5441 "$g->feature-available".
5442 $bootable = $g->part_get_bootable ($device, $partnum);
5444 This command returns true if the partition "partnum" on "device"
5445 has the bootable flag set.
5446 See also "$g->part_set_bootable".
5448 $guid = $g->part_get_disk_guid ($device);
5450 Return the disk identifier (GUID) of a GPT-partitioned "device".
5451 Behaviour is undefined for other partition types.
5452 This function depends on the feature "gdisk". See also
5454 "$g->feature-available".
5455 $attributes = $g->part_get_gpt_attributes ($device, $partnum);
5457 Return the attribute flags of numbered GPT partition "partnum". An
5458 error is returned for MBR partitions.
5459 This function depends on the feature "gdisk". See also
5461 "$g->feature-available".
5462 $guid = $g->part_get_gpt_guid ($device, $partnum);
5464 Return the GUID of numbered GPT partition "partnum".
5465 This function depends on the feature "gdisk". See also
5467 "$g->feature-available".
5468 $guid = $g->part_get_gpt_type ($device, $partnum);
5470 Return the type GUID of numbered GPT partition "partnum". For MBR
5471 partitions, return an appropriate GUID corresponding to the MBR
5472 type. Behaviour is undefined for other partition types.
5473 This function depends on the feature "gdisk". See also
5475 "$g->feature-available".
5476 $idbyte = $g->part_get_mbr_id ($device, $partnum);
5478 Returns the MBR type byte (also known as the ID byte) from the
5479 numbered partition "partnum".
5480 Note that only MBR (old DOS-style) partitions have type bytes. You
5482 will get undefined results for other partition table types (see
5483 "$g->part_get_parttype").
5484 $partitiontype = $g->part_get_mbr_part_type ($device, $partnum);
5486 This returns the partition type of an MBR partition numbered
5487 "partnum" on device "device".
5488 It returns "primary", "logical", or "extended".
5490 $name = $g->part_get_name ($device, $partnum);
5492 This gets the partition name on partition numbered "partnum" on
5493 device "device". Note that partitions are numbered from 1.
5494 The partition name can only be read on certain types of partition
5496 table. This works on "gpt" but not on "mbr" partitions.
5497 $parttype = $g->part_get_parttype ($device);
5499 This command examines the partition table on "device" and returns
5500 the partition table type (format) being used.
5501 Common return values include: "msdos" (a DOS/Windows style MBR
5503 partition table), "gpt" (a GPT/EFI-style partition table). Other
5504 values are possible, although unusual. See "$g->part_init" for a
5505 full list.
5506 $g->part_init ($device, $parttype);
5508 This creates an empty partition table on "device" of one of the
5509 partition types listed below. Usually "parttype" should be either
5510 "msdos" or "gpt" (for large disks).
5511 Initially there are no partitions. Following this, you should call
5513 "$g->part_add" for each partition required.
5514 Possible values for "parttype" are:
5516 efi
5518 gpt Intel EFI / GPT partition table.
5519 This is recommended for >= 2 TB partitions that will be
5521 accessed from Linux and Intel-based Mac OS X. It also has
5522 limited backwards compatibility with the "mbr" format.
5523 mbr
5525 msdos
5526 The standard PC "Master Boot Record" (MBR) format used by MS-
5527 DOS and Windows. This partition type will only work for device
5528 sizes up to 2 TB. For large disks we recommend using "gpt".
5529 Other partition table types that may work but are not supported
5531 include:
5532 aix AIX disk labels.
5534 amiga
5536 rdb Amiga "Rigid Disk Block" format.
5537 bsd BSD disk labels.
5539 dasd
5541 DASD, used on IBM mainframes.
5542 dvh MIPS/SGI volumes.
5544 mac Old Mac partition format. Modern Macs use "gpt".
5546 pc98
5548 NEC PC-98 format, common in Japan apparently.
5549 sun Sun disk labels.
5551 @partitions = $g->part_list ($device);
5553 This command parses the partition table on "device" and returns the
5554 list of partitions found.
5555 The fields in the returned structure are:
5557 part_num
5559 Partition number, counting from 1.
5560 part_start
5562 Start of the partition in bytes. To get sectors you have to
5563 divide by the deviceXs sector size, see "$g->blockdev_getss".
5564 part_end
5566 End of the partition in bytes.
5567 part_size
5569 Size of the partition in bytes.
5570 $g->part_resize ($device, $partnum, $endsect);
5572 This command resizes the partition numbered "partnum" on "device"
5573 by moving the end position.
5574 Note that this does not modify any filesystem present in the
5576 partition. If you wish to do this, you will need to use filesystem
5577 resizing commands like "$g->resize2fs".
5578 When growing a partition you will want to grow the filesystem
5580 afterwards, but when shrinking, you need to shrink the filesystem
5581 before the partition.
5582 $g->part_set_bootable ($device, $partnum, $bootable);
5584 This sets the bootable flag on partition numbered "partnum" on
5585 device "device". Note that partitions are numbered from 1.
5586 The bootable flag is used by some operating systems (notably
5588 Windows) to determine which partition to boot from. It is by no
5589 means universally recognized.
5590 $g->part_set_disk_guid ($device, $guid);
5592 Set the disk identifier (GUID) of a GPT-partitioned "device" to
5593 "guid". Return an error if the partition table of "device" isn't
5594 GPT, or if "guid" is not a valid GUID.
5595 This function depends on the feature "gdisk". See also
5597 "$g->feature-available".
5598 $g->part_set_disk_guid_random ($device);
5600 Set the disk identifier (GUID) of a GPT-partitioned "device" to a
5601 randomly generated value. Return an error if the partition table
5602 of "device" isn't GPT.
5603 This function depends on the feature "gdisk". See also
5605 "$g->feature-available".
5606 $g->part_set_gpt_attributes ($device, $partnum, $attributes);
5608 Set the attribute flags of numbered GPT partition "partnum" to
5609 "attributes". Return an error if the partition table of "device"
5610 isn't GPT.
5611 See
5613 <https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_entries>
5614 for a useful list of partition attributes.
5615 This function depends on the feature "gdisk". See also
5617 "$g->feature-available".
5618 $g->part_set_gpt_guid ($device, $partnum, $guid);
5620 Set the GUID of numbered GPT partition "partnum" to "guid". Return
5621 an error if the partition table of "device" isn't GPT, or if "guid"
5622 is not a valid GUID.
5623 This function depends on the feature "gdisk". See also
5625 "$g->feature-available".
5626 $g->part_set_gpt_type ($device, $partnum, $guid);
5628 Set the type GUID of numbered GPT partition "partnum" to "guid".
5629 Return an error if the partition table of "device" isn't GPT, or if
5630 "guid" is not a valid GUID.
5631 See
5633 <http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs>
5634 for a useful list of type GUIDs.
5635 This function depends on the feature "gdisk". See also
5637 "$g->feature-available".
5638 $g->part_set_mbr_id ($device, $partnum, $idbyte);
5640 Sets the MBR type byte (also known as the ID byte) of the numbered
5641 partition "partnum" to "idbyte". Note that the type bytes quoted
5642 in most documentation are in fact hexadecimal numbers, but usually
5643 documented without any leading "0x" which might be confusing.
5644 Note that only MBR (old DOS-style) partitions have type bytes. You
5646 will get undefined results for other partition table types (see
5647 "$g->part_get_parttype").
5648 $g->part_set_name ($device, $partnum, $name);
5650 This sets the partition name on partition numbered "partnum" on
5651 device "device". Note that partitions are numbered from 1.
5652 The partition name can only be set on certain types of partition
5654 table. This works on "gpt" but not on "mbr" partitions.
5655 $device = $g->part_to_dev ($partition);
5657 This function takes a partition name (eg. "/dev/sdb1") and removes
5658 the partition number, returning the device name (eg. "/dev/sdb").
5659 The named partition must exist, for example as a string returned
5661 from "$g->list_partitions".
5662 See also "$g->part_to_partnum", "$g->device_index".
5664 $partnum = $g->part_to_partnum ($partition);
5666 This function takes a partition name (eg. "/dev/sdb1") and returns
5667 the partition number (eg. 1).
5668 The named partition must exist, for example as a string returned
5670 from "$g->list_partitions".
5671 See also "$g->part_to_dev".
5673 $g->ping_daemon ();
5675 This is a test probe into the guestfs daemon running inside the
5676 libguestfs appliance. Calling this function checks that the daemon
5677 responds to the ping message, without affecting the daemon or
5678 attached block device(s) in any other way.
5679 $content = $g->pread ($path, $count, $offset);
5681 This command lets you read part of a file. It reads "count" bytes
5682 of the file, starting at "offset", from file "path".
5683 This may read fewer bytes than requested. For further details see
5685 the pread(2) system call.
5686 See also "$g->pwrite", "$g->pread_device".
5688 Because of the message protocol, there is a transfer limit of
5690 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5691 guestfs(3).
5692 $content = $g->pread_device ($device, $count, $offset);
5694 This command lets you read part of a block device. It reads
5695 "count" bytes of "device", starting at "offset".
5696 This may read fewer bytes than requested. For further details see
5698 the pread(2) system call.
5699 See also "$g->pread".
5701 Because of the message protocol, there is a transfer limit of
5703 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5704 guestfs(3).
5705 $g->pvchange_uuid ($device);
5707 Generate a new random UUID for the physical volume "device".
5708 This function depends on the feature "lvm2". See also
5710 "$g->feature-available".
5711 $g->pvchange_uuid_all ();
5713 Generate new random UUIDs for all physical volumes.
5714 This function depends on the feature "lvm2". See also
5716 "$g->feature-available".
5717 $g->pvcreate ($device);
5719 This creates an LVM physical volume on the named "device", where
5720 "device" should usually be a partition name such as /dev/sda1.
5721 This function depends on the feature "lvm2". See also
5723 "$g->feature-available".
5724 $g->pvremove ($device);
5726 This wipes a physical volume "device" so that LVM will no longer
5727 recognise it.
5728 The implementation uses the "pvremove" command which refuses to
5730 wipe physical volumes that contain any volume groups, so you have
5731 to remove those first.
5732 This function depends on the feature "lvm2". See also
5734 "$g->feature-available".
5735 $g->pvresize ($device);
5737 This resizes (expands or shrinks) an existing LVM physical volume
5738 to match the new size of the underlying device.
5739 This function depends on the feature "lvm2". See also
5741 "$g->feature-available".
5742 $g->pvresize_size ($device, $size);
5744 This command is the same as "$g->pvresize" except that it allows
5745 you to specify the new size (in bytes) explicitly.
5746 This function depends on the feature "lvm2". See also
5748 "$g->feature-available".
5749 @physvols = $g->pvs ();
5751 List all the physical volumes detected. This is the equivalent of
5752 the pvs(8) command.
5753 This returns a list of just the device names that contain PVs (eg.
5755 /dev/sda2).
5756 See also "$g->pvs_full".
5758 This function depends on the feature "lvm2". See also
5760 "$g->feature-available".
5761 @physvols = $g->pvs_full ();
5763 List all the physical volumes detected. This is the equivalent of
5764 the pvs(8) command. The "full" version includes all fields.
5765 This function depends on the feature "lvm2". See also
5767 "$g->feature-available".
5768 $uuid = $g->pvuuid ($device);
5770 This command returns the UUID of the LVM PV "device".
5771 $nbytes = $g->pwrite ($path, $content, $offset);
5773 This command writes to part of a file. It writes the data buffer
5774 "content" to the file "path" starting at offset "offset".
5775 This command implements the pwrite(2) system call, and like that
5777 system call it may not write the full data requested. The return
5778 value is the number of bytes that were actually written to the
5779 file. This could even be 0, although short writes are unlikely for
5780 regular files in ordinary circumstances.
5781 See also "$g->pread", "$g->pwrite_device".
5783 Because of the message protocol, there is a transfer limit of
5785 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5786 guestfs(3).
5787 $nbytes = $g->pwrite_device ($device, $content, $offset);
5789 This command writes to part of a device. It writes the data buffer
5790 "content" to "device" starting at offset "offset".
5791 This command implements the pwrite(2) system call, and like that
5793 system call it may not write the full data requested (although
5794 short writes to disk devices and partitions are probably impossible
5795 with standard Linux kernels).
5796 See also "$g->pwrite".
5798 Because of the message protocol, there is a transfer limit of
5800 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5801 guestfs(3).
5802 $content = $g->read_file ($path);
5804 This calls returns the contents of the file "path" as a buffer.
5805 Unlike "$g->cat", this function can correctly handle files that
5807 contain embedded ASCII NUL characters.
5808 @lines = $g->read_lines ($path);
5810 Return the contents of the file named "path".
5811 The file contents are returned as a list of lines. Trailing "LF"
5813 and "CRLF" character sequences are not returned.
5814 Note that this function cannot correctly handle binary files
5816 (specifically, files containing "\0" character which is treated as
5817 end of string). For those you need to use the "$g->read_file"
5818 function and split the buffer into lines yourself.
5819 @entries = $g->readdir ($dir);
5821 This returns the list of directory entries in directory "dir".
5822 All entries in the directory are returned, including "." and "..".
5824 The entries are not sorted, but returned in the same order as the
5825 underlying filesystem.
5826 Also this call returns basic file type information about each file.
5828 The "ftyp" field will contain one of the following characters:
5829 'b' Block special
5831 'c' Char special
5833 'd' Directory
5835 'f' FIFO (named pipe)
5837 'l' Symbolic link
5839 'r' Regular file
5841 's' Socket
5843 'u' Unknown file type
5845 '?' The readdir(3) call returned a "d_type" field with an
5847 unexpected value
5848 This function is primarily intended for use by programs. To get a
5850 simple list of names, use "$g->ls". To get a printable directory
5851 for human consumption, use "$g->ll".
5852 Because of the message protocol, there is a transfer limit of
5854 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
5855 guestfs(3).
5856 $link = $g->readlink ($path);
5858 This command reads the target of a symbolic link.
5859 @links = $g->readlinklist ($path, \@names);
5861 This call allows you to do a "readlink" operation on multiple
5862 files, where all files are in the directory "path". "names" is the
5863 list of files from this directory.
5864 On return you get a list of strings, with a one-to-one
5866 correspondence to the "names" list. Each string is the value of
5867 the symbolic link.
5868 If the readlink(2) operation fails on any name, then the
5870 corresponding result string is the empty string "". However the
5871 whole operation is completed even if there were readlink(2) errors,
5872 and so you can call this function with names where you don't know
5873 if they are symbolic links already (albeit slightly less
5874 efficient).
5875 This call is intended for programs that want to efficiently list a
5877 directory contents without making many round-trips.
5878 $rpath = $g->realpath ($path);
5880 Return the canonicalized absolute pathname of "path". The returned
5881 path has no ".", ".." or symbolic link path elements.
5882 $g->remount ($mountpoint [, rw => $rw]);
5884 This call allows you to change the "rw" (readonly/read-write) flag
5885 on an already mounted filesystem at "mountpoint", converting a
5886 readonly filesystem to be read-write, or vice-versa.
5887 Note that at the moment you must supply the "optional" "rw"
5889 parameter. In future we may allow other flags to be adjusted.
5890 $g->remove_drive ($label);
5892 This function is conceptually the opposite of "$g->add_drive_opts".
5893 It removes the drive that was previously added with label "label".
5894 Note that in order to remove drives, you have to add them with
5896 labels (see the optional "label" argument to "$g->add_drive_opts").
5897 If you didn't use a label, then they cannot be removed.
5898 You can call this function before or after launching the handle.
5900 If called after launch, if the backend supports it, we try to hot
5901 unplug the drive: see "HOTPLUGGING" in guestfs(3). The disk must
5902 not be in use (eg. mounted) when you do this. We try to detect if
5903 the disk is in use and stop you from doing this.
5904 $g->removexattr ($xattr, $path);
5906 This call removes the extended attribute named "xattr" of the file
5907 "path".
5908 See also: "$g->lremovexattr", attr(5).
5910 This function depends on the feature "linuxxattrs". See also
5912 "$g->feature-available".
5913 $g->rename ($oldpath, $newpath);
5915 Rename a file to a new place on the same filesystem. This is the
5916 same as the Linux rename(2) system call. In most cases you are
5917 better to use "$g->mv" instead.
5918 $g->resize2fs ($device);
5920 This resizes an ext2, ext3 or ext4 filesystem to match the size of
5921 the underlying device.
5922 See also "RESIZE2FS ERRORS" in guestfs(3).
5924 $g->resize2fs_M ($device);
5926 This command is the same as "$g->resize2fs", but the filesystem is
5927 resized to its minimum size. This works like the -M option to the
5928 "resize2fs" command.
5929 To get the resulting size of the filesystem you should call
5931 "$g->tune2fs_l" and read the "Block size" and "Block count" values.
5932 These two numbers, multiplied together, give the resulting size of
5933 the minimal filesystem in bytes.
5934 See also "RESIZE2FS ERRORS" in guestfs(3).
5936 $g->resize2fs_size ($device, $size);
5938 This command is the same as "$g->resize2fs" except that it allows
5939 you to specify the new size (in bytes) explicitly.
5940 See also "RESIZE2FS ERRORS" in guestfs(3).
5942 $g->rm ($path);
5944 Remove the single file "path".
5945 $g->rm_f ($path);
5947 Remove the file "path".
5948 If the file doesn't exist, that error is ignored. (Other errors,
5950 eg. I/O errors or bad paths, are not ignored)
5951 This call cannot remove directories. Use "$g->rmdir" to remove an
5953 empty directory, or "$g->rm_rf" to remove directories recursively.
5954 $g->rm_rf ($path);
5956 Remove the file or directory "path", recursively removing the
5957 contents if its a directory. This is like the "rm -rf" shell
5958 command.
5959 $g->rmdir ($path);
5961 Remove the single directory "path".
5962 $g->rmmountpoint ($exemptpath);
5964 This call removes a mountpoint that was previously created with
5965 "$g->mkmountpoint". See "$g->mkmountpoint" for full details.
5966 $g->rsync ($src, $dest [, archive => $archive] [, deletedest =>
5968 $deletedest]);
5969 This call may be used to copy or synchronize two directories under
5970 the same libguestfs handle. This uses the rsync(1) program which
5971 uses a fast algorithm that avoids copying files unnecessarily.
5972 "src" and "dest" are the source and destination directories. Files
5974 are copied from "src" to "dest".
5975 The optional arguments are:
5977 "archive"
5979 Turns on archive mode. This is the same as passing the
5980 --archive flag to "rsync".
5981 "deletedest"
5983 Delete files at the destination that do not exist at the
5984 source.
5985 This function depends on the feature "rsync". See also
5987 "$g->feature-available".
5988 $g->rsync_in ($remote, $dest [, archive => $archive] [, deletedest =>
5990 $deletedest]);
5991 This call may be used to copy or synchronize the filesystem on the
5992 host or on a remote computer with the filesystem within libguestfs.
5993 This uses the rsync(1) program which uses a fast algorithm that
5994 avoids copying files unnecessarily.
5995 This call only works if the network is enabled. See
5997 "$g->set_network" or the --network option to various tools like
5998 guestfish(1).
5999 Files are copied from the remote server and directory specified by
6001 "remote" to the destination directory "dest".
6002 The format of the remote server string is defined by rsync(1).
6004 Note that there is no way to supply a password or passphrase so the
6005 target must be set up not to require one.
6006 The optional arguments are the same as those of "$g->rsync".
6008 This function depends on the feature "rsync". See also
6010 "$g->feature-available".
6011 $g->rsync_out ($src, $remote [, archive => $archive] [, deletedest =>
6013 $deletedest]);
6014 This call may be used to copy or synchronize the filesystem within
6015 libguestfs with a filesystem on the host or on a remote computer.
6016 This uses the rsync(1) program which uses a fast algorithm that
6017 avoids copying files unnecessarily.
6018 This call only works if the network is enabled. See
6020 "$g->set_network" or the --network option to various tools like
6021 guestfish(1).
6022 Files are copied from the source directory "src" to the remote
6024 server and directory specified by "remote".
6025 The format of the remote server string is defined by rsync(1).
6027 Note that there is no way to supply a password or passphrase so the
6028 target must be set up not to require one.
6029 The optional arguments are the same as those of "$g->rsync".
6031 Globbing does not happen on the "src" parameter. In programs which
6033 use the API directly you have to expand wildcards yourself (see
6034 "$g->glob_expand"). In guestfish you can use the "glob" command
6035 (see "glob" in guestfish(1)), for example:
6036 ><fs> glob rsync-out /* rsync://remote/
6038 This function depends on the feature "rsync". See also
6040 "$g->feature-available".
6041 $g->scrub_device ($device);
6043 This command writes patterns over "device" to make data retrieval
6044 more difficult.
6045 It is an interface to the scrub(1) program. See that manual page
6047 for more details.
6048 This function depends on the feature "scrub". See also
6050 "$g->feature-available".
6051 $g->scrub_file ($file);
6053 This command writes patterns over a file to make data retrieval
6054 more difficult.
6055 The file is removed after scrubbing.
6057 It is an interface to the scrub(1) program. See that manual page
6059 for more details.
6060 This function depends on the feature "scrub". See also
6062 "$g->feature-available".
6063 $g->scrub_freespace ($dir);
6065 This command creates the directory "dir" and then fills it with
6066 files until the filesystem is full, and scrubs the files as for
6067 "$g->scrub_file", and deletes them. The intention is to scrub any
6068 free space on the partition containing "dir".
6069 It is an interface to the scrub(1) program. See that manual page
6071 for more details.
6072 This function depends on the feature "scrub". See also
6074 "$g->feature-available".
6075 $g->selinux_relabel ($specfile, $path [, force => $force]);
6077 SELinux relabel parts of the filesystem.
6078 The "specfile" parameter controls the policy spec file used. You
6080 have to parse "/etc/selinux/config" to find the correct SELinux
6081 policy and then pass the spec file, usually: "/etc/selinux/" +
6082 selinuxtype + "/contexts/files/file_contexts".
6083 The required "path" parameter is the top level directory where
6085 relabelling starts. Normally you should pass "path" as "/" to
6086 relabel the whole guest filesystem.
6087 The optional "force" boolean controls whether the context is reset
6089 for customizable files, and also whether the user, role and range
6090 parts of the file context is changed.
6091 This function depends on the feature "selinuxrelabel". See also
6093 "$g->feature-available".
6094 $g->set_append ($append);
6096 This function is used to add additional options to the libguestfs
6097 appliance kernel command line.
6098 The default is "NULL" unless overridden by setting
6100 "LIBGUESTFS_APPEND" environment variable.
6101 Setting "append" to "NULL" means no additional options are passed
6103 (libguestfs always adds a few of its own).
6104 $g->set_attach_method ($backend);
6106 Set the method that libguestfs uses to connect to the backend
6107 guestfsd daemon.
6108 See "BACKEND" in guestfs(3).
6110 This function is deprecated. In new code, use the "set_backend"
6112 call instead.
6113 Deprecated functions will not be removed from the API, but the fact
6115 that they are deprecated indicates that there are problems with
6116 correct use of these functions.
6117 $g->set_autosync ($autosync);
6119 If "autosync" is true, this enables autosync. Libguestfs will make
6120 a best effort attempt to make filesystems consistent and
6121 synchronized when the handle is closed (also if the program exits
6122 without closing handles).
6123 This is enabled by default (since libguestfs 1.5.24, previously it
6125 was disabled by default).
6126 $g->set_backend ($backend);
6128 Set the method that libguestfs uses to connect to the backend
6129 guestfsd daemon.
6130 This handle property was previously called the "attach method".
6132 See "BACKEND" in guestfs(3).
6134 $g->set_backend_setting ($name, $val);
6136 Append "name=value" to the backend settings string list. However
6137 if a string already exists matching "name" or beginning with
6138 "name=", then that setting is replaced.
6139 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
6141 $g->set_backend_settings (\@settings);
6143 Set a list of zero or more settings which are passed through to the
6144 current backend. Each setting is a string which is interpreted in
6145 a backend-specific way, or ignored if not understood by the
6146 backend.
6147 The default value is an empty list, unless the environment variable
6149 "LIBGUESTFS_BACKEND_SETTINGS" was set when the handle was created.
6150 This environment variable contains a colon-separated list of
6151 settings.
6152 This call replaces all backend settings. If you want to replace a
6154 single backend setting, see "$g->set_backend_setting". If you want
6155 to clear a single backend setting, see "$g->clear_backend_setting".
6156 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
6158 $g->set_cachedir ($cachedir);
6160 Set the directory used by the handle to store the appliance cache,
6161 when using a supermin appliance. The appliance is cached and
6162 shared between all handles which have the same effective user ID.
6163 The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR"
6165 control the default value: If "LIBGUESTFS_CACHEDIR" is set, then
6166 that is the default. Else if "TMPDIR" is set, then that is the
6167 default. Else /var/tmp is the default.
6168 $g->set_direct ($direct);
6170 If the direct appliance mode flag is enabled, then stdin and stdout
6171 are passed directly through to the appliance once it is launched.
6172 One consequence of this is that log messages aren't caught by the
6174 library and handled by "$g->set_log_message_callback", but go
6175 straight to stdout.
6176 You probably don't want to use this unless you know what you are
6178 doing.
6179 The default is disabled.
6181 This function is deprecated. In new code, use the
6183 "internal_get_console_socket" call instead.
6184 Deprecated functions will not be removed from the API, but the fact
6186 that they are deprecated indicates that there are problems with
6187 correct use of these functions.
6188 $g->set_e2attrs ($file, $attrs [, clear => $clear]);
6190 This sets or clears the file attributes "attrs" associated with the
6191 inode file.
6192 "attrs" is a string of characters representing file attributes.
6194 See "$g->get_e2attrs" for a list of possible attributes. Not all
6195 attributes can be changed.
6196 If optional boolean "clear" is not present or false, then the
6198 "attrs" listed are set in the inode.
6199 If "clear" is true, then the "attrs" listed are cleared in the
6201 inode.
6202 In both cases, other attributes not present in the "attrs" string
6204 are left unchanged.
6205 These attributes are only present when the file is located on an
6207 ext2/3/4 filesystem. Using this call on other filesystem types
6208 will result in an error.
6209 $g->set_e2generation ($file, $generation);
6211 This sets the ext2 file generation of a file.
6212 See "$g->get_e2generation".
6214 $g->set_e2label ($device, $label);
6216 This sets the ext2/3/4 filesystem label of the filesystem on
6217 "device" to "label". Filesystem labels are limited to 16
6218 characters.
6219 You can use either "$g->tune2fs_l" or "$g->get_e2label" to return
6221 the existing label on a filesystem.
6222 This function is deprecated. In new code, use the "set_label" call
6224 instead.
6225 Deprecated functions will not be removed from the API, but the fact
6227 that they are deprecated indicates that there are problems with
6228 correct use of these functions.
6229 $g->set_e2uuid ($device, $uuid);
6231 This sets the ext2/3/4 filesystem UUID of the filesystem on
6232 "device" to "uuid". The format of the UUID and alternatives such
6233 as "clear", "random" and "time" are described in the tune2fs(8)
6234 manpage.
6235 You can use "$g->vfs_uuid" to return the existing UUID of a
6237 filesystem.
6238 This function is deprecated. In new code, use the "set_uuid" call
6240 instead.
6241 Deprecated functions will not be removed from the API, but the fact
6243 that they are deprecated indicates that there are problems with
6244 correct use of these functions.
6245 $g->set_hv ($hv);
6247 Set the hypervisor binary that we will use. The hypervisor depends
6248 on the backend, but is usually the location of the qemu/KVM
6249 hypervisor. For the uml backend, it is the location of the "linux"
6250 or "vmlinux" binary.
6251 The default is chosen when the library was compiled by the
6253 configure script.
6254 You can also override this by setting the "LIBGUESTFS_HV"
6256 environment variable.
6257 Note that you should call this function as early as possible after
6259 creating the handle. This is because some pre-launch operations
6260 depend on testing qemu features (by running "qemu -help"). If the
6261 qemu binary changes, we don't retest features, and so you might see
6262 inconsistent results. Using the environment variable
6263 "LIBGUESTFS_HV" is safest of all since that picks the qemu binary
6264 at the same time as the handle is created.
6265 $g->set_identifier ($identifier);
6267 This is an informative string which the caller may optionally set
6268 in the handle. It is printed in various places, allowing the
6269 current handle to be identified in debugging output.
6270 One important place is when tracing is enabled. If the identifier
6272 string is not an empty string, then trace messages change from
6273 this:
6274 libguestfs: trace: get_tmpdir
6276 libguestfs: trace: get_tmpdir = "/tmp"
6277 to this:
6279 libguestfs: trace: ID: get_tmpdir
6281 libguestfs: trace: ID: get_tmpdir = "/tmp"
6282 where "ID" is the identifier string set by this call.
6284 The identifier must only contain alphanumeric ASCII characters,
6286 underscore and minus sign. The default is the empty string.
6287 See also "$g->set_program", "$g->set_trace", "$g->get_identifier".
6289 $g->set_label ($mountable, $label);
6291 Set the filesystem label on "mountable" to "label".
6292 Only some filesystem types support labels, and libguestfs supports
6294 setting labels on only a subset of these.
6295 ext2, ext3, ext4
6297 Labels are limited to 16 bytes.
6298 NTFS
6300 Labels are limited to 128 unicode characters.
6301 XFS The label is limited to 12 bytes. The filesystem must not be
6303 mounted when trying to set the label.
6304 btrfs
6306 The label is limited to 255 bytes and some characters are not
6307 allowed. Setting the label on a btrfs subvolume will set the
6308 label on its parent filesystem. The filesystem must not be
6309 mounted when trying to set the label.
6310 fat The label is limited to 11 bytes.
6312 swap
6314 The label is limited to 16 bytes.
6315 If there is no support for changing the label for the type of the
6317 specified filesystem, set_label will fail and set errno as ENOTSUP.
6318 To read the label on a filesystem, call "$g->vfs_label".
6320 $g->set_libvirt_requested_credential ($index, $cred);
6322 After requesting the "index"'th credential from the user, call this
6323 function to pass the answer back to libvirt.
6324 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
6326 example code.
6327 $g->set_libvirt_supported_credentials (\@creds);
6329 Call this function before setting an event handler for
6330 "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential
6331 types that the program knows how to process.
6332 The "creds" list must be a non-empty list of strings. Possible
6334 strings are:
6335 "username"
6337 "authname"
6338 "language"
6339 "cnonce"
6340 "passphrase"
6341 "echoprompt"
6342 "noechoprompt"
6343 "realm"
6344 "external"
6345 See libvirt documentation for the meaning of these credential
6347 types.
6348 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
6350 example code.
6351 $g->set_memsize ($memsize);
6353 This sets the memory size in megabytes allocated to the hypervisor.
6354 This only has any effect if called before "$g->launch".
6355 You can also change this by setting the environment variable
6357 "LIBGUESTFS_MEMSIZE" before the handle is created.
6358 For more information on the architecture of libguestfs, see
6360 guestfs(3).
6361 $g->set_network ($network);
6363 If "network" is true, then the network is enabled in the libguestfs
6364 appliance. The default is false.
6365 This affects whether commands are able to access the network (see
6367 "RUNNING COMMANDS" in guestfs(3)).
6368 You must call this before calling "$g->launch", otherwise it has no
6370 effect.
6371 $g->set_path ($searchpath);
6373 Set the path that libguestfs searches for kernel and initrd.img.
6374 The default is "$libdir/guestfs" unless overridden by setting
6376 "LIBGUESTFS_PATH" environment variable.
6377 Setting "path" to "NULL" restores the default path.
6379 $g->set_pgroup ($pgroup);
6381 If "pgroup" is true, child processes are placed into their own
6382 process group.
6383 The practical upshot of this is that signals like "SIGINT" (from
6385 users pressing "^C") won't be received by the child process.
6386 The default for this flag is false, because usually you want "^C"
6388 to kill the subprocess. Guestfish sets this flag to true when used
6389 interactively, so that "^C" can cancel long-running commands
6390 gracefully (see "$g->user_cancel").
6391 $g->set_program ($program);
6393 Set the program name. This is an informative string which the main
6394 program may optionally set in the handle.
6395 When the handle is created, the program name in the handle is set
6397 to the basename from "argv[0]". The program name can never be
6398 "NULL".
6399 $g->set_qemu ($hv);
6401 Set the hypervisor binary (usually qemu) that we will use.
6402 The default is chosen when the library was compiled by the
6404 configure script.
6405 You can also override this by setting the "LIBGUESTFS_HV"
6407 environment variable.
6408 Setting "hv" to "NULL" restores the default qemu binary.
6410 Note that you should call this function as early as possible after
6412 creating the handle. This is because some pre-launch operations
6413 depend on testing qemu features (by running "qemu -help"). If the
6414 qemu binary changes, we don't retest features, and so you might see
6415 inconsistent results. Using the environment variable
6416 "LIBGUESTFS_HV" is safest of all since that picks the qemu binary
6417 at the same time as the handle is created.
6418 This function is deprecated. In new code, use the "set_hv" call
6420 instead.
6421 Deprecated functions will not be removed from the API, but the fact
6423 that they are deprecated indicates that there are problems with
6424 correct use of these functions.
6425 $g->set_recovery_proc ($recoveryproc);
6427 If this is called with the parameter "false" then "$g->launch" does
6428 not create a recovery process. The purpose of the recovery process
6429 is to stop runaway hypervisor processes in the case where the main
6430 program aborts abruptly.
6431 This only has any effect if called before "$g->launch", and the
6433 default is true.
6434 About the only time when you would want to disable this is if the
6436 main process will fork itself into the background ("daemonize"
6437 itself). In this case the recovery process thinks that the main
6438 program has disappeared and so kills the hypervisor, which is not
6439 very helpful.
6440 $g->set_selinux ($selinux);
6442 This sets the selinux flag that is passed to the appliance at boot
6443 time. The default is "selinux=0" (disabled).
6444 Note that if SELinux is enabled, it is always in Permissive mode
6446 ("enforcing=0").
6447 For more information on the architecture of libguestfs, see
6449 guestfs(3).
6450 This function is deprecated. In new code, use the
6452 "selinux_relabel" call instead.
6453 Deprecated functions will not be removed from the API, but the fact
6455 that they are deprecated indicates that there are problems with
6456 correct use of these functions.
6457 $g->set_smp ($smp);
6459 Change the number of virtual CPUs assigned to the appliance. The
6460 default is 1. Increasing this may improve performance, though
6461 often it has no effect.
6462 This function must be called before "$g->launch".
6464 $g->set_tmpdir ($tmpdir);
6466 Set the directory used by the handle to store temporary files.
6467 The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control
6469 the default value: If "LIBGUESTFS_TMPDIR" is set, then that is the
6470 default. Else if "TMPDIR" is set, then that is the default. Else
6471 /tmp is the default.
6472 $g->set_trace ($trace);
6474 If the command trace flag is set to 1, then libguestfs calls,
6475 parameters and return values are traced.
6476 If you want to trace C API calls into libguestfs (and other
6478 libraries) then possibly a better way is to use the external
6479 ltrace(1) command.
6480 Command traces are disabled unless the environment variable
6482 "LIBGUESTFS_TRACE" is defined and set to 1.
6483 Trace messages are normally sent to "stderr", unless you register a
6485 callback to send them somewhere else (see
6486 "$g->set_event_callback").
6487 $g->set_uuid ($device, $uuid);
6489 Set the filesystem UUID on "device" to "uuid". If this fails and
6490 the errno is ENOTSUP, means that there is no support for changing
6491 the UUID for the type of the specified filesystem.
6492 Only some filesystem types support setting UUIDs.
6494 To read the UUID on a filesystem, call "$g->vfs_uuid".
6496 $g->set_uuid_random ($device);
6498 Set the filesystem UUID on "device" to a random UUID. If this
6499 fails and the errno is ENOTSUP, means that there is no support for
6500 changing the UUID for the type of the specified filesystem.
6501 Only some filesystem types support setting UUIDs.
6503 To read the UUID on a filesystem, call "$g->vfs_uuid".
6505 $g->set_verbose ($verbose);
6507 If "verbose" is true, this turns on verbose messages.
6508 Verbose messages are disabled unless the environment variable
6510 "LIBGUESTFS_DEBUG" is defined and set to 1.
6511 Verbose messages are normally sent to "stderr", unless you register
6513 a callback to send them somewhere else (see
6514 "$g->set_event_callback").
6515 $g->setcon ($context);
6517 This sets the SELinux security context of the daemon to the string
6518 "context".
6519 See the documentation about SELINUX in guestfs(3).
6521 This function depends on the feature "selinux". See also
6523 "$g->feature-available".
6524 This function is deprecated. In new code, use the
6526 "selinux_relabel" call instead.
6527 Deprecated functions will not be removed from the API, but the fact
6529 that they are deprecated indicates that there are problems with
6530 correct use of these functions.
6531 $g->setxattr ($xattr, $val, $vallen, $path);
6533 This call sets the extended attribute named "xattr" of the file
6534 "path" to the value "val" (of length "vallen"). The value is
6535 arbitrary 8 bit data.
6536 See also: "$g->lsetxattr", attr(5).
6538 This function depends on the feature "linuxxattrs". See also
6540 "$g->feature-available".
6541 $g->sfdisk ($device, $cyls, $heads, $sectors, \@lines);
6543 This is a direct interface to the sfdisk(8) program for creating
6544 partitions on block devices.
6545 "device" should be a block device, for example /dev/sda.
6547 "cyls", "heads" and "sectors" are the number of cylinders, heads
6549 and sectors on the device, which are passed directly to sfdisk as
6550 the -C, -H and -S parameters. If you pass 0 for any of these, then
6551 the corresponding parameter is omitted. Usually for XlargeX disks,
6552 you can just pass 0 for these, but for small (floppy-sized) disks,
6553 sfdisk (or rather, the kernel) cannot work out the right geometry
6554 and you will need to tell it.
6555 "lines" is a list of lines that we feed to "sfdisk". For more
6557 information refer to the sfdisk(8) manpage.
6558 To create a single partition occupying the whole disk, you would
6560 pass "lines" as a single element list, when the single element
6561 being the string "," (comma).
6562 See also: "$g->sfdisk_l", "$g->sfdisk_N", "$g->part_init"
6564 This function is deprecated. In new code, use the "part_add" call
6566 instead.
6567 Deprecated functions will not be removed from the API, but the fact
6569 that they are deprecated indicates that there are problems with
6570 correct use of these functions.
6571 $g->sfdiskM ($device, \@lines);
6573 This is a simplified interface to the "$g->sfdisk" command, where
6574 partition sizes are specified in megabytes only (rounded to the
6575 nearest cylinder) and you don't need to specify the cyls, heads and
6576 sectors parameters which were rarely if ever used anyway.
6577 See also: "$g->sfdisk", the sfdisk(8) manpage and "$g->part_disk"
6579 This function is deprecated. In new code, use the "part_add" call
6581 instead.
6582 Deprecated functions will not be removed from the API, but the fact
6584 that they are deprecated indicates that there are problems with
6585 correct use of these functions.
6586 $g->sfdisk_N ($device, $partnum, $cyls, $heads, $sectors, $line);
6588 This runs sfdisk(8) option to modify just the single partition "n"
6589 (note: "n" counts from 1).
6590 For other parameters, see "$g->sfdisk". You should usually pass 0
6592 for the cyls/heads/sectors parameters.
6593 See also: "$g->part_add"
6595 This function is deprecated. In new code, use the "part_add" call
6597 instead.
6598 Deprecated functions will not be removed from the API, but the fact
6600 that they are deprecated indicates that there are problems with
6601 correct use of these functions.
6602 $partitions = $g->sfdisk_disk_geometry ($device);
6604 This displays the disk geometry of "device" read from the partition
6605 table. Especially in the case where the underlying block device
6606 has been resized, this can be different from the kernelXs idea of
6607 the geometry (see "$g->sfdisk_kernel_geometry").
6608 The result is in human-readable format, and not designed to be
6610 parsed.
6611 $partitions = $g->sfdisk_kernel_geometry ($device);
6613 This displays the kernelXs idea of the geometry of "device".
6614 The result is in human-readable format, and not designed to be
6616 parsed.
6617 $partitions = $g->sfdisk_l ($device);
6619 This displays the partition table on "device", in the human-
6620 readable output of the sfdisk(8) command. It is not intended to be
6621 parsed.
6622 See also: "$g->part_list"
6624 This function is deprecated. In new code, use the "part_list" call
6626 instead.
6627 Deprecated functions will not be removed from the API, but the fact
6629 that they are deprecated indicates that there are problems with
6630 correct use of these functions.
6631 $output = $g->sh ($command);
6633 This call runs a command from the guest filesystem via the guestXs
6634 /bin/sh.
6635 This is like "$g->command", but passes the command to:
6637 /bin/sh -c "command"
6639 Depending on the guestXs shell, this usually results in wildcards
6641 being expanded, shell expressions being interpolated and so on.
6642 All the provisos about "$g->command" apply to this call.
6644 @lines = $g->sh_lines ($command);
6646 This is the same as "$g->sh", but splits the result into a list of
6647 lines.
6648 See also: "$g->command_lines"
6650 $g->shutdown ();
6652 This is the opposite of "$g->launch". It performs an orderly
6653 shutdown of the backend process(es). If the autosync flag is set
6654 (which is the default) then the disk image is synchronized.
6655 If the subprocess exits with an error then this function will
6657 return an error, which should not be ignored (it may indicate that
6658 the disk image could not be written out properly).
6659 It is safe to call this multiple times. Extra calls are ignored.
6661 This call does not close or free up the handle. You still need to
6663 call "$g->close" afterwards.
6664 "$g->close" will call this if you don't do it explicitly, but note
6666 that any errors are ignored in that case.
6667 $g->sleep ($secs);
6669 Sleep for "secs" seconds.
6670 %statbuf = $g->stat ($path);
6672 Returns file information for the given "path".
6673 This is the same as the stat(2) system call.
6675 This function is deprecated. In new code, use the "statns" 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 %statbuf = $g->statns ($path);
6684 Returns file information for the given "path".
6685 This is the same as the stat(2) system call.
6687 %statbuf = $g->statvfs ($path);
6689 Returns file system statistics for any mounted file system. "path"
6690 should be a file or directory in the mounted file system (typically
6691 it is the mount point itself, but it doesn't need to be).
6692 This is the same as the statvfs(2) system call.
6694 @stringsout = $g->strings ($path);
6696 This runs the strings(1) command on a file and returns the list of
6697 printable strings found.
6698 The "strings" command has, in the past, had problems with parsing
6700 untrusted files. These are mitigated in the current version of
6701 libguestfs, but see "CVE-2014-8484" in guestfs(3).
6702 Because of the message protocol, there is a transfer limit of
6704 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
6705 guestfs(3).
6706 @stringsout = $g->strings_e ($encoding, $path);
6708 This is like the "$g->strings" command, but allows you to specify
6709 the encoding of strings that are looked for in the source file
6710 "path".
6711 Allowed encodings are:
6713 s Single 7-bit-byte characters like ASCII and the ASCII-
6715 compatible parts of ISO-8859-X (this is what "$g->strings"
6716 uses).
6717 S Single 8-bit-byte characters.
6719 b 16-bit big endian strings such as those encoded in UTF-16BE or
6721 UCS-2BE.
6722 l (lower case letter L)
6724 16-bit little endian such as UTF-16LE and UCS-2LE. This is
6725 useful for examining binaries in Windows guests.
6726 B 32-bit big endian such as UCS-4BE.
6728 L 32-bit little endian such as UCS-4LE.
6730 The returned strings are transcoded to UTF-8.
6732 The "strings" command has, in the past, had problems with parsing
6734 untrusted files. These are mitigated in the current version of
6735 libguestfs, but see "CVE-2014-8484" in guestfs(3).
6736 Because of the message protocol, there is a transfer limit of
6738 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
6739 guestfs(3).
6740 $g->swapoff_device ($device);
6742 This command disables the libguestfs appliance swap device or
6743 partition named "device". See "$g->swapon_device".
6744 $g->swapoff_file ($file);
6746 This command disables the libguestfs appliance swap on file.
6747 $g->swapoff_label ($label);
6749 This command disables the libguestfs appliance swap on labeled swap
6750 partition.
6751 $g->swapoff_uuid ($uuid);
6753 This command disables the libguestfs appliance swap partition with
6754 the given UUID.
6755 This function depends on the feature "linuxfsuuid". See also
6757 "$g->feature-available".
6758 $g->swapon_device ($device);
6760 This command enables the libguestfs appliance to use the swap
6761 device or partition named "device". The increased memory is made
6762 available for all commands, for example those run using
6763 "$g->command" or "$g->sh".
6764 Note that you should not swap to existing guest swap partitions
6766 unless you know what you are doing. They may contain hibernation
6767 information, or other information that the guest doesn't want you
6768 to trash. You also risk leaking information about the host to the
6769 guest this way. Instead, attach a new host device to the guest and
6770 swap on that.
6771 $g->swapon_file ($file);
6773 This command enables swap to a file. See "$g->swapon_device" for
6774 other notes.
6775 $g->swapon_label ($label);
6777 This command enables swap to a labeled swap partition. See
6778 "$g->swapon_device" for other notes.
6779 $g->swapon_uuid ($uuid);
6781 This command enables swap to a swap partition with the given UUID.
6782 See "$g->swapon_device" for other notes.
6783 This function depends on the feature "linuxfsuuid". See also
6785 "$g->feature-available".
6786 $g->sync ();
6788 This syncs the disk, so that any writes are flushed through to the
6789 underlying disk image.
6790 You should always call this if you have modified a disk image,
6792 before closing the handle.
6793 $g->syslinux ($device [, directory => $directory]);
6795 Install the SYSLINUX bootloader on "device".
6796 The device parameter must be either a whole disk formatted as a FAT
6798 filesystem, or a partition formatted as a FAT filesystem. In the
6799 latter case, the partition should be marked as "active"
6800 ("$g->part_set_bootable") and a Master Boot Record must be
6801 installed (eg. using "$g->pwrite_device") on the first sector of
6802 the whole disk. The SYSLINUX package comes with some suitable
6803 Master Boot Records. See the syslinux(1) man page for further
6804 information.
6805 The optional arguments are:
6807 directory
6809 Install SYSLINUX in the named subdirectory, instead of in the
6810 root directory of the FAT filesystem.
6811 Additional configuration can be supplied to SYSLINUX by placing a
6813 file called syslinux.cfg on the FAT filesystem, either in the root
6814 directory, or under directory if that optional argument is being
6815 used. For further information about the contents of this file, see
6816 syslinux(1).
6817 See also "$g->extlinux".
6819 This function depends on the feature "syslinux". See also
6821 "$g->feature-available".
6822 @lines = $g->tail ($path);
6824 This command returns up to the last 10 lines of a file as a list of
6825 strings.
6826 Because of the message protocol, there is a transfer limit of
6828 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
6829 guestfs(3).
6830 @lines = $g->tail_n ($nrlines, $path);
6832 If the parameter "nrlines" is a positive number, this returns the
6833 last "nrlines" lines of the file "path".
6834 If the parameter "nrlines" is a negative number, this returns lines
6836 from the file "path", starting with the "-nrlines"th line.
6837 If the parameter "nrlines" is zero, this returns an empty list.
6839 Because of the message protocol, there is a transfer limit of
6841 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
6842 guestfs(3).
6843 $g->tar_in ($tarfile, $directory [, compress => $compress] [, xattrs =>
6845 $xattrs] [, selinux => $selinux] [, acls => $acls]);
6846 This command uploads and unpacks local file "tarfile" into
6847 directory.
6848 The optional "compress" flag controls compression. If not given,
6850 then the input should be an uncompressed tar file. Otherwise one
6851 of the following strings may be given to select the compression
6852 type of the input file: "compress", "gzip", "bzip2", "xz", "lzop".
6853 (Note that not all builds of libguestfs will support all of these
6854 compression types).
6855 The other optional arguments are:
6857 "xattrs"
6859 If set to true, extended attributes are restored from the tar
6860 file.
6861 "selinux"
6863 If set to true, SELinux contexts are restored from the tar
6864 file.
6865 "acls"
6867 If set to true, POSIX ACLs are restored from the tar file.
6868 $g->tar_in_opts ($tarfile, $directory [, compress => $compress] [,
6870 xattrs => $xattrs] [, selinux => $selinux] [, acls => $acls]);
6871 This is an alias of "tar_in".
6872 $g->tar_out ($directory, $tarfile [, compress => $compress] [,
6874 numericowner => $numericowner] [, excludes => $excludes] [, xattrs =>
6875 $xattrs] [, selinux => $selinux] [, acls => $acls]);
6876 This command packs the contents of directory and downloads it to
6877 local file "tarfile".
6878 The optional "compress" flag controls compression. If not given,
6880 then the output will be an uncompressed tar file. Otherwise one of
6881 the following strings may be given to select the compression type
6882 of the output file: "compress", "gzip", "bzip2", "xz", "lzop".
6883 (Note that not all builds of libguestfs will support all of these
6884 compression types).
6885 The other optional arguments are:
6887 "excludes"
6889 A list of wildcards. Files are excluded if they match any of
6890 the wildcards.
6891 "numericowner"
6893 If set to true, the output tar file will contain UID/GID
6894 numbers instead of user/group names.
6895 "xattrs"
6897 If set to true, extended attributes are saved in the output
6898 tar.
6899 "selinux"
6901 If set to true, SELinux contexts are saved in the output tar.
6902 "acls"
6904 If set to true, POSIX ACLs are saved in the output tar.
6905 $g->tar_out_opts ($directory, $tarfile [, compress => $compress] [,
6907 numericowner => $numericowner] [, excludes => $excludes] [, xattrs =>
6908 $xattrs] [, selinux => $selinux] [, acls => $acls]);
6909 This is an alias of "tar_out".
6910 $g->tgz_in ($tarball, $directory);
6912 This command uploads and unpacks local file "tarball" (a gzip
6913 compressed tar file) into directory.
6914 This function is deprecated. In new code, use the "tar_in" call
6916 instead.
6917 Deprecated functions will not be removed from the API, but the fact
6919 that they are deprecated indicates that there are problems with
6920 correct use of these functions.
6921 $g->tgz_out ($directory, $tarball);
6923 This command packs the contents of directory and downloads it to
6924 local file "tarball".
6925 This function is deprecated. In new code, use the "tar_out" call
6927 instead.
6928 Deprecated functions will not be removed from the API, but the fact
6930 that they are deprecated indicates that there are problems with
6931 correct use of these functions.
6932 $g->touch ($path);
6934 Touch acts like the touch(1) command. It can be used to update the
6935 timestamps on a file, or, if the file does not exist, to create a
6936 new zero-length file.
6937 This command only works on regular files, and will fail on other
6939 file types such as directories, symbolic links, block special etc.
6940 $g->truncate ($path);
6942 This command truncates "path" to a zero-length file. The file must
6943 exist already.
6944 $g->truncate_size ($path, $size);
6946 This command truncates "path" to size "size" bytes. The file must
6947 exist already.
6948 If the current file size is less than "size" then the file is
6950 extended to the required size with zero bytes. This creates a
6951 sparse file (ie. disk blocks are not allocated for the file until
6952 you write to it). To create a non-sparse file of zeroes, use
6953 "$g->fallocate64" instead.
6954 $g->tune2fs ($device [, force => $force] [, maxmountcount =>
6956 $maxmountcount] [, mountcount => $mountcount] [, errorbehavior =>
6957 $errorbehavior] [, group => $group] [, intervalbetweenchecks =>
6958 $intervalbetweenchecks] [, reservedblockspercentage =>
6959 $reservedblockspercentage] [, lastmounteddirectory =>
6960 $lastmounteddirectory] [, reservedblockscount => $reservedblockscount]
6961 [, user => $user]);
6962 This call allows you to adjust various filesystem parameters of an
6963 ext2/ext3/ext4 filesystem called "device".
6964 The optional parameters are:
6966 "force"
6968 Force tune2fs to complete the operation even in the face of
6969 errors. This is the same as the tune2fs "-f" option.
6970 "maxmountcount"
6972 Set the number of mounts after which the filesystem is checked
6973 by e2fsck(8). If this is 0 then the number of mounts is
6974 disregarded. This is the same as the tune2fs "-c" option.
6975 "mountcount"
6977 Set the number of times the filesystem has been mounted. This
6978 is the same as the tune2fs "-C" option.
6979 "errorbehavior"
6981 Change the behavior of the kernel code when errors are
6982 detected. Possible values currently are: "continue",
6983 "remount-ro", "panic". In practice these options don't really
6984 make any difference, particularly for write errors.
6985 This is the same as the tune2fs "-e" option.
6987 "group"
6989 Set the group which can use reserved filesystem blocks. This
6990 is the same as the tune2fs "-g" option except that it can only
6991 be specified as a number.
6992 "intervalbetweenchecks"
6994 Adjust the maximal time between two filesystem checks (in
6995 seconds). If the option is passed as 0 then time-dependent
6996 checking is disabled.
6997 This is the same as the tune2fs "-i" option.
6999 "reservedblockspercentage"
7001 Set the percentage of the filesystem which may only be
7002 allocated by privileged processes. This is the same as the
7003 tune2fs "-m" option.
7004 "lastmounteddirectory"
7006 Set the last mounted directory. This is the same as the
7007 tune2fs "-M" option.
7008 "reservedblockscount" Set the number of reserved filesystem blocks.
7010 This is the same as the tune2fs "-r" option.
7011 "user"
7012 Set the user who can use the reserved filesystem blocks. This
7013 is the same as the tune2fs "-u" option except that it can only
7014 be specified as a number.
7015 To get the current values of filesystem parameters, see
7017 "$g->tune2fs_l". For precise details of how tune2fs works, see the
7018 tune2fs(8) man page.
7019 %superblock = $g->tune2fs_l ($device);
7021 This returns the contents of the ext2, ext3 or ext4 filesystem
7022 superblock on "device".
7023 It is the same as running "tune2fs -l device". See tune2fs(8)
7025 manpage for more details. The list of fields returned isn't
7026 clearly defined, and depends on both the version of "tune2fs" that
7027 libguestfs was built against, and the filesystem itself.
7028 $g->txz_in ($tarball, $directory);
7030 This command uploads and unpacks local file "tarball" (an xz
7031 compressed tar file) into directory.
7032 This function depends on the feature "xz". See also
7034 "$g->feature-available".
7035 This function is deprecated. In new code, use the "tar_in" call
7037 instead.
7038 Deprecated functions will not be removed from the API, but the fact
7040 that they are deprecated indicates that there are problems with
7041 correct use of these functions.
7042 $g->txz_out ($directory, $tarball);
7044 This command packs the contents of directory and downloads it to
7045 local file "tarball" (as an xz compressed tar archive).
7046 This function depends on the feature "xz". See also
7048 "$g->feature-available".
7049 This function is deprecated. In new code, use the "tar_out" call
7051 instead.
7052 Deprecated functions will not be removed from the API, but the fact
7054 that they are deprecated indicates that there are problems with
7055 correct use of these functions.
7056 $oldmask = $g->umask ($mask);
7058 This function sets the mask used for creating new files and device
7059 nodes to "mask & 0777".
7060 Typical umask values would be 022 which creates new files with
7062 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which
7063 creates new files with permissions like "-rw-rw-r--" or
7064 "-rwxrwxr-x".
7065 The default umask is 022. This is important because it means that
7067 directories and device nodes will be created with 0644 or 0755 mode
7068 even if you specify 0777.
7069 See also "$g->get_umask", umask(2), "$g->mknod", "$g->mkdir".
7071 This call returns the previous umask.
7073 $g->umount ($pathordevice [, force => $force] [, lazyunmount =>
7075 $lazyunmount]);
7076 This unmounts the given filesystem. The filesystem may be
7077 specified either by its mountpoint (path) or the device which
7078 contains the filesystem.
7079 $g->umount_opts ($pathordevice [, force => $force] [, lazyunmount =>
7081 $lazyunmount]);
7082 This is an alias of "umount".
7083 $g->umount_all ();
7085 This unmounts all mounted filesystems.
7086 Some internal mounts are not unmounted by this call.
7088 $g->umount_local ([retry => $retry]);
7090 If libguestfs is exporting the filesystem on a local mountpoint,
7091 then this unmounts it.
7092 See "MOUNT LOCAL" in guestfs(3) for full documentation.
7094 $g->upload ($filename, $remotefilename);
7096 Upload local file filename to remotefilename on the filesystem.
7097 filename can also be a named pipe.
7099 See also "$g->download".
7101 $g->upload_offset ($filename, $remotefilename, $offset);
7103 Upload local file filename to remotefilename on the filesystem.
7104 remotefilename is overwritten starting at the byte "offset"
7106 specified. The intention is to overwrite parts of existing files
7107 or devices, although if a non-existent file is specified then it is
7108 created with a "hole" before "offset". The size of the data
7109 written is implicit in the size of the source filename.
7110 Note that there is no limit on the amount of data that can be
7112 uploaded with this call, unlike with "$g->pwrite", and this call
7113 always writes the full amount unless an error occurs.
7114 See also "$g->upload", "$g->pwrite".
7116 $g->user_cancel ();
7118 This function cancels the current upload or download operation.
7119 Unlike most other libguestfs calls, this function is signal safe
7121 and thread safe. You can call it from a signal handler or from
7122 another thread, without needing to do any locking.
7123 The transfer that was in progress (if there is one) will stop
7125 shortly afterwards, and will return an error. The errno (see
7126 "guestfs_last_errno") is set to "EINTR", so you can test for this
7127 to find out if the operation was cancelled or failed because of
7128 another error.
7129 No cleanup is performed: for example, if a file was being uploaded
7131 then after cancellation there may be a partially uploaded file. It
7132 is the callerXs responsibility to clean up if necessary.
7133 There are two common places that you might call "$g->user_cancel":
7135 In an interactive text-based program, you might call it from a
7137 "SIGINT" signal handler so that pressing "^C" cancels the current
7138 operation. (You also need to call "guestfs_set_pgroup" so that
7139 child processes don't receive the "^C" signal).
7140 In a graphical program, when the main thread is displaying a
7142 progress bar with a cancel button, wire up the cancel button to
7143 call this function.
7144 $g->utimens ($path, $atsecs, $atnsecs, $mtsecs, $mtnsecs);
7146 This command sets the timestamps of a file with nanosecond
7147 precision.
7148 "atsecs, atnsecs" are the last access time (atime) in secs and
7150 nanoseconds from the epoch.
7151 "mtsecs, mtnsecs" are the last modification time (mtime) in secs
7153 and nanoseconds from the epoch.
7154 If the *nsecs field contains the special value "-1" then the
7156 corresponding timestamp is set to the current time. (The *secs
7157 field is ignored in this case).
7158 If the *nsecs field contains the special value "-2" then the
7160 corresponding timestamp is left unchanged. (The *secs field is
7161 ignored in this case).
7162 %uts = $g->utsname ();
7164 This returns the kernel version of the appliance, where this is
7165 available. This information is only useful for debugging. Nothing
7166 in the returned structure is defined by the API.
7167 %version = $g->version ();
7169 Return the libguestfs version number that the program is linked
7170 against.
7171 Note that because of dynamic linking this is not necessarily the
7173 version of libguestfs that you compiled against. You can compile
7174 the program, and then at runtime dynamically link against a
7175 completely different libguestfs.so library.
7176 This call was added in version 1.0.58. In previous versions of
7178 libguestfs there was no way to get the version number. From C code
7179 you can use dynamic linker functions to find out if this symbol
7180 exists (if it doesn't, then itXs an earlier version).
7181 The call returns a structure with four elements. The first three
7183 ("major", "minor" and "release") are numbers and correspond to the
7184 usual version triplet. The fourth element ("extra") is a string
7185 and is normally empty, but may be used for distro-specific
7186 information.
7187 To construct the original version string:
7189 "$major.$minor.$release$extra"
7190 See also: "LIBGUESTFS VERSION NUMBERS" in guestfs(3).
7192 Note: Don't use this call to test for availability of features. In
7194 enterprise distributions we backport features from later versions
7195 into earlier versions, making this an unreliable way to test for
7196 features. Use "$g->available" or "$g->feature_available" instead.
7197 $label = $g->vfs_label ($mountable);
7199 This returns the label of the filesystem on "mountable".
7200 If the filesystem is unlabeled, this returns the empty string.
7202 To find a filesystem from the label, use "$g->findfs_label".
7204 $sizeinbytes = $g->vfs_minimum_size ($mountable);
7206 Get the minimum size of filesystem in bytes. This is the minimum
7207 possible size for filesystem shrinking.
7208 If getting minimum size of specified filesystem is not supported,
7210 this will fail and set errno as ENOTSUP.
7211 See also ntfsresize(8), resize2fs(8), btrfs(8), xfs_info(8).
7213 $fstype = $g->vfs_type ($mountable);
7215 This command gets the filesystem type corresponding to the
7216 filesystem on "mountable".
7217 For most filesystems, the result is the name of the Linux VFS
7219 module which would be used to mount this filesystem if you mounted
7220 it without specifying the filesystem type. For example a string
7221 such as "ext3" or "ntfs".
7222 $uuid = $g->vfs_uuid ($mountable);
7224 This returns the filesystem UUID of the filesystem on "mountable".
7225 If the filesystem does not have a UUID, this returns the empty
7227 string.
7228 To find a filesystem from the UUID, use "$g->findfs_uuid".
7230 $g->vg_activate ($activate, \@volgroups);
7232 This command activates or (if "activate" is false) deactivates all
7233 logical volumes in the listed volume groups "volgroups".
7234 This command is the same as running "vgchange -a y|n volgroups..."
7236 Note that if "volgroups" is an empty list then all volume groups
7238 are activated or deactivated.
7239 This function depends on the feature "lvm2". See also
7241 "$g->feature-available".
7242 $g->vg_activate_all ($activate);
7244 This command activates or (if "activate" is false) deactivates all
7245 logical volumes in all volume groups.
7246 This command is the same as running "vgchange -a y|n"
7248 This function depends on the feature "lvm2". See also
7250 "$g->feature-available".
7251 $g->vgchange_uuid ($vg);
7253 Generate a new random UUID for the volume group "vg".
7254 This function depends on the feature "lvm2". See also
7256 "$g->feature-available".
7257 $g->vgchange_uuid_all ();
7259 Generate new random UUIDs for all volume groups.
7260 This function depends on the feature "lvm2". See also
7262 "$g->feature-available".
7263 $g->vgcreate ($volgroup, \@physvols);
7265 This creates an LVM volume group called "volgroup" from the non-
7266 empty list of physical volumes "physvols".
7267 This function depends on the feature "lvm2". See also
7269 "$g->feature-available".
7270 @uuids = $g->vglvuuids ($vgname);
7272 Given a VG called "vgname", this returns the UUIDs of all the
7273 logical volumes created in this volume group.
7274 You can use this along with "$g->lvs" and "$g->lvuuid" calls to
7276 associate logical volumes and volume groups.
7277 See also "$g->vgpvuuids".
7279 $metadata = $g->vgmeta ($vgname);
7281 "vgname" is an LVM volume group. This command examines the volume
7282 group and returns its metadata.
7283 Note that the metadata is an internal structure used by LVM,
7285 subject to change at any time, and is provided for information
7286 only.
7287 This function depends on the feature "lvm2". See also
7289 "$g->feature-available".
7290 @uuids = $g->vgpvuuids ($vgname);
7292 Given a VG called "vgname", this returns the UUIDs of all the
7293 physical volumes that this volume group resides on.
7294 You can use this along with "$g->pvs" and "$g->pvuuid" calls to
7296 associate physical volumes and volume groups.
7297 See also "$g->vglvuuids".
7299 $g->vgremove ($vgname);
7301 Remove an LVM volume group "vgname", (for example "VG").
7302 This also forcibly removes all logical volumes in the volume group
7304 (if any).
7305 This function depends on the feature "lvm2". See also
7307 "$g->feature-available".
7308 $g->vgrename ($volgroup, $newvolgroup);
7310 Rename a volume group "volgroup" with the new name "newvolgroup".
7311 @volgroups = $g->vgs ();
7313 List all the volumes groups detected. This is the equivalent of
7314 the vgs(8) command.
7315 This returns a list of just the volume group names that were
7317 detected (eg. "VolGroup00").
7318 See also "$g->vgs_full".
7320 This function depends on the feature "lvm2". See also
7322 "$g->feature-available".
7323 @volgroups = $g->vgs_full ();
7325 List all the volumes groups detected. This is the equivalent of
7326 the vgs(8) command. The "full" version includes all fields.
7327 This function depends on the feature "lvm2". See also
7329 "$g->feature-available".
7330 $g->vgscan ();
7332 This rescans all block devices and rebuilds the list of LVM
7333 physical volumes, volume groups and logical volumes.
7334 $uuid = $g->vguuid ($vgname);
7336 This command returns the UUID of the LVM VG named "vgname".
7337 $g->wait_ready ();
7339 This function is a no op.
7340 In versions of the API < 1.0.71 you had to call this function just
7342 after calling "$g->launch" to wait for the launch to complete.
7343 However this is no longer necessary because "$g->launch" now does
7344 the waiting.
7345 If you see any calls to this function in code then you can just
7347 remove them, unless you want to retain compatibility with older
7348 versions of the API.
7349 This function is deprecated. There is no replacement. Consult the
7351 API documentation in guestfs(3) for further information.
7352 Deprecated functions will not be removed from the API, but the fact
7354 that they are deprecated indicates that there are problems with
7355 correct use of these functions.
7356 $chars = $g->wc_c ($path);
7358 This command counts the characters in a file, using the "wc -c"
7359 external command.
7360 $lines = $g->wc_l ($path);
7362 This command counts the lines in a file, using the "wc -l" external
7363 command.
7364 $words = $g->wc_w ($path);
7366 This command counts the words in a file, using the "wc -w" external
7367 command.
7368 $g->wipefs ($device);
7370 This command erases filesystem or RAID signatures from the
7371 specified "device" to make the filesystem invisible to libblkid.
7372 This does not erase the filesystem itself nor any other data from
7374 the "device".
7375 Compare with "$g->zero" which zeroes the first few blocks of a
7377 device.
7378 This function depends on the feature "wipefs". See also
7380 "$g->feature-available".
7381 $g->write ($path, $content);
7383 This call creates a file called "path". The content of the file is
7384 the string "content" (which can contain any 8 bit data).
7385 See also "$g->write_append".
7387 $g->write_append ($path, $content);
7389 This call appends "content" to the end of file "path". If "path"
7390 does not exist, then a new file is created.
7391 See also "$g->write".
7393 $g->write_file ($path, $content, $size);
7395 This call creates a file called "path". The contents of the file
7396 is the string "content" (which can contain any 8 bit data), with
7397 length "size".
7398 As a special case, if "size" is 0 then the length is calculated
7400 using "strlen" (so in this case the content cannot contain embedded
7401 ASCII NULs).
7402 NB. Owing to a bug, writing content containing ASCII NUL characters
7404 does not work, even if the length is specified.
7405 Because of the message protocol, there is a transfer limit of
7407 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7408 guestfs(3).
7409 This function is deprecated. In new code, use the "write" call
7411 instead.
7412 Deprecated functions will not be removed from the API, but the fact
7414 that they are deprecated indicates that there are problems with
7415 correct use of these functions.
7416 $g->xfs_admin ($device [, extunwritten => $extunwritten] [, imgfile =>
7418 $imgfile] [, v2log => $v2log] [, projid32bit => $projid32bit] [,
7419 lazycounter => $lazycounter] [, label => $label] [, uuid => $uuid]);
7420 Change the parameters of the XFS filesystem on "device".
7421 Devices that are mounted cannot be modified. Administrators must
7423 unmount filesystems before this call can modify parameters.
7424 Some of the parameters of a mounted filesystem can be examined and
7426 modified using the "$g->xfs_info" and "$g->xfs_growfs" calls.
7427 This function depends on the feature "xfs". See also
7429 "$g->feature-available".
7430 $g->xfs_growfs ($path [, datasec => $datasec] [, logsec => $logsec] [,
7432 rtsec => $rtsec] [, datasize => $datasize] [, logsize => $logsize] [,
7433 rtsize => $rtsize] [, rtextsize => $rtextsize] [, maxpct => $maxpct]);
7434 Grow the XFS filesystem mounted at "path".
7435 The returned struct contains geometry information. Missing fields
7437 are returned as "-1" (for numeric fields) or empty string.
7438 This function depends on the feature "xfs". See also
7440 "$g->feature-available".
7441 %info = $g->xfs_info ($pathordevice);
7443 "pathordevice" is a mounted XFS filesystem or a device containing
7444 an XFS filesystem. This command returns the geometry of the
7445 filesystem.
7446 The returned struct contains geometry information. Missing fields
7448 are returned as "-1" (for numeric fields) or empty string.
7449 This function depends on the feature "xfs". See also
7451 "$g->feature-available".
7452 $status = $g->xfs_repair ($device [, forcelogzero => $forcelogzero] [,
7454 nomodify => $nomodify] [, noprefetch => $noprefetch] [, forcegeometry
7455 => $forcegeometry] [, maxmem => $maxmem] [, ihashsize => $ihashsize] [,
7456 bhashsize => $bhashsize] [, agstride => $agstride] [, logdev =>
7457 $logdev] [, rtdev => $rtdev]);
7458 Repair corrupt or damaged XFS filesystem on "device".
7459 The filesystem is specified using the "device" argument which
7461 should be the device name of the disk partition or volume
7462 containing the filesystem. If given the name of a block device,
7463 "xfs_repair" will attempt to find the raw device associated with
7464 the specified block device and will use the raw device instead.
7465 Regardless, the filesystem to be repaired must be unmounted,
7467 otherwise, the resulting filesystem may be inconsistent or corrupt.
7468 The returned status indicates whether filesystem corruption was
7470 detected (returns 1) or was not detected (returns 0).
7471 This function depends on the feature "xfs". See also
7473 "$g->feature-available".
7474 $g->yara_destroy ();
7476 Destroy previously loaded Yara rules in order to free libguestfs
7477 resources.
7478 This function depends on the feature "libyara". See also
7480 "$g->feature-available".
7481 $g->yara_load ($filename);
7483 Upload a set of Yara rules from local file filename.
7484 Yara rules allow to categorize files based on textual or binary
7486 patterns within their content. See "$g->yara_scan" to see how to
7487 scan files with the loaded rules.
7488 Rules can be in binary format, as when compiled with yarac command,
7490 or in source code format. In the latter case, the rules will be
7491 first compiled and then loaded.
7492 Rules in source code format cannot include external files. In such
7494 cases, it is recommended to compile them first.
7495 Previously loaded rules will be destroyed.
7497 This function depends on the feature "libyara". See also
7499 "$g->feature-available".
7500 @detections = $g->yara_scan ($path);
7502 Scan a file with the previously loaded Yara rules.
7503 For each matching rule, a "yara_detection" structure is returned.
7505 The "yara_detection" structure contains the following fields.
7507 "yara_name"
7509 Path of the file matching a Yara rule.
7510 "yara_rule"
7512 Identifier of the Yara rule which matched against the given
7513 file.
7514 This function depends on the feature "libyara". See also
7516 "$g->feature-available".
7517 @lines = $g->zegrep ($regex, $path);
7519 This calls the external "zegrep" program and returns the matching
7520 lines.
7521 Because of the message protocol, there is a transfer limit of
7523 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7524 guestfs(3).
7525 This function is deprecated. In new code, use the "grep" call
7527 instead.
7528 Deprecated functions will not be removed from the API, but the fact
7530 that they are deprecated indicates that there are problems with
7531 correct use of these functions.
7532 @lines = $g->zegrepi ($regex, $path);
7534 This calls the external "zegrep -i" program and returns the
7535 matching lines.
7536 Because of the message protocol, there is a transfer limit of
7538 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7539 guestfs(3).
7540 This function is deprecated. In new code, use the "grep" call
7542 instead.
7543 Deprecated functions will not be removed from the API, but the fact
7545 that they are deprecated indicates that there are problems with
7546 correct use of these functions.
7547 $g->zero ($device);
7549 This command writes zeroes over the first few blocks of "device".
7550 How many blocks are zeroed isn't specified (but itXs not enough to
7552 securely wipe the device). It should be sufficient to remove any
7553 partition tables, filesystem superblocks and so on.
7554 If blocks are already zero, then this command avoids writing
7556 zeroes. This prevents the underlying device from becoming non-
7557 sparse or growing unnecessarily.
7558 See also: "$g->zero_device", "$g->scrub_device",
7560 "$g->is_zero_device"
7561 $g->zero_device ($device);
7563 This command writes zeroes over the entire "device". Compare with
7564 "$g->zero" which just zeroes the first few blocks of a device.
7565 If blocks are already zero, then this command avoids writing
7567 zeroes. This prevents the underlying device from becoming non-
7568 sparse or growing unnecessarily.
7569 $g->zero_free_space ($directory);
7571 Zero the free space in the filesystem mounted on directory. The
7572 filesystem must be mounted read-write.
7573 The filesystem contents are not affected, but any free space in the
7575 filesystem is freed.
7576 Free space is not "trimmed". You may want to call "$g->fstrim"
7578 either as an alternative to this, or after calling this, depending
7579 on your requirements.
7580 $g->zerofree ($device);
7582 This runs the zerofree program on "device". This program claims to
7583 zero unused inodes and disk blocks on an ext2/3 filesystem, thus
7584 making it possible to compress the filesystem more effectively.
7585 You should not run this program if the filesystem is mounted.
7587 It is possible that using this program can damage the filesystem or
7589 data on the filesystem.
7590 This function depends on the feature "zerofree". See also
7592 "$g->feature-available".
7593 @lines = $g->zfgrep ($pattern, $path);
7595 This calls the external "zfgrep" program and returns the matching
7596 lines.
7597 Because of the message protocol, there is a transfer limit of
7599 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7600 guestfs(3).
7601 This function is deprecated. In new code, use the "grep" call
7603 instead.
7604 Deprecated functions will not be removed from the API, but the fact
7606 that they are deprecated indicates that there are problems with
7607 correct use of these functions.
7608 @lines = $g->zfgrepi ($pattern, $path);
7610 This calls the external "zfgrep -i" program and returns the
7611 matching lines.
7612 Because of the message protocol, there is a transfer limit of
7614 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7615 guestfs(3).
7616 This function is deprecated. In new code, use the "grep" call
7618 instead.
7619 Deprecated functions will not be removed from the API, but the fact
7621 that they are deprecated indicates that there are problems with
7622 correct use of these functions.
7623 $description = $g->zfile ($meth, $path);
7625 This command runs file after first decompressing "path" using
7626 "method".
7627 "method" must be one of "gzip", "compress" or "bzip2".
7629 Since 1.0.63, use "$g->file" instead which can now process
7631 compressed files.
7632 This function is deprecated. In new code, use the "file" call
7634 instead.
7635 Deprecated functions will not be removed from the API, but the fact
7637 that they are deprecated indicates that there are problems with
7638 correct use of these functions.
7639 @lines = $g->zgrep ($regex, $path);
7641 This calls the external "zgrep" program and returns the matching
7642 lines.
7643 Because of the message protocol, there is a transfer limit of
7645 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7646 guestfs(3).
7647 This function is deprecated. In new code, use the "grep" call
7649 instead.
7650 Deprecated functions will not be removed from the API, but the fact
7652 that they are deprecated indicates that there are problems with
7653 correct use of these functions.
7654 @lines = $g->zgrepi ($regex, $path);
7656 This calls the external "zgrep -i" program and returns the matching
7657 lines.
7658 Because of the message protocol, there is a transfer limit of
7660 somewhere between 2MB and 4MB. See "PROTOCOL LIMITS" in
7661 guestfs(3).
7662 This function is deprecated. In new code, use the "grep" call
7664 instead.
7665 Deprecated functions will not be removed from the API, but the fact
7667 that they are deprecated indicates that there are problems with
7668 correct use of these functions.
7669
7671 From time to time we add new libguestfs APIs. Also some libguestfs
7672 APIs won't be available in all builds of libguestfs (the Fedora build
7673 is full-featured, but other builds may disable features). How do you
7674 test whether the APIs that your Perl program needs are available in the
7675 version of "Sys::Guestfs" that you are using?
7676 To test if a particular function is available in the "Sys::Guestfs"
7678 class, use the ordinary Perl UNIVERSAL method "can(METHOD)" (see
7679 perlobj(1)). For example:
7680 use Sys::Guestfs;
7682 if (defined (Sys::Guestfs->can ("set_verbose"))) {
7683 print "\$g->set_verbose is available\n";
7684 }
7685 To test if particular features are supported by the current build, use
7687 the "feature_available" method like the example below. Note that the
7688 appliance must be launched first.
7689 $g->feature_available ( ["augeas"] );
7691 For further discussion on this topic, refer to "AVAILABILITY" in
7693 guestfs(3).
7694
7696 The handle returned from "new" is a hash reference. The hash normally
7697 contains some elements:
7698 {
7700 _g => [private data used by libguestfs],
7701 _flags => [flags provided when creating the handle]
7702 }
7703 Callers can add other elements to this hash to store data for their own
7705 purposes. The data lasts for the lifetime of the handle.
7706 Any fields whose names begin with an underscore are reserved for
7708 private use by libguestfs. We may add more in future.
7709 It is recommended that callers prefix the name of their field(s) with
7711 some unique string, to avoid conflicts with other users.
7712
7714 Copyright (C) 2009-2019 Red Hat Inc.
7715
7717 Please see the file COPYING.LIB for the full license.
7718
7720 guestfs(3), guestfish(1), <http://libguestfs.org>.
7721perl v5.16.3 2019-03-14 Sys::Guestfs(3)