1Sys::Guestfs(3)       User Contributed Perl Documentation      Sys::Guestfs(3)
2
3
4

NAME

6       Sys::Guestfs - Perl bindings for libguestfs
7

SYNOPSIS

9        use Sys::Guestfs;
10
11        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

DESCRIPTION

20       The "Sys::Guestfs" module provides a Perl XS binding to the libguestfs
21       API for examining and modifying virtual machine disk images.
22
23       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
29       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
34       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

ERRORS

39       All errors turn into calls to "croak" (see Carp(3)).
40
41       The error string from libguestfs is directly available from $@.  Use
42       the "last_errno" method if you want to get the errno.
43

METHODS

45       $g = Sys::Guestfs->new ([environment => 0,] [close_on_exit => 0]);
46           Create a new guestfs handle.
47
48           If the optional argument "environment" is false, then the
49           "GUESTFS_CREATE_NO_ENVIRONMENT" flag is set.
50
51           If the optional argument "close_on_exit" is false, then the
52           "GUESTFS_CREATE_NO_CLOSE_ON_EXIT" flag is set.
53
54       $g->close ();
55           Explicitly close the guestfs handle.
56
57           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
67       $Sys::Guestfs::EVENT_CLOSE
68           See "GUESTFS_EVENT_CLOSE" in guestfs(3).
69
70       $Sys::Guestfs::EVENT_SUBPROCESS_QUIT
71           See "GUESTFS_EVENT_SUBPROCESS_QUIT" in guestfs(3).
72
73       $Sys::Guestfs::EVENT_LAUNCH_DONE
74           See "GUESTFS_EVENT_LAUNCH_DONE" in guestfs(3).
75
76       $Sys::Guestfs::EVENT_PROGRESS
77           See "GUESTFS_EVENT_PROGRESS" in guestfs(3).
78
79       $Sys::Guestfs::EVENT_APPLIANCE
80           See "GUESTFS_EVENT_APPLIANCE" in guestfs(3).
81
82       $Sys::Guestfs::EVENT_LIBRARY
83           See "GUESTFS_EVENT_LIBRARY" in guestfs(3).
84
85       $Sys::Guestfs::EVENT_TRACE
86           See "GUESTFS_EVENT_TRACE" in guestfs(3).
87
88       $Sys::Guestfs::EVENT_ENTER
89           See "GUESTFS_EVENT_ENTER" in guestfs(3).
90
91       $Sys::Guestfs::EVENT_LIBVIRT_AUTH
92           See "GUESTFS_EVENT_LIBVIRT_AUTH" in guestfs(3).
93
94       $Sys::Guestfs::EVENT_WARNING
95           See "GUESTFS_EVENT_WARNING" in guestfs(3).
96
97       $Sys::Guestfs::EVENT_ALL
98           See "GUESTFS_EVENT_ALL" in guestfs(3).
99
100       $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
105           This function returns an event handle which can be used to delete
106           the callback using "delete_event_callback".
107
108           The callback function receives 4 parameters:
109
110            &cb ($event, $event_handle, $buf, $array)
111
112           $event
113               The event which happened (equal to one of
114               "$Sys::Guestfs::EVENT_*").
115
116           $event_handle
117               The event handle.
118
119           $buf
120               For some event types, this is a message buffer (ie. a string).
121
122           $array
123               For some event types (notably progress events), this is an
124               array of integers.
125
126           You should carefully read the documentation for
127           "guestfs_set_event_callback" in guestfs(3) before using this
128           function.
129
130       $g->delete_event_callback ($event_handle);
131           This removes the callback which was previously registered using
132           "set_event_callback".
133
134       $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
138           Note that this is a class function, not a method.
139
140       $errnum = $g->last_errno ();
141           This returns the last error number (errno) that happened on the
142           handle $g.
143
144           If successful, an errno integer not equal to zero is returned.
145
146           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
150           You can use the standard Perl module Errno(3) to compare the
151           numeric error returned from this call with symbolic errnos:
152
153            $g->mkdir ("/foo");
154            if ($g->last_errno() == Errno::EEXIST()) {
155              # mkdir failed because the directory exists already.
156            }
157
158       $g->acl_delete_def_file ($dir);
159           This function deletes the default POSIX Access Control List (ACL)
160           attached to directory "dir".
161
162           This function depends on the feature "acl".  See also
163           "$g->feature-available".
164
165       $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
169           The "acltype" parameter may be:
170
171           "access"
172               Return the ordinary (access) ACL for any file, directory or
173               other filesystem object.
174
175           "default"
176               Return the default ACL.  Normally this only makes sense if
177               "path" is a directory.
178
179           This function depends on the feature "acl".  See also
180           "$g->feature-available".
181
182       $g->acl_set_file ($path, $acltype, $acl);
183           This function sets the POSIX Access Control List (ACL) attached to
184           "path".
185
186           The "acltype" parameter may be:
187
188           "access"
189               Set the ordinary (access) ACL for any file, directory or other
190               filesystem object.
191
192           "default"
193               Set the default ACL.  Normally this only makes sense if "path"
194               is a directory.
195
196           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
201           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
206            u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx
207            \ Unix permissions / \mask/ \      ACL        /
208
209           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
213           This function depends on the feature "acl".  See also
214           "$g->feature-available".
215
216       $g->add_cdrom ($filename);
217           This function adds a virtual CD-ROM disk image to the guest.
218
219           The image is added as read-only drive, so this function is
220           equivalent of "$g->add_drive_ro".
221
222           This function is deprecated.  In new code, use the "add_drive_ro"
223           call instead.
224
225           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
229       $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
238           The number of disks added is returned.  This operation is atomic:
239           if an error is returned, then no disks are added.
240
241           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
245           Disks must be accessible locally.  This often means that adding
246           disks from a remote libvirt connection (see
247           <https://libvirt.org/remote.html>) will fail unless those disks are
248           accessible via the same device path locally too.
249
250           The optional "libvirturi" parameter sets the libvirt URI (see
251           <https://libvirt.org/uri.html>).  If this is not set then we
252           connect to the default libvirt URI (or one set through an
253           environment variable, see the libvirt documentation for full
254           details).
255
256           The optional "live" flag is ignored in libguestfs ≥ 1.48.
257
258           If the "allowuuid" flag is true (default is false) then a UUID may
259           be passed instead of the domain name.  The "dom" string is treated
260           as a UUID first and looked up, and if that lookup fails then we
261           treat "dom" as a name as usual.
262
263           The optional "readonlydisk" parameter controls what we do for disks
264           which are marked <readonly/> in the libvirt XML.  Possible values
265           are:
266
267           readonlydisk = "error"
268               If "readonly" is false:
269
270               The whole call is aborted with an error if any disk with the
271               <readonly/> flag is found.
272
273               If "readonly" is true:
274
275               Disks with the <readonly/> flag are added read-only.
276
277           readonlydisk = "read"
278               If "readonly" is false:
279
280               Disks with the <readonly/> flag are added read-only.  Other
281               disks are added read/write.
282
283               If "readonly" is true:
284
285               Disks with the <readonly/> flag are added read-only.
286
287           readonlydisk = "write" (default)
288               If "readonly" is false:
289
290               Disks with the <readonly/> flag are added read/write.
291
292               If "readonly" is true:
293
294               Disks with the <readonly/> flag are added read-only.
295
296           readonlydisk = "ignore"
297               If "readonly" is true or false:
298
299               Disks with the <readonly/> flag are skipped.
300
301           If present, the value of "logical_block_size" attribute of
302           <blockio/> tag in libvirt XML will be passed as "blocksize"
303           parameter to "$g->add_drive_opts".
304
305           The other optional parameters are passed directly through to
306           "$g->add_drive_opts".
307
308       $g->add_drive ($filename [, readonly => $readonly] [, format =>
309       $format] [, iface => $iface] [, name => $name] [, label => $label] [,
310       protocol => $protocol] [, server => $server] [, username => $username]
311       [, secret => $secret] [, cachemode => $cachemode] [, discard =>
312       $discard] [, copyonread => $copyonread] [, blocksize => $blocksize]);
313           This function adds a disk image called filename to the handle.
314           filename may be a regular host file or a host device.
315
316           When this function is called before "$g->launch" (the usual case)
317           then the first time you call this function, the disk appears in the
318           API as /dev/sda, the second time as /dev/sdb, and so on.
319
320           You don't necessarily need to be root when using libguestfs.
321           However you obviously do need sufficient permissions to access the
322           filename for whatever operations you want to perform (ie. read
323           access if you just want to read the image or write access if you
324           want to modify the image).
325
326           This call checks that filename exists.
327
328           filename may be the special string "/dev/null".  See "NULL DISKS"
329           in guestfs(3).
330
331           The optional arguments are:
332
333           "readonly"
334               If true then the image is treated as read-only.  Writes are
335               still allowed, but they are stored in a temporary snapshot
336               overlay which is discarded at the end.  The disk that you add
337               is not modified.
338
339           "format"
340               This forces the image format.  If you omit this (or use
341               "$g->add_drive" or "$g->add_drive_ro") then the format is
342               automatically detected.  Possible formats include "raw" and
343               "qcow2".
344
345               Automatic detection of the format opens you up to a potential
346               security hole when dealing with untrusted raw-format images.
347               See CVE-2010-3851 and RHBZ#642934.  Specifying the format
348               closes this security hole.
349
350           "iface"
351               This rarely-used option lets you emulate the behaviour of the
352               deprecated "$g->add_drive_with_if" call (q.v.)
353
354           "name"
355               This field used to be passed as a hint for guest inspection,
356               but it is no longer used.
357
358           "label"
359               Give the disk a label.  The label should be a unique, short
360               string using only ASCII characters "[a-zA-Z]".  As well as its
361               usual name in the API (such as /dev/sda), the drive will also
362               be named /dev/disk/guestfs/label.
363
364               See "DISK LABELS" in guestfs(3).
365
366           "protocol"
367               The optional protocol argument can be used to select an
368               alternate source protocol.
369
370               See also: "REMOTE STORAGE" in guestfs(3).
371
372               "protocol = "file""
373                   filename is interpreted as a local file or device.  This is
374                   the default if the optional protocol parameter is omitted.
375
376               "protocol = "ftp"|"ftps"|"http"|"https"|"tftp""
377                   Connect to a remote FTP, HTTP or TFTP server.  The "server"
378                   parameter must also be supplied - see below.
379
380                   See also: "FTP, HTTP AND TFTP" in guestfs(3)
381
382               "protocol = "gluster""
383                   Connect to the GlusterFS server.  The "server" parameter
384                   must also be supplied - see below.
385
386                   See also: "GLUSTER" in guestfs(3)
387
388               "protocol = "iscsi""
389                   Connect to the iSCSI server.  The "server" parameter must
390                   also be supplied - see below.  The "username" parameter may
391                   be supplied.  See below.  The "secret" parameter may be
392                   supplied.  See below.
393
394                   See also: "ISCSI" in guestfs(3).
395
396               "protocol = "nbd""
397                   Connect to the Network Block Device server.  The "server"
398                   parameter must also be supplied - see below.
399
400                   See also: "NETWORK BLOCK DEVICE" in guestfs(3).
401
402               "protocol = "rbd""
403                   Connect to the Ceph (librbd/RBD) server.  The "server"
404                   parameter must also be supplied - see below.  The
405                   "username" parameter may be supplied.  See below.  The
406                   "secret" parameter may be supplied.  See below.
407
408                   See also: "CEPH" in guestfs(3).
409
410               "protocol = "sheepdog""
411                   Connect to the Sheepdog server.  The "server" parameter may
412                   also be supplied - see below.
413
414                   See also: "SHEEPDOG" in guestfs(3).
415
416               "protocol = "ssh""
417                   Connect to the Secure Shell (ssh) server.
418
419                   The "server" parameter must be supplied.  The "username"
420                   parameter may be supplied.  See below.
421
422                   See also: "SSH" in guestfs(3).
423
424           "server"
425               For protocols which require access to a remote server, this is
426               a list of server(s).
427
428                Protocol       Number of servers required
429                --------       --------------------------
430                file           List must be empty or param not used at all
431                ftp|ftps|http|https|tftp  Exactly one
432                gluster        Exactly one
433                iscsi          Exactly one
434                nbd            Exactly one
435                rbd            Zero or more
436                sheepdog       Zero or more
437                ssh            Exactly one
438
439               Each list element is a string specifying a server.  The string
440               must be in one of the following formats:
441
442                hostname
443                hostname:port
444                tcp:hostname
445                tcp:hostname:port
446                unix:/path/to/socket
447
448               If the port number is omitted, then the standard port number
449               for the protocol is used (see /etc/services).
450
451           "username"
452               For the "ftp", "ftps", "http", "https", "iscsi", "rbd", "ssh"
453               and "tftp" protocols, this specifies the remote username.
454
455               If not given, then the local username is used for "ssh", and no
456               authentication is attempted for ceph.  But note this sometimes
457               may give unexpected results, for example if using the libvirt
458               backend and if the libvirt backend is configured to start the
459               qemu appliance as a special user such as "qemu.qemu".  If in
460               doubt, specify the remote username you want.
461
462           "secret"
463               For the "rbd" protocol only, this specifies the ‘secret’ to use
464               when connecting to the remote device.  It must be base64
465               encoded.
466
467               If not given, then a secret matching the given username will be
468               looked up in the default keychain locations, or if no username
469               is given, then no authentication will be used.
470
471           "cachemode"
472               Choose whether or not libguestfs will obey sync operations
473               (safe but slow) or not (unsafe but fast).  The possible values
474               for this string are:
475
476               "cachemode = "writeback""
477                   This is the default.
478
479                   Write operations in the API do not return until a write(2)
480                   call has completed in the host [but note this does not
481                   imply that anything gets written to disk].
482
483                   Sync operations in the API, including implicit syncs caused
484                   by filesystem journalling, will not return until an
485                   fdatasync(2) call has completed in the host, indicating
486                   that data has been committed to disk.
487
488               "cachemode = "unsafe""
489                   In this mode, there are no guarantees.  Libguestfs may
490                   cache anything and ignore sync requests.  This is suitable
491                   only for scratch or temporary disks.
492
493           "discard"
494               Enable or disable discard (a.k.a. trim or unmap) support on
495               this drive.  If enabled, operations such as "$g->fstrim" will
496               be able to discard / make thin / punch holes in the underlying
497               host file or device.
498
499               Possible discard settings are:
500
501               "discard = "disable""
502                   Disable discard support.  This is the default.
503
504               "discard = "enable""
505                   Enable discard support.  Fail if discard is not possible.
506
507               "discard = "besteffort""
508                   Enable discard support if possible, but don't fail if it is
509                   not supported.
510
511                   Since not all backends and not all underlying systems
512                   support discard, this is a good choice if you want to use
513                   discard if possible, but don't mind if it doesn't work.
514
515           "copyonread"
516               The boolean parameter "copyonread" enables copy-on-read
517               support.  This only affects disk formats which have backing
518               files, and causes reads to be stored in the overlay layer,
519               speeding up multiple reads of the same area of disk.
520
521               The default is false.
522
523           "blocksize"
524               This parameter sets the sector size of the disk.  Possible
525               values are 512 (the default if the parameter is omitted) or
526               4096.  Use 4096 when handling an "Advanced Format" disk that
527               uses 4K sector size
528               (<https://en.wikipedia.org/wiki/Advanced_Format>).
529
530               Only a subset of the backends support this parameter (currently
531               only the libvirt and direct backends do).
532
533       $g->add_drive_opts ($filename [, readonly => $readonly] [, format =>
534       $format] [, iface => $iface] [, name => $name] [, label => $label] [,
535       protocol => $protocol] [, server => $server] [, username => $username]
536       [, secret => $secret] [, cachemode => $cachemode] [, discard =>
537       $discard] [, copyonread => $copyonread] [, blocksize => $blocksize]);
538           This is an alias of "add_drive".
539
540       $g->add_drive_ro ($filename);
541           This function is the equivalent of calling "$g->add_drive_opts"
542           with the optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set
543           to 1, so the disk is added read-only, with the format being
544           detected automatically.
545
546       $g->add_drive_ro_with_if ($filename, $iface);
547           This is the same as "$g->add_drive_ro" but it allows you to specify
548           the QEMU interface emulation to use at run time.  Both the direct
549           and the libvirt backends ignore "iface".
550
551           This function is deprecated.  In new code, use the "add_drive" call
552           instead.
553
554           Deprecated functions will not be removed from the API, but the fact
555           that they are deprecated indicates that there are problems with
556           correct use of these functions.
557
558       $g->add_drive_scratch ($size [, name => $name] [, label => $label] [,
559       blocksize => $blocksize]);
560           This command adds a temporary scratch drive to the handle.  The
561           "size" parameter is the virtual size (in bytes).  The scratch drive
562           is blank initially (all reads return zeroes until you start writing
563           to it).  The drive is deleted when the handle is closed.
564
565           The optional arguments "name", "label" and "blocksize" are passed
566           through to "$g->add_drive_opts".
567
568       $g->add_drive_with_if ($filename, $iface);
569           This is the same as "$g->add_drive" but it allows you to specify
570           the QEMU interface emulation to use at run time.  Both the direct
571           and the libvirt backends ignore "iface".
572
573           This function is deprecated.  In new code, use the "add_drive" call
574           instead.
575
576           Deprecated functions will not be removed from the API, but the fact
577           that they are deprecated indicates that there are problems with
578           correct use of these functions.
579
580       $nrdisks = $g->add_libvirt_dom ($dom [, readonly => $readonly] [, iface
581       => $iface] [, live => $live] [, readonlydisk => $readonlydisk] [,
582       cachemode => $cachemode] [, discard => $discard] [, copyonread =>
583       $copyonread]);
584           This function adds the disk(s) attached to the libvirt domain
585           "dom".  It works by requesting the domain XML from libvirt, parsing
586           it for disks, and calling "$g->add_drive_opts" on each one.
587
588           In the C API we declare "void *dom", but really it has type
589           "virDomainPtr dom".  This is so we don't need <libvirt.h>.
590
591           The number of disks added is returned.  This operation is atomic:
592           if an error is returned, then no disks are added.
593
594           This function does some minimal checks to make sure the libvirt
595           domain is not running (unless "readonly" is true).  In a future
596           version we will try to acquire the libvirt lock on each disk.
597
598           Disks must be accessible locally.  This often means that adding
599           disks from a remote libvirt connection (see
600           <https://libvirt.org/remote.html>) will fail unless those disks are
601           accessible via the same device path locally too.
602
603           The optional "live" flag is ignored in libguestfs ≥ 1.48.
604
605           The optional "readonlydisk" parameter controls what we do for disks
606           which are marked <readonly/> in the libvirt XML.  See
607           "$g->add_domain" for possible values.
608
609           If present, the value of "logical_block_size" attribute of
610           <blockio/> tag in libvirt XML will be passed as "blocksize"
611           parameter to "$g->add_drive_opts".
612
613           The other optional parameters are passed directly through to
614           "$g->add_drive_opts".
615
616       $g->aug_clear ($augpath);
617           Set the value associated with "path" to "NULL".  This is the same
618           as the augtool(1) "clear" command.
619
620       $g->aug_close ();
621           Close the current Augeas handle and free up any resources used by
622           it.  After calling this, you have to call "$g->aug_init" again
623           before you can use any other Augeas functions.
624
625       %nrnodescreated = $g->aug_defnode ($name, $expr, $val);
626           Defines a variable "name" whose value is the result of evaluating
627           "expr".
628
629           If "expr" evaluates to an empty nodeset, a node is created,
630           equivalent to calling "$g->aug_set" "expr", "val".  "name" will be
631           the nodeset containing that single node.
632
633           On success this returns a pair containing the number of nodes in
634           the nodeset, and a boolean flag if a node was created.
635
636       $nrnodes = $g->aug_defvar ($name, $expr);
637           Defines an Augeas variable "name" whose value is the result of
638           evaluating "expr".  If "expr" is NULL, then "name" is undefined.
639
640           On success this returns the number of nodes in "expr", or 0 if
641           "expr" evaluates to something which is not a nodeset.
642
643       $val = $g->aug_get ($augpath);
644           Look up the value associated with "path".  If "path" matches
645           exactly one node, the "value" is returned.
646
647       $g->aug_init ($root, $flags);
648           Create a new Augeas handle for editing configuration files.  If
649           there was any previous Augeas handle associated with this guestfs
650           session, then it is closed.
651
652           You must call this before using any other "$g->aug_*" commands.
653
654           "root" is the filesystem root.  "root" must not be NULL, use /
655           instead.
656
657           The flags are the same as the flags defined in <augeas.h>, the
658           logical or of the following integers:
659
660           "AUG_SAVE_BACKUP" = 1
661               Keep the original file with a ".augsave" extension.
662
663           "AUG_SAVE_NEWFILE" = 2
664               Save changes into a file with extension ".augnew", and do not
665               overwrite original.  Overrides "AUG_SAVE_BACKUP".
666
667           "AUG_TYPE_CHECK" = 4
668               Typecheck lenses.
669
670               This option is only useful when debugging Augeas lenses.  Use
671               of this option may require additional memory for the libguestfs
672               appliance.  You may need to set the "LIBGUESTFS_MEMSIZE"
673               environment variable or call "$g->set_memsize".
674
675           "AUG_NO_STDINC" = 8
676               Do not use standard load path for modules.
677
678           "AUG_SAVE_NOOP" = 16
679               Make save a no-op, just record what would have been changed.
680
681           "AUG_NO_LOAD" = 32
682               Do not load the tree in "$g->aug_init".
683
684           To close the handle, you can call "$g->aug_close".
685
686           To find out more about Augeas, see <http://augeas.net/>.
687
688       $g->aug_insert ($augpath, $label, $before);
689           Create a new sibling "label" for "path", inserting it into the tree
690           before or after "path" (depending on the boolean flag "before").
691
692           "path" must match exactly one existing node in the tree, and
693           "label" must be a label, ie. not contain /, "*" or end with a
694           bracketed index "[N]".
695
696       $label = $g->aug_label ($augpath);
697           The label (name of the last element) of the Augeas path expression
698           "augpath" is returned.  "augpath" must match exactly one node, else
699           this function returns an error.
700
701       $g->aug_load ();
702           Load files into the tree.
703
704           See "aug_load" in the Augeas documentation for the full gory
705           details.
706
707       @matches = $g->aug_ls ($augpath);
708           This is just a shortcut for listing "$g->aug_match" "path/*" and
709           sorting the resulting nodes into alphabetical order.
710
711       @matches = $g->aug_match ($augpath);
712           Returns a list of paths which match the path expression "path".
713           The returned paths are sufficiently qualified so that they match
714           exactly one node in the current tree.
715
716       $g->aug_mv ($src, $dest);
717           Move the node "src" to "dest".  "src" must match exactly one node.
718           "dest" is overwritten if it exists.
719
720       $nrnodes = $g->aug_rm ($augpath);
721           Remove "path" and all of its children.
722
723           On success this returns the number of entries which were removed.
724
725       $g->aug_save ();
726           This writes all pending changes to disk.
727
728           The flags which were passed to "$g->aug_init" affect exactly how
729           files are saved.
730
731       $g->aug_set ($augpath, $val);
732           Set the value associated with "augpath" to "val".
733
734           In the Augeas API, it is possible to clear a node by setting the
735           value to NULL.  Due to an oversight in the libguestfs API you
736           cannot do that with this call.  Instead you must use the
737           "$g->aug_clear" call.
738
739       $nodes = $g->aug_setm ($base, $sub, $val);
740           Change multiple Augeas nodes in a single operation.  "base" is an
741           expression matching multiple nodes.  "sub" is a path expression
742           relative to "base".  All nodes matching "base" are found, and then
743           for each node, "sub" is changed to "val".  "sub" may also be "NULL"
744           in which case the "base" nodes are modified.
745
746           This returns the number of nodes modified.
747
748       $g->aug_transform ($lens, $file [, remove => $remove]);
749           Add an Augeas transformation for the specified "lens" so it can
750           handle "file".
751
752           If "remove" is true ("false" by default), then the transformation
753           is removed.
754
755       $g->available (\@groups);
756           This command is used to check the availability of some groups of
757           functionality in the appliance, which not all builds of the
758           libguestfs appliance will be able to provide.
759
760           The libguestfs groups, and the functions that those groups
761           correspond to, are listed in "AVAILABILITY" in guestfs(3).  You can
762           also fetch this list at runtime by calling
763           "$g->available_all_groups".
764
765           The argument "groups" is a list of group names, eg: "["inotify",
766           "augeas"]" would check for the availability of the Linux inotify
767           functions and Augeas (configuration file editing) functions.
768
769           The command returns no error if all requested groups are available.
770
771           It fails with an error if one or more of the requested groups is
772           unavailable in the appliance.
773
774           If an unknown group name is included in the list of groups then an
775           error is always returned.
776
777           Notes:
778
779           •   "$g->feature_available" is the same as this call, but with a
780               slightly simpler to use API: that call returns a boolean
781               true/false instead of throwing an error.
782
783           •   You must call "$g->launch" before calling this function.
784
785               The reason is because we don't know what groups are supported
786               by the appliance/daemon until it is running and can be queried.
787
788           •   If a group of functions is available, this does not necessarily
789               mean that they will work.  You still have to check for errors
790               when calling individual API functions even if they are
791               available.
792
793           •   It is usually the job of distro packagers to build complete
794               functionality into the libguestfs appliance.  Upstream
795               libguestfs, if built from source with all requirements
796               satisfied, will support everything.
797
798           •   This call was added in version 1.0.80.  In previous versions of
799               libguestfs all you could do would be to speculatively execute a
800               command to find out if the daemon implemented it.  See also
801               "$g->version".
802
803           See also "$g->filesystem_available".
804
805       @groups = $g->available_all_groups ();
806           This command returns a list of all optional groups that this daemon
807           knows about.  Note this returns both supported and unsupported
808           groups.  To find out which ones the daemon can actually support you
809           have to call "$g->available" / "$g->feature_available" on each
810           member of the returned list.
811
812           See also "$g->available", "$g->feature_available" and
813           "AVAILABILITY" in guestfs(3).
814
815       $g->base64_in ($base64file, $filename);
816           This command uploads base64-encoded data from "base64file" to
817           filename.
818
819       $g->base64_out ($filename, $base64file);
820           This command downloads the contents of filename, writing it out to
821           local file "base64file" encoded as base64.
822
823       $g->blkdiscard ($device);
824           This discards all blocks on the block device "device", giving the
825           free space back to the host.
826
827           This operation requires support in libguestfs, the host filesystem,
828           qemu and the host kernel.  If this support isn't present it may
829           give an error or even appear to run but do nothing.  You must also
830           set the "discard" attribute on the underlying drive (see
831           "$g->add_drive_opts").
832
833           This function depends on the feature "blkdiscard".  See also
834           "$g->feature-available".
835
836       $zeroes = $g->blkdiscardzeroes ($device);
837           This call returns true if blocks on "device" that have been
838           discarded by a call to "$g->blkdiscard" are returned as blocks of
839           zero bytes when read the next time.
840
841           If it returns false, then it may be that discarded blocks are read
842           as stale or random data.
843
844           This function depends on the feature "blkdiscardzeroes".  See also
845           "$g->feature-available".
846
847       %info = $g->blkid ($device);
848           This command returns block device attributes for "device". The
849           following fields are usually present in the returned hash. Other
850           fields may also be present.
851
852           "UUID"
853               The uuid of this device.
854
855           "LABEL"
856               The label of this device.
857
858           "VERSION"
859               The version of blkid command.
860
861           "TYPE"
862               The filesystem type or RAID of this device.
863
864           "USAGE"
865               The usage of this device, for example "filesystem" or "raid".
866
867       $g->blockdev_flushbufs ($device);
868           This tells the kernel to flush internal buffers associated with
869           "device".
870
871           This uses the blockdev(8) command.
872
873       $blocksize = $g->blockdev_getbsz ($device);
874           This returns the block size of a device.
875
876           Note: this is different from both size in blocks and filesystem
877           block size.  Also this setting is not really used by anything.  You
878           should probably not use it for anything.  Filesystems have their
879           own idea about what block size to choose.
880
881           This uses the blockdev(8) command.
882
883       $ro = $g->blockdev_getro ($device);
884           Returns a boolean indicating if the block device is read-only (true
885           if read-only, false if not).
886
887           This uses the blockdev(8) command.
888
889       $sizeinbytes = $g->blockdev_getsize64 ($device);
890           This returns the size of the device in bytes.
891
892           See also "$g->blockdev_getsz".
893
894           This uses the blockdev(8) command.
895
896       $sectorsize = $g->blockdev_getss ($device);
897           This returns the size of sectors on a block device.  Usually 512,
898           but can be larger for modern devices.
899
900           (Note, this is not the size in sectors, use "$g->blockdev_getsz"
901           for that).
902
903           This uses the blockdev(8) command.
904
905       $sizeinsectors = $g->blockdev_getsz ($device);
906           This returns the size of the device in units of 512-byte sectors
907           (even if the sectorsize isn't 512 bytes ... weird).
908
909           See also "$g->blockdev_getss" for the real sector size of the
910           device, and "$g->blockdev_getsize64" for the more useful size in
911           bytes.
912
913           This uses the blockdev(8) command.
914
915       $g->blockdev_rereadpt ($device);
916           Reread the partition table on "device".
917
918           This uses the blockdev(8) command.
919
920       $g->blockdev_setbsz ($device, $blocksize);
921           This call does nothing and has never done anything because of a bug
922           in blockdev.  Do not use it.
923
924           If you need to set the filesystem block size, use the "blocksize"
925           option of "$g->mkfs".
926
927           This function is deprecated.  There is no replacement.  Consult the
928           API documentation in guestfs(3) for further information.
929
930           Deprecated functions will not be removed from the API, but the fact
931           that they are deprecated indicates that there are problems with
932           correct use of these functions.
933
934       $g->blockdev_setra ($device, $sectors);
935           Set readahead (in 512-byte sectors) for the device.
936
937           This uses the blockdev(8) command.
938
939       $g->blockdev_setro ($device);
940           Sets the block device named "device" to read-only.
941
942           This uses the blockdev(8) command.
943
944       $g->blockdev_setrw ($device);
945           Sets the block device named "device" to read-write.
946
947           This uses the blockdev(8) command.
948
949       $g->btrfs_balance_cancel ($path);
950           Cancel a running balance on a btrfs filesystem.
951
952           This function depends on the feature "btrfs".  See also
953           "$g->feature-available".
954
955       $g->btrfs_balance_pause ($path);
956           Pause a running balance on a btrfs filesystem.
957
958           This function depends on the feature "btrfs".  See also
959           "$g->feature-available".
960
961       $g->btrfs_balance_resume ($path);
962           Resume a paused balance on a btrfs filesystem.
963
964           This function depends on the feature "btrfs".  See also
965           "$g->feature-available".
966
967       %status = $g->btrfs_balance_status ($path);
968           Show the status of a running or paused balance on a btrfs
969           filesystem.
970
971           This function depends on the feature "btrfs".  See also
972           "$g->feature-available".
973
974       $g->btrfs_device_add (\@devices, $fs);
975           Add the list of device(s) in "devices" to the btrfs filesystem
976           mounted at "fs".  If "devices" is an empty list, this does nothing.
977
978           This function depends on the feature "btrfs".  See also
979           "$g->feature-available".
980
981       $g->btrfs_device_delete (\@devices, $fs);
982           Remove the "devices" from the btrfs filesystem mounted at "fs".  If
983           "devices" is an empty list, this does nothing.
984
985           This function depends on the feature "btrfs".  See also
986           "$g->feature-available".
987
988       $g->btrfs_filesystem_balance ($fs);
989           Balance the chunks in the btrfs filesystem mounted at "fs" across
990           the underlying devices.
991
992           This function depends on the feature "btrfs".  See also
993           "$g->feature-available".
994
995       $g->btrfs_filesystem_defragment ($path [, flush => $flush] [, compress
996       => $compress]);
997           Defragment a file or directory on a btrfs filesystem. compress is
998           one of zlib or lzo.
999
1000           This function depends on the feature "btrfs".  See also
1001           "$g->feature-available".
1002
1003       $g->btrfs_filesystem_resize ($mountpoint [, size => $size]);
1004           This command resizes a btrfs filesystem.
1005
1006           Note that unlike other resize calls, the filesystem has to be
1007           mounted and the parameter is the mountpoint not the device (this is
1008           a requirement of btrfs itself).
1009
1010           The optional parameters are:
1011
1012           "size"
1013               The new size (in bytes) of the filesystem.  If omitted, the
1014               filesystem is resized to the maximum size.
1015
1016           See also btrfs(8).
1017
1018           This function depends on the feature "btrfs".  See also
1019           "$g->feature-available".
1020
1021       @devices = $g->btrfs_filesystem_show ($device);
1022           Show all the devices where the filesystems in "device" is spanned
1023           over.
1024
1025           If not all the devices for the filesystems are present, then this
1026           function fails and the "errno" is set to "ENODEV".
1027
1028           This function depends on the feature "btrfs".  See also
1029           "$g->feature-available".
1030
1031       $g->btrfs_filesystem_sync ($fs);
1032           Force sync on the btrfs filesystem mounted at "fs".
1033
1034           This function depends on the feature "btrfs".  See also
1035           "$g->feature-available".
1036
1037       $g->btrfs_fsck ($device [, superblock => $superblock] [, repair =>
1038       $repair]);
1039           Used to check a btrfs filesystem, "device" is the device file where
1040           the filesystem is stored.
1041
1042           This function depends on the feature "btrfs".  See also
1043           "$g->feature-available".
1044
1045       $g->btrfs_image (\@source, $image [, compresslevel => $compresslevel]);
1046           This is used to create an image of a btrfs filesystem.  All data
1047           will be zeroed, but metadata and the like is preserved.
1048
1049           This function depends on the feature "btrfs".  See also
1050           "$g->feature-available".
1051
1052       $g->btrfs_qgroup_assign ($src, $dst, $path);
1053           Add qgroup "src" to parent qgroup "dst". This command can group
1054           several qgroups into a parent qgroup to share common limit.
1055
1056           This function depends on the feature "btrfs".  See also
1057           "$g->feature-available".
1058
1059       $g->btrfs_qgroup_create ($qgroupid, $subvolume);
1060           Create a quota group (qgroup) for subvolume at "subvolume".
1061
1062           This function depends on the feature "btrfs".  See also
1063           "$g->feature-available".
1064
1065       $g->btrfs_qgroup_destroy ($qgroupid, $subvolume);
1066           Destroy a quota group.
1067
1068           This function depends on the feature "btrfs".  See also
1069           "$g->feature-available".
1070
1071       $g->btrfs_qgroup_limit ($subvolume, $size);
1072           Limit the size of the subvolume with path "subvolume".
1073
1074           This function depends on the feature "btrfs".  See also
1075           "$g->feature-available".
1076
1077       $g->btrfs_qgroup_remove ($src, $dst, $path);
1078           Remove qgroup "src" from the parent qgroup "dst".
1079
1080           This function depends on the feature "btrfs".  See also
1081           "$g->feature-available".
1082
1083       @qgroups = $g->btrfs_qgroup_show ($path);
1084           Show all subvolume quota groups in a btrfs filesystem, including
1085           their usages.
1086
1087           This function depends on the feature "btrfs".  See also
1088           "$g->feature-available".
1089
1090       $g->btrfs_quota_enable ($fs, $enable);
1091           Enable or disable subvolume quota support for filesystem which
1092           contains "path".
1093
1094           This function depends on the feature "btrfs".  See also
1095           "$g->feature-available".
1096
1097       $g->btrfs_quota_rescan ($fs);
1098           Trash all qgroup numbers and scan the metadata again with the
1099           current config.
1100
1101           This function depends on the feature "btrfs".  See also
1102           "$g->feature-available".
1103
1104       $g->btrfs_replace ($srcdev, $targetdev, $mntpoint);
1105           Replace device of a btrfs filesystem. On a live filesystem,
1106           duplicate the data to the target device which is currently stored
1107           on the source device.  After completion of the operation, the
1108           source device is wiped out and removed from the filesystem.
1109
1110           The "targetdev" needs to be same size or larger than the "srcdev".
1111           Devices which are currently mounted are never allowed to be used as
1112           the "targetdev".
1113
1114           This function depends on the feature "btrfs".  See also
1115           "$g->feature-available".
1116
1117       $g->btrfs_rescue_chunk_recover ($device);
1118           Recover the chunk tree of btrfs filesystem by scanning the devices
1119           one by one.
1120
1121           This function depends on the feature "btrfs".  See also
1122           "$g->feature-available".
1123
1124       $g->btrfs_rescue_super_recover ($device);
1125           Recover bad superblocks from good copies.
1126
1127           This function depends on the feature "btrfs".  See also
1128           "$g->feature-available".
1129
1130       $g->btrfs_scrub_cancel ($path);
1131           Cancel a running scrub on a btrfs filesystem.
1132
1133           This function depends on the feature "btrfs".  See also
1134           "$g->feature-available".
1135
1136       $g->btrfs_scrub_resume ($path);
1137           Resume a previously canceled or interrupted scrub on a btrfs
1138           filesystem.
1139
1140           This function depends on the feature "btrfs".  See also
1141           "$g->feature-available".
1142
1143       $g->btrfs_scrub_start ($path);
1144           Reads all the data and metadata on the filesystem, and uses
1145           checksums and the duplicate copies from RAID storage to identify
1146           and repair any corrupt data.
1147
1148           This function depends on the feature "btrfs".  See also
1149           "$g->feature-available".
1150
1151       %status = $g->btrfs_scrub_status ($path);
1152           Show status of running or finished scrub on a btrfs filesystem.
1153
1154           This function depends on the feature "btrfs".  See also
1155           "$g->feature-available".
1156
1157       $g->btrfs_set_seeding ($device, $seeding);
1158           Enable or disable the seeding feature of a device that contains a
1159           btrfs filesystem.
1160
1161           This function depends on the feature "btrfs".  See also
1162           "$g->feature-available".
1163
1164       $g->btrfs_subvolume_create ($dest [, qgroupid => $qgroupid]);
1165           Create a btrfs subvolume.  The "dest" argument is the destination
1166           directory and the name of the subvolume, in the form
1167           /path/to/dest/name.  The optional parameter "qgroupid" represents
1168           the qgroup which the newly created subvolume will be added to.
1169
1170           This function depends on the feature "btrfs".  See also
1171           "$g->feature-available".
1172
1173       $g->btrfs_subvolume_create_opts ($dest [, qgroupid => $qgroupid]);
1174           This is an alias of "btrfs_subvolume_create".
1175
1176       $g->btrfs_subvolume_delete ($subvolume);
1177           Delete the named btrfs subvolume or snapshot.
1178
1179           This function depends on the feature "btrfs".  See also
1180           "$g->feature-available".
1181
1182       $id = $g->btrfs_subvolume_get_default ($fs);
1183           Get the default subvolume or snapshot of a filesystem mounted at
1184           "mountpoint".
1185
1186           This function depends on the feature "btrfs".  See also
1187           "$g->feature-available".
1188
1189       @subvolumes = $g->btrfs_subvolume_list ($fs);
1190           List the btrfs snapshots and subvolumes of the btrfs filesystem
1191           which is mounted at "fs".
1192
1193           This function depends on the feature "btrfs".  See also
1194           "$g->feature-available".
1195
1196       $g->btrfs_subvolume_set_default ($id, $fs);
1197           Set the subvolume of the btrfs filesystem "fs" which will be
1198           mounted by default.  See "$g->btrfs_subvolume_list" to get a list
1199           of subvolumes.
1200
1201           This function depends on the feature "btrfs".  See also
1202           "$g->feature-available".
1203
1204       %btrfssubvolumeinfo = $g->btrfs_subvolume_show ($subvolume);
1205           Return detailed information of the subvolume.
1206
1207           This function depends on the feature "btrfs".  See also
1208           "$g->feature-available".
1209
1210       $g->btrfs_subvolume_snapshot ($source, $dest [, ro => $ro] [, qgroupid
1211       => $qgroupid]);
1212           Create a snapshot of the btrfs subvolume "source".  The "dest"
1213           argument is the destination directory and the name of the snapshot,
1214           in the form /path/to/dest/name. By default the newly created
1215           snapshot is writable, if the value of optional parameter "ro" is
1216           true, then a readonly snapshot is created. The optional parameter
1217           "qgroupid" represents the qgroup which the newly created snapshot
1218           will be added to.
1219
1220           This function depends on the feature "btrfs".  See also
1221           "$g->feature-available".
1222
1223       $g->btrfs_subvolume_snapshot_opts ($source, $dest [, ro => $ro] [,
1224       qgroupid => $qgroupid]);
1225           This is an alias of "btrfs_subvolume_snapshot".
1226
1227       $g->btrfstune_enable_extended_inode_refs ($device);
1228           This will Enable extended inode refs.
1229
1230           This function depends on the feature "btrfs".  See also
1231           "$g->feature-available".
1232
1233       $g->btrfstune_enable_skinny_metadata_extent_refs ($device);
1234           This enable skinny metadata extent refs.
1235
1236           This function depends on the feature "btrfs".  See also
1237           "$g->feature-available".
1238
1239       $g->btrfstune_seeding ($device, $seeding);
1240           Enable seeding of a btrfs device, this will force a fs readonly so
1241           that you can use it to build other filesystems.
1242
1243           This function depends on the feature "btrfs".  See also
1244           "$g->feature-available".
1245
1246       $ptr = $g->c_pointer ();
1247           In non-C language bindings, this allows you to retrieve the
1248           underlying C pointer to the handle (ie. "$g->h *").  The purpose of
1249           this is to allow other libraries to interwork with libguestfs.
1250
1251       $canonical = $g->canonical_device_name ($device);
1252           This utility function is useful when displaying device names to the
1253           user.  It takes a number of irregular device names and returns them
1254           in a consistent format:
1255
1256           /dev/hdX
1257           /dev/vdX
1258               These are returned as /dev/sdX.  Note this works for device
1259               names and partition names.  This is approximately the reverse
1260               of the algorithm described in "BLOCK DEVICE NAMING" in
1261               guestfs(3).
1262
1263           /dev/mapper/VG-LV
1264           /dev/dm-N
1265               Converted to /dev/VG/LV form using "$g->lvm_canonical_lv_name".
1266
1267           Other strings are returned unmodified.
1268
1269       $cap = $g->cap_get_file ($path);
1270           This function returns the Linux capabilities attached to "path".
1271           The capabilities set is returned in text form (see cap_to_text(3)).
1272
1273           If no capabilities are attached to a file, an empty string is
1274           returned.
1275
1276           This function depends on the feature "linuxcaps".  See also
1277           "$g->feature-available".
1278
1279       $g->cap_set_file ($path, $cap);
1280           This function sets the Linux capabilities attached to "path".  The
1281           capabilities set "cap" should be passed in text form (see
1282           cap_from_text(3)).
1283
1284           This function depends on the feature "linuxcaps".  See also
1285           "$g->feature-available".
1286
1287       $rpath = $g->case_sensitive_path ($path);
1288           This can be used to resolve case insensitive paths on a filesystem
1289           which is case sensitive.  The use case is to resolve paths which
1290           you have read from Windows configuration files or the Windows
1291           Registry, to the true path.
1292
1293           The command handles a peculiarity of the Linux ntfs-3g filesystem
1294           driver (and probably others), which is that although the underlying
1295           filesystem is case-insensitive, the driver exports the filesystem
1296           to Linux as case-sensitive.
1297
1298           One consequence of this is that special directories such as
1299           C:\windows may appear as /WINDOWS or /windows (or other things)
1300           depending on the precise details of how they were created.  In
1301           Windows itself this would not be a problem.
1302
1303           Bug or feature?  You decide:
1304           <https://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1>
1305
1306           "$g->case_sensitive_path" attempts to resolve the true case of each
1307           element in the path. It will return a resolved path if either the
1308           full path or its parent directory exists. If the parent directory
1309           exists but the full path does not, the case of the parent directory
1310           will be correctly resolved, and the remainder appended unmodified.
1311           For example, if the file "/Windows/System32/netkvm.sys" exists:
1312
1313           "$g->case_sensitive_path" ("/windows/system32/netkvm.sys")
1314               "Windows/System32/netkvm.sys"
1315
1316           "$g->case_sensitive_path" ("/windows/system32/NoSuchFile")
1317               "Windows/System32/NoSuchFile"
1318
1319           "$g->case_sensitive_path" ("/windows/system33/netkvm.sys")
1320               ERROR
1321
1322           Note: Because of the above behaviour, "$g->case_sensitive_path"
1323           cannot be used to check for the existence of a file.
1324
1325           Note: This function does not handle drive names, backslashes etc.
1326
1327           See also "$g->realpath".
1328
1329       $content = $g->cat ($path);
1330           Return the contents of the file named "path".
1331
1332           Because, in C, this function returns a "char *", there is no way to
1333           differentiate between a "\0" character in a file and end of string.
1334           To handle binary files, use the "$g->read_file" or "$g->download"
1335           functions.
1336
1337       $checksum = $g->checksum ($csumtype, $path);
1338           This call computes the MD5, SHAx or CRC checksum of the file named
1339           "path".
1340
1341           The type of checksum to compute is given by the "csumtype"
1342           parameter which must have one of the following values:
1343
1344           "crc"
1345               Compute the cyclic redundancy check (CRC) specified by POSIX
1346               for the "cksum" command.
1347
1348           "md5"
1349               Compute the MD5 hash (using the md5sum(1) program).
1350
1351           "sha1"
1352               Compute the SHA1 hash (using the sha1sum(1) program).
1353
1354           "sha224"
1355               Compute the SHA224 hash (using the sha224sum(1) program).
1356
1357           "sha256"
1358               Compute the SHA256 hash (using the sha256sum(1) program).
1359
1360           "sha384"
1361               Compute the SHA384 hash (using the sha384sum(1) program).
1362
1363           "sha512"
1364               Compute the SHA512 hash (using the sha512sum(1) program).
1365
1366           The checksum is returned as a printable string.
1367
1368           To get the checksum for a device, use "$g->checksum_device".
1369
1370           To get the checksums for many files, use "$g->checksums_out".
1371
1372       $checksum = $g->checksum_device ($csumtype, $device);
1373           This call computes the MD5, SHAx or CRC checksum of the contents of
1374           the device named "device".  For the types of checksums supported
1375           see the "$g->checksum" command.
1376
1377       $g->checksums_out ($csumtype, $directory, $sumsfile);
1378           This command computes the checksums of all regular files in
1379           directory and then emits a list of those checksums to the local
1380           output file "sumsfile".
1381
1382           This can be used for verifying the integrity of a virtual machine.
1383           However to be properly secure you should pay attention to the
1384           output of the checksum command (it uses the ones from GNU
1385           coreutils).  In particular when the filename is not printable,
1386           coreutils uses a special backslash syntax.  For more information,
1387           see the GNU coreutils info file.
1388
1389       $g->chmod ($mode, $path);
1390           Change the mode (permissions) of "path" to "mode".  Only numeric
1391           modes are supported.
1392
1393           Note: When using this command from guestfish, "mode" by default
1394           would be decimal, unless you prefix it with 0 to get octal, ie. use
1395           0700 not 700.
1396
1397           The mode actually set is affected by the umask.
1398
1399       $g->chown ($owner, $group, $path);
1400           Change the file owner to "owner" and group to "group".
1401
1402           Only numeric uid and gid are supported.  If you want to use names,
1403           you will need to locate and parse the password file yourself
1404           (Augeas support makes this relatively easy).
1405
1406       $count = $g->clear_backend_setting ($name);
1407           If there is a backend setting string matching "name" or beginning
1408           with "name=", then that string is removed from the backend
1409           settings.
1410
1411           This call returns the number of strings which were removed (which
1412           may be 0, 1 or greater than 1).
1413
1414           See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
1415
1416       $g->clevis_luks_unlock ($device, $mapname);
1417           This command opens a block device that has been encrypted according
1418           to the Linux Unified Key Setup (LUKS) standard, using network-bound
1419           disk encryption (NBDE).
1420
1421           "device" is the encrypted block device.
1422
1423           The appliance will connect to the Tang servers noted in the tree of
1424           Clevis pins that is bound to a keyslot of the LUKS header.  The
1425           Clevis pin tree may comprise "sss" (redudancy) pins as internal
1426           nodes (optionally), and "tang" pins as leaves.  "tpm2" pins are not
1427           supported.  The appliance unlocks the encrypted block device by
1428           combining responses from the Tang servers with metadata from the
1429           LUKS header; there is no "key" parameter.
1430
1431           This command will fail if networking has not been enabled for the
1432           appliance. Refer to "$g->set_network".
1433
1434           The command creates a new block device called /dev/mapper/mapname.
1435           Reads and writes to this block device are decrypted from and
1436           encrypted to the underlying "device" respectively.  Close the
1437           decrypted block device with "$g->cryptsetup_close".
1438
1439           "mapname" cannot be "control" because that name is reserved by
1440           device-mapper.
1441
1442           If this block device contains LVM volume groups, then calling
1443           "$g->lvm_scan" with the "activate" parameter "true" will make them
1444           visible.
1445
1446           Use "$g->list_dm_devices" to list all device mapper devices.
1447
1448           This function depends on the feature "clevisluks".  See also
1449           "$g->feature-available".
1450
1451       $output = $g->command (\@arguments);
1452           This call runs a command from the guest filesystem.  The filesystem
1453           must be mounted, and must contain a compatible operating system
1454           (ie. something Linux, with the same or compatible processor
1455           architecture).
1456
1457           The single parameter is an argv-style list of arguments.  The first
1458           element is the name of the program to run.  Subsequent elements are
1459           parameters.  The list must be non-empty (ie. must contain a program
1460           name).  Note that the command runs directly, and is not invoked via
1461           the shell (see "$g->sh").
1462
1463           The return value is anything printed to stdout by the command.
1464
1465           If the command returns a non-zero exit status, then this function
1466           returns an error message.  The error message string is the content
1467           of stderr from the command.
1468
1469           The $PATH environment variable will contain at least /usr/bin and
1470           /bin.  If you require a program from another location, you should
1471           provide the full path in the first parameter.
1472
1473           Shared libraries and data files required by the program must be
1474           available on filesystems which are mounted in the correct places.
1475           It is the caller’s responsibility to ensure all filesystems that
1476           are needed are mounted at the right locations.
1477
1478           Because of the message protocol, there is a transfer limit of
1479           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
1480           guestfs(3).
1481
1482       @lines = $g->command_lines (\@arguments);
1483           This is the same as "$g->command", but splits the result into a
1484           list of lines.
1485
1486           See also: "$g->sh_lines"
1487
1488           Because of the message protocol, there is a transfer limit of
1489           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
1490           guestfs(3).
1491
1492       $g->compress_device_out ($ctype, $device, $zdevice [, level =>
1493       $level]);
1494           This command compresses "device" and writes it out to the local
1495           file "zdevice".
1496
1497           The "ctype" and optional "level" parameters have the same meaning
1498           as in "$g->compress_out".
1499
1500       $g->compress_out ($ctype, $file, $zfile [, level => $level]);
1501           This command compresses file and writes it out to the local file
1502           zfile.
1503
1504           The compression program used is controlled by the "ctype"
1505           parameter.  Currently this includes: "compress", "gzip", "bzip2",
1506           "xz" or "lzop".  Some compression types may not be supported by
1507           particular builds of libguestfs, in which case you will get an
1508           error containing the substring "not supported".
1509
1510           The optional "level" parameter controls compression level.  The
1511           meaning and default for this parameter depends on the compression
1512           program being used.
1513
1514       $g->config ($hvparam, $hvvalue);
1515           This can be used to add arbitrary hypervisor parameters of the form
1516           -param value.  Actually it’s not quite arbitrary - we prevent you
1517           from setting some parameters which would interfere with parameters
1518           that we use.
1519
1520           The first character of "hvparam" string must be a "-" (dash).
1521
1522           "hvvalue" can be NULL.
1523
1524       $g->copy_attributes ($src, $dest [, all => $all] [, mode => $mode] [,
1525       xattributes => $xattributes] [, ownership => $ownership]);
1526           Copy the attributes of a path (which can be a file or a directory)
1527           to another path.
1528
1529           By default no attribute is copied, so make sure to specify any (or
1530           "all" to copy everything).
1531
1532           The optional arguments specify which attributes can be copied:
1533
1534           "mode"
1535               Copy part of the file mode from "source" to "destination". Only
1536               the UNIX permissions and the sticky/setuid/setgid bits can be
1537               copied.
1538
1539           "xattributes"
1540               Copy the Linux extended attributes (xattrs) from "source" to
1541               "destination".  This flag does nothing if the linuxxattrs
1542               feature is not available (see "$g->feature_available").
1543
1544           "ownership"
1545               Copy the owner uid and the group gid of "source" to
1546               "destination".
1547
1548           "all"
1549               Copy all the attributes from "source" to "destination".
1550               Enabling it enables all the other flags, if they are not
1551               specified already.
1552
1553       $g->copy_device_to_device ($src, $dest [, srcoffset => $srcoffset] [,
1554       destoffset => $destoffset] [, size => $size] [, sparse => $sparse] [,
1555       append => $append]);
1556           The four calls "$g->copy_device_to_device",
1557           "$g->copy_device_to_file", "$g->copy_file_to_device", and
1558           "$g->copy_file_to_file" let you copy from a source (device|file) to
1559           a destination (device|file).
1560
1561           Partial copies can be made since you can specify optionally the
1562           source offset, destination offset and size to copy.  These values
1563           are all specified in bytes.  If not given, the offsets both default
1564           to zero, and the size defaults to copying as much as possible until
1565           we hit the end of the source.
1566
1567           The source and destination may be the same object.  However
1568           overlapping regions may not be copied correctly.
1569
1570           If the destination is a file, it is created if required.  If the
1571           destination file is not large enough, it is extended.
1572
1573           If the destination is a file and the "append" flag is not set, then
1574           the destination file is truncated.  If the "append" flag is set,
1575           then the copy appends to the destination file.  The "append" flag
1576           currently cannot be set for devices.
1577
1578           If the "sparse" flag is true then the call avoids writing blocks
1579           that contain only zeroes, which can help in some situations where
1580           the backing disk is thin-provisioned.  Note that unless the target
1581           is already zeroed, using this option will result in incorrect
1582           copying.
1583
1584       $g->copy_device_to_file ($src, $dest [, srcoffset => $srcoffset] [,
1585       destoffset => $destoffset] [, size => $size] [, sparse => $sparse] [,
1586       append => $append]);
1587           See "$g->copy_device_to_device" for a general overview of this
1588           call.
1589
1590       $g->copy_file_to_device ($src, $dest [, srcoffset => $srcoffset] [,
1591       destoffset => $destoffset] [, size => $size] [, sparse => $sparse] [,
1592       append => $append]);
1593           See "$g->copy_device_to_device" for a general overview of this
1594           call.
1595
1596       $g->copy_file_to_file ($src, $dest [, srcoffset => $srcoffset] [,
1597       destoffset => $destoffset] [, size => $size] [, sparse => $sparse] [,
1598       append => $append]);
1599           See "$g->copy_device_to_device" for a general overview of this
1600           call.
1601
1602           This is not the function you want for copying files.  This is for
1603           copying blocks within existing files.  See "$g->cp", "$g->cp_a" and
1604           "$g->mv" for general file copying and moving functions.
1605
1606       $g->copy_in ($localpath, $remotedir);
1607           "$g->copy_in" copies local files or directories recursively into
1608           the disk image, placing them in the directory called "remotedir"
1609           (which must exist).
1610
1611           Wildcards cannot be used.
1612
1613       $g->copy_out ($remotepath, $localdir);
1614           "$g->copy_out" copies remote files or directories recursively out
1615           of the disk image, placing them on the host disk in a local
1616           directory called "localdir" (which must exist).
1617
1618           To download to the current directory, use "." as in:
1619
1620            C<$g-E<gt>copy_out> /home .
1621
1622           Wildcards cannot be used.
1623
1624       $g->copy_size ($src, $dest, $size);
1625           This command copies exactly "size" bytes from one source device or
1626           file "src" to another destination device or file "dest".
1627
1628           Note this will fail if the source is too short or if the
1629           destination is not large enough.
1630
1631           This function is deprecated.  In new code, use the
1632           "copy_device_to_device" call instead.
1633
1634           Deprecated functions will not be removed from the API, but the fact
1635           that they are deprecated indicates that there are problems with
1636           correct use of these functions.
1637
1638       $g->cp ($src, $dest);
1639           This copies a file from "src" to "dest" where "dest" is either a
1640           destination filename or destination directory.
1641
1642       $g->cp_a ($src, $dest);
1643           This copies a file or directory from "src" to "dest" recursively
1644           using the "cp -a" command.
1645
1646       $g->cp_r ($src, $dest);
1647           This copies a file or directory from "src" to "dest" recursively
1648           using the "cp -rP" command.
1649
1650           Most users should use "$g->cp_a" instead.  This command is useful
1651           when you don't want to preserve permissions, because the target
1652           filesystem does not support it (primarily when writing to DOS FAT
1653           filesystems).
1654
1655       $g->cpio_out ($directory, $cpiofile [, format => $format]);
1656           This command packs the contents of directory and downloads it to
1657           local file "cpiofile".
1658
1659           The optional "format" parameter can be used to select the format.
1660           Only the following formats are currently permitted:
1661
1662           "newc"
1663               New (SVR4) portable format.  This format happens to be
1664               compatible with the cpio-like format used by the Linux kernel
1665               for initramfs.
1666
1667               This is the default format.
1668
1669           "crc"
1670               New (SVR4) portable format with a checksum.
1671
1672       $g->cryptsetup_close ($device);
1673           This closes an encrypted device that was created earlier by
1674           "$g->cryptsetup_open".  The "device" parameter must be the name of
1675           the mapping device (ie. /dev/mapper/mapname) and not the name of
1676           the underlying block device.
1677
1678           This function depends on the feature "luks".  See also
1679           "$g->feature-available".
1680
1681       $g->cryptsetup_open ($device, $key, $mapname [, readonly => $readonly]
1682       [, crypttype => $crypttype]);
1683           This command opens a block device which has been encrypted
1684           according to the Linux Unified Key Setup (LUKS) standard, Windows
1685           BitLocker, or some other types.
1686
1687           "device" is the encrypted block device or partition.
1688
1689           The caller must supply one of the keys associated with the
1690           encrypted block device, in the "key" parameter.
1691
1692           This creates a new block device called /dev/mapper/mapname.  Reads
1693           and writes to this block device are decrypted from and encrypted to
1694           the underlying "device" respectively.
1695
1696           "mapname" cannot be "control" because that name is reserved by
1697           device-mapper.
1698
1699           If the optional "crypttype" parameter is not present then
1700           libguestfs tries to guess the correct type (for example LUKS or
1701           BitLocker).  However you can override this by specifying one of the
1702           following types:
1703
1704           "luks"
1705               A Linux LUKS device.
1706
1707           "bitlk"
1708               A Windows BitLocker device.
1709
1710           The optional "readonly" flag, if set to true, creates a read-only
1711           mapping.
1712
1713           If this block device contains LVM volume groups, then calling
1714           "$g->lvm_scan" with the "activate" parameter "true" will make them
1715           visible.
1716
1717           Use "$g->list_dm_devices" to list all device mapper devices.
1718
1719           This function depends on the feature "luks".  See also
1720           "$g->feature-available".
1721
1722       $g->dd ($src, $dest);
1723           This command copies from one source device or file "src" to another
1724           destination device or file "dest".  Normally you would use this to
1725           copy to or from a device or partition, for example to duplicate a
1726           filesystem.
1727
1728           If the destination is a device, it must be as large or larger than
1729           the source file or device, otherwise the copy will fail.  This
1730           command cannot do partial copies (see "$g->copy_device_to_device").
1731
1732           This function is deprecated.  In new code, use the
1733           "copy_device_to_device" call instead.
1734
1735           Deprecated functions will not be removed from the API, but the fact
1736           that they are deprecated indicates that there are problems with
1737           correct use of these functions.
1738
1739       $index = $g->device_index ($device);
1740           This function takes a device name (eg. "/dev/sdb") and returns the
1741           index of the device in the list of devices.
1742
1743           Index numbers start from 0.  The named device must exist, for
1744           example as a string returned from "$g->list_devices".
1745
1746           See also "$g->list_devices", "$g->part_to_dev", "$g->device_name".
1747
1748       $name = $g->device_name ($index);
1749           This function takes a device index and returns the device name.
1750           For example index 0 will return the string "/dev/sda".
1751
1752           The drive index must have been added to the handle.
1753
1754           See also "$g->list_devices", "$g->part_to_dev", "$g->device_index".
1755
1756       $output = $g->df ();
1757           This command runs the df(1) command to report disk space used.
1758
1759           This command is mostly useful for interactive sessions.  It is not
1760           intended that you try to parse the output string.  Use
1761           "$g->statvfs" from programs.
1762
1763       $output = $g->df_h ();
1764           This command runs the "df -h" command to report disk space used in
1765           human-readable format.
1766
1767           This command is mostly useful for interactive sessions.  It is not
1768           intended that you try to parse the output string.  Use
1769           "$g->statvfs" from programs.
1770
1771       $g->disk_create ($filename, $format, $size [, backingfile =>
1772       $backingfile] [, backingformat => $backingformat] [, preallocation =>
1773       $preallocation] [, compat => $compat] [, clustersize => $clustersize]);
1774           Create a blank disk image called filename (a host file) with format
1775           "format" (usually "raw" or "qcow2").  The size is "size" bytes.
1776
1777           If used with the optional "backingfile" parameter, then a snapshot
1778           is created on top of the backing file.  In this case, "size" must
1779           be passed as -1.  The size of the snapshot is the same as the size
1780           of the backing file, which is discovered automatically.  You are
1781           encouraged to also pass "backingformat" to describe the format of
1782           "backingfile".
1783
1784           If filename refers to a block device, then the device is formatted.
1785           The "size" is ignored since block devices have an intrinsic size.
1786
1787           The other optional parameters are:
1788
1789           "preallocation"
1790               If format is "raw", then this can be either "off" (or "sparse")
1791               or "full" to create a sparse or fully allocated file
1792               respectively.  The default is "off".
1793
1794               If format is "qcow2", then this can be "off" (or "sparse"),
1795               "metadata" or "full".  Preallocating metadata can be faster
1796               when doing lots of writes, but uses more space.  The default is
1797               "off".
1798
1799           "compat"
1800               "qcow2" only: Pass the string 1.1 to use the advanced qcow2
1801               format supported by qemu ≥ 1.1.
1802
1803           "clustersize"
1804               "qcow2" only: Change the qcow2 cluster size.  The default is
1805               65536 (bytes) and this setting may be any power of two between
1806               512 and 2097152.
1807
1808           Note that this call does not add the new disk to the handle.  You
1809           may need to call "$g->add_drive_opts" separately.
1810
1811       $format = $g->disk_format ($filename);
1812           Detect and return the format of the disk image called filename.
1813           filename can also be a host device, etc.  If the format of the
1814           image could not be detected, then "unknown" is returned.
1815
1816           Note that detecting the disk format can be insecure under some
1817           circumstances.  See "CVE-2010-3851" in guestfs(3).
1818
1819           See also: "DISK IMAGE FORMATS" in guestfs(3)
1820
1821       $backingfile = $g->disk_has_backing_file ($filename);
1822           Detect and return whether the disk image filename has a backing
1823           file.
1824
1825           Note that detecting disk features can be insecure under some
1826           circumstances.  See "CVE-2010-3851" in guestfs(3).
1827
1828       $size = $g->disk_virtual_size ($filename);
1829           Detect and return the virtual size in bytes of the disk image
1830           called filename.
1831
1832           Note that detecting disk features can be insecure under some
1833           circumstances.  See "CVE-2010-3851" in guestfs(3).
1834
1835       $kmsgs = $g->dmesg ();
1836           This returns the kernel messages (dmesg(1) output) from the guest
1837           kernel.  This is sometimes useful for extended debugging of
1838           problems.
1839
1840           Another way to get the same information is to enable verbose
1841           messages with "$g->set_verbose" or by setting the environment
1842           variable "LIBGUESTFS_DEBUG=1" before running the program.
1843
1844       $g->download ($remotefilename, $filename);
1845           Download file remotefilename and save it as filename on the local
1846           machine.
1847
1848           filename can also be a named pipe.
1849
1850           See also "$g->upload", "$g->cat".
1851
1852       $g->download_blocks ($device, $start, $stop, $filename [, unallocated
1853       => $unallocated]);
1854           Download the data units from start address to stop from the disk
1855           partition (eg. /dev/sda1) and save them as filename on the local
1856           machine.
1857
1858           The use of this API on sparse disk image formats such as QCOW, may
1859           result in large zero-filled files downloaded on the host.
1860
1861           The size of a data unit varies across filesystem implementations.
1862           On NTFS filesystems data units are referred as clusters while on
1863           ExtX ones they are referred as fragments.
1864
1865           If the optional "unallocated" flag is true (default is false), only
1866           the unallocated blocks will be extracted.  This is useful to detect
1867           hidden data or to retrieve deleted files which data units have not
1868           been overwritten yet.
1869
1870           This function depends on the feature "sleuthkit".  See also
1871           "$g->feature-available".
1872
1873       $g->download_inode ($device, $inode, $filename);
1874           Download a file given its inode from the disk partition (eg.
1875           /dev/sda1) and save it as filename on the local machine.
1876
1877           It is not required to mount the disk to run this command.
1878
1879           The command is capable of downloading deleted or inaccessible
1880           files.
1881
1882           This function depends on the feature "sleuthkit".  See also
1883           "$g->feature-available".
1884
1885       $g->download_offset ($remotefilename, $filename, $offset, $size);
1886           Download file remotefilename and save it as filename on the local
1887           machine.
1888
1889           remotefilename is read for "size" bytes starting at "offset" (this
1890           region must be within the file or device).
1891
1892           Note that there is no limit on the amount of data that can be
1893           downloaded with this call, unlike with "$g->pread", and this call
1894           always reads the full amount unless an error occurs.
1895
1896           See also "$g->download", "$g->pread".
1897
1898       $g->drop_caches ($whattodrop);
1899           This instructs the guest kernel to drop its page cache, and/or
1900           dentries and inode caches.  The parameter "whattodrop" tells the
1901           kernel what precisely to drop, see
1902           <https://linux-mm.org/Drop_Caches>
1903
1904           Setting "whattodrop" to 3 should drop everything.
1905
1906           This automatically calls sync(2) before the operation, so that the
1907           maximum guest memory is freed.
1908
1909       $sizekb = $g->du ($path);
1910           This command runs the "du -s" command to estimate file space usage
1911           for "path".
1912
1913           "path" can be a file or a directory.  If "path" is a directory then
1914           the estimate includes the contents of the directory and all
1915           subdirectories (recursively).
1916
1917           The result is the estimated size in kilobytes (ie. units of 1024
1918           bytes).
1919
1920       $g->e2fsck ($device [, correct => $correct] [, forceall => $forceall]);
1921           This runs the ext2/ext3 filesystem checker on "device".  It can
1922           take the following optional arguments:
1923
1924           "correct"
1925               Automatically repair the file system. This option will cause
1926               e2fsck to automatically fix any filesystem problems that can be
1927               safely fixed without human intervention.
1928
1929               This option may not be specified at the same time as the
1930               "forceall" option.
1931
1932           "forceall"
1933               Assume an answer of ‘yes’ to all questions; allows e2fsck to be
1934               used non-interactively.
1935
1936               This option may not be specified at the same time as the
1937               "correct" option.
1938
1939       $g->e2fsck_f ($device);
1940           This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
1941           checker on "device", noninteractively (-p), even if the filesystem
1942           appears to be clean (-f).
1943
1944           This function is deprecated.  In new code, use the "e2fsck" call
1945           instead.
1946
1947           Deprecated functions will not be removed from the API, but the fact
1948           that they are deprecated indicates that there are problems with
1949           correct use of these functions.
1950
1951       $output = $g->echo_daemon (\@words);
1952           This command concatenates the list of "words" passed with single
1953           spaces between them and returns the resulting string.
1954
1955           You can use this command to test the connection through to the
1956           daemon.
1957
1958           See also "$g->ping_daemon".
1959
1960       @lines = $g->egrep ($regex, $path);
1961           This calls the external egrep(1) program and returns the matching
1962           lines.
1963
1964           Because of the message protocol, there is a transfer limit of
1965           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
1966           guestfs(3).
1967
1968           This function is deprecated.  In new code, use the "grep" call
1969           instead.
1970
1971           Deprecated functions will not be removed from the API, but the fact
1972           that they are deprecated indicates that there are problems with
1973           correct use of these functions.
1974
1975       @lines = $g->egrepi ($regex, $path);
1976           This calls the external "egrep -i" program and returns the matching
1977           lines.
1978
1979           Because of the message protocol, there is a transfer limit of
1980           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
1981           guestfs(3).
1982
1983           This function is deprecated.  In new code, use the "grep" call
1984           instead.
1985
1986           Deprecated functions will not be removed from the API, but the fact
1987           that they are deprecated indicates that there are problems with
1988           correct use of these functions.
1989
1990       $equality = $g->equal ($file1, $file2);
1991           This compares the two files file1 and file2 and returns true if
1992           their content is exactly equal, or false otherwise.
1993
1994           The external cmp(1) program is used for the comparison.
1995
1996       $existsflag = $g->exists ($path);
1997           This returns "true" if and only if there is a file, directory (or
1998           anything) with the given "path" name.
1999
2000           See also "$g->is_file", "$g->is_dir", "$g->stat".
2001
2002       $g->extlinux ($directory);
2003           Install the SYSLINUX bootloader on the device mounted at directory.
2004           Unlike "$g->syslinux" which requires a FAT filesystem, this can be
2005           used on an ext2/3/4 or btrfs filesystem.
2006
2007           The directory parameter can be either a mountpoint, or a directory
2008           within the mountpoint.
2009
2010           You also have to mark the partition as "active"
2011           ("$g->part_set_bootable") and a Master Boot Record must be
2012           installed (eg. using "$g->pwrite_device") on the first sector of
2013           the whole disk.  The SYSLINUX package comes with some suitable
2014           Master Boot Records.  See the extlinux(1) man page for further
2015           information.
2016
2017           Additional configuration can be supplied to SYSLINUX by placing a
2018           file called extlinux.conf on the filesystem under directory.  For
2019           further information about the contents of this file, see
2020           extlinux(1).
2021
2022           See also "$g->syslinux".
2023
2024           This function depends on the feature "extlinux".  See also
2025           "$g->feature-available".
2026
2027       $g->f2fs_expand ($device);
2028           This expands a f2fs filesystem to match the size of the underlying
2029           device.
2030
2031           This function depends on the feature "f2fs".  See also
2032           "$g->feature-available".
2033
2034       $g->fallocate ($path, $len);
2035           This command preallocates a file (containing zero bytes) named
2036           "path" of size "len" bytes.  If the file exists already, it is
2037           overwritten.
2038
2039           Do not confuse this with the guestfish-specific "alloc" command
2040           which allocates a file in the host and attaches it as a device.
2041
2042           This function is deprecated.  In new code, use the "fallocate64"
2043           call instead.
2044
2045           Deprecated functions will not be removed from the API, but the fact
2046           that they are deprecated indicates that there are problems with
2047           correct use of these functions.
2048
2049       $g->fallocate64 ($path, $len);
2050           This command preallocates a file (containing zero bytes) named
2051           "path" of size "len" bytes.  If the file exists already, it is
2052           overwritten.
2053
2054           Note that this call allocates disk blocks for the file.  To create
2055           a sparse file use "$g->truncate_size" instead.
2056
2057           The deprecated call "$g->fallocate" does the same, but owing to an
2058           oversight it only allowed 30 bit lengths to be specified,
2059           effectively limiting the maximum size of files created through that
2060           call to 1GB.
2061
2062           Do not confuse this with the guestfish-specific "alloc" and
2063           "sparse" commands which create a file in the host and attach it as
2064           a device.
2065
2066       $isavailable = $g->feature_available (\@groups);
2067           This is the same as "$g->available", but unlike that call it
2068           returns a simple true/false boolean result, instead of throwing an
2069           exception if a feature is not found.  For other documentation see
2070           "$g->available".
2071
2072       @lines = $g->fgrep ($pattern, $path);
2073           This calls the external fgrep(1) program and returns the matching
2074           lines.
2075
2076           Because of the message protocol, there is a transfer limit of
2077           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
2078           guestfs(3).
2079
2080           This function is deprecated.  In new code, use the "grep" call
2081           instead.
2082
2083           Deprecated functions will not be removed from the API, but the fact
2084           that they are deprecated indicates that there are problems with
2085           correct use of these functions.
2086
2087       @lines = $g->fgrepi ($pattern, $path);
2088           This calls the external "fgrep -i" program and returns the matching
2089           lines.
2090
2091           Because of the message protocol, there is a transfer limit of
2092           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
2093           guestfs(3).
2094
2095           This function is deprecated.  In new code, use the "grep" call
2096           instead.
2097
2098           Deprecated functions will not be removed from the API, but the fact
2099           that they are deprecated indicates that there are problems with
2100           correct use of these functions.
2101
2102       $description = $g->file ($path);
2103           This call uses the standard file(1) command to determine the type
2104           or contents of the file.
2105
2106           This call will also transparently look inside various types of
2107           compressed file.
2108
2109           The filename is not prepended to the output (like the file command
2110           -b option).
2111
2112           The output depends on the output of the underlying file(1) command
2113           and it can change in future in ways beyond our control.  In other
2114           words, the output is not guaranteed by the ABI.
2115
2116           See also: file(1), "$g->vfs_type", "$g->lstat", "$g->is_file",
2117           "$g->is_blockdev" (etc), "$g->is_zero".
2118
2119       $arch = $g->file_architecture ($filename);
2120           This detects the architecture of the binary filename, and returns
2121           it if known.
2122
2123           Currently defined architectures are:
2124
2125           "aarch64"
2126               64 bit ARM.
2127
2128           "arm"
2129               32 bit ARM.
2130
2131           "i386"
2132               This string is returned for all 32 bit i386, i486, i586, i686
2133               binaries irrespective of the precise processor requirements of
2134               the binary.
2135
2136           "ia64"
2137               Intel Itanium.
2138
2139           "ppc"
2140               32 bit Power PC.
2141
2142           "ppc64"
2143               64 bit Power PC (big endian).
2144
2145           "ppc64le"
2146               64 bit Power PC (little endian).
2147
2148           "riscv32"
2149           "riscv64"
2150           "riscv128"
2151               RISC-V 32-, 64- or 128-bit variants.
2152
2153           "s390"
2154               31 bit IBM S/390.
2155
2156           "s390x"
2157               64 bit IBM S/390.
2158
2159           "sparc"
2160               32 bit SPARC.
2161
2162           "sparc64"
2163               64 bit SPARC V9 and above.
2164
2165           "x86_64"
2166               64 bit x86-64.
2167
2168           Libguestfs may return other architecture strings in future.
2169
2170           The function works on at least the following types of files:
2171
2172           •   many types of Un*x and Linux binary
2173
2174           •   many types of Un*x and Linux shared library
2175
2176           •   Windows Win32 and Win64 binaries
2177
2178           •   Windows Win32 and Win64 DLLs
2179
2180               Win32 binaries and DLLs return "i386".
2181
2182               Win64 binaries and DLLs return "x86_64".
2183
2184           •   Linux kernel modules
2185
2186           •   Linux new-style initrd images
2187
2188           •   some non-x86 Linux vmlinuz kernels
2189
2190           What it can't do currently:
2191
2192           •   static libraries (libfoo.a)
2193
2194           •   Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
2195
2196           •   x86 Linux vmlinuz kernels
2197
2198               x86 vmlinuz images (bzImage format) consist of a mix of 16-,
2199               32- and compressed code, and are horribly hard to unpack.  If
2200               you want to find the architecture of a kernel, use the
2201               architecture of the associated initrd or kernel module(s)
2202               instead.
2203
2204       $size = $g->filesize ($file);
2205           This command returns the size of file in bytes.
2206
2207           To get other stats about a file, use "$g->stat", "$g->lstat",
2208           "$g->is_dir", "$g->is_file" etc.  To get the size of block devices,
2209           use "$g->blockdev_getsize64".
2210
2211       $fsavail = $g->filesystem_available ($filesystem);
2212           Check whether libguestfs supports the named filesystem.  The
2213           argument "filesystem" is a filesystem name, such as "ext3".
2214
2215           You must call "$g->launch" before using this command.
2216
2217           This is mainly useful as a negative test.  If this returns true, it
2218           doesn't mean that a particular filesystem can be created or
2219           mounted, since filesystems can fail for other reasons such as it
2220           being a later version of the filesystem, or having incompatible
2221           features, or lacking the right mkfs.<fs> tool.
2222
2223           See also "$g->available", "$g->feature_available", "AVAILABILITY"
2224           in guestfs(3).
2225
2226       @dirents = $g->filesystem_walk ($device);
2227           Walk through the internal structures of a disk partition (eg.
2228           /dev/sda1) in order to return a list of all the files and
2229           directories stored within.
2230
2231           It is not necessary to mount the disk partition to run this
2232           command.
2233
2234           All entries in the filesystem are returned. This function can list
2235           deleted or unaccessible files. The entries are not sorted.
2236
2237           The "tsk_dirent" structure contains the following fields.
2238
2239           "tsk_inode"
2240               Filesystem reference number of the node. It might be 0 if the
2241               node has been deleted.
2242
2243           "tsk_type"
2244               Basic file type information.  See below for a detailed list of
2245               values.
2246
2247           "tsk_size"
2248               File size in bytes. It might be -1 if the node has been
2249               deleted.
2250
2251           "tsk_name"
2252               The file path relative to its directory.
2253
2254           "tsk_flags"
2255               Bitfield containing extra information regarding the entry.  It
2256               contains the logical OR of the following values:
2257
2258               0x0001
2259                   If set to 1, the file is allocated and visible within the
2260                   filesystem.  Otherwise, the file has been deleted.  Under
2261                   certain circumstances, the function "download_inode" can be
2262                   used to recover deleted files.
2263
2264               0x0002
2265                   Filesystem such as NTFS and Ext2 or greater, separate the
2266                   file name from the metadata structure.  The bit is set to 1
2267                   when the file name is in an unallocated state and the
2268                   metadata structure is in an allocated one.  This generally
2269                   implies the metadata has been reallocated to a new file.
2270                   Therefore, information such as file type, file size,
2271                   timestamps, number of links and symlink target might not
2272                   correspond with the ones of the original deleted entry.
2273
2274               0x0004
2275                   The bit is set to 1 when the file is compressed using
2276                   filesystem native compression support (NTFS). The API is
2277                   not able to detect application level compression.
2278
2279           "tsk_atime_sec"
2280           "tsk_atime_nsec"
2281           "tsk_mtime_sec"
2282           "tsk_mtime_nsec"
2283           "tsk_ctime_sec"
2284           "tsk_ctime_nsec"
2285           "tsk_crtime_sec"
2286           "tsk_crtime_nsec"
2287               Respectively, access, modification, last status change and
2288               creation time in Unix format in seconds and nanoseconds.
2289
2290           "tsk_nlink"
2291               Number of file names pointing to this entry.
2292
2293           "tsk_link"
2294               If the entry is a symbolic link, this field will contain the
2295               path to the target file.
2296
2297           The "tsk_type" field will contain one of the following characters:
2298
2299           'b' Block special
2300
2301           'c' Char special
2302
2303           'd' Directory
2304
2305           'f' FIFO (named pipe)
2306
2307           'l' Symbolic link
2308
2309           'r' Regular file
2310
2311           's' Socket
2312
2313           'h' Shadow inode (Solaris)
2314
2315           'w' Whiteout inode (BSD)
2316
2317           'u' Unknown file type
2318
2319           This function depends on the feature "libtsk".  See also
2320           "$g->feature-available".
2321
2322       $g->fill ($c, $len, $path);
2323           This command creates a new file called "path".  The initial content
2324           of the file is "len" octets of "c", where "c" must be a number in
2325           the range "[0..255]".
2326
2327           To fill a file with zero bytes (sparsely), it is much more
2328           efficient to use "$g->truncate_size".  To create a file with a
2329           pattern of repeating bytes use "$g->fill_pattern".
2330
2331       $g->fill_dir ($dir, $nr);
2332           This function, useful for testing filesystems, creates "nr" empty
2333           files in the directory "dir" with names 00000000 through "nr-1"
2334           (ie. each file name is 8 digits long padded with zeroes).
2335
2336       $g->fill_pattern ($pattern, $len, $path);
2337           This function is like "$g->fill" except that it creates a new file
2338           of length "len" containing the repeating pattern of bytes in
2339           "pattern".  The pattern is truncated if necessary to ensure the
2340           length of the file is exactly "len" bytes.
2341
2342       @names = $g->find ($directory);
2343           This command lists out all files and directories, recursively,
2344           starting at directory.  It is essentially equivalent to running the
2345           shell command "find directory -print" but some post-processing
2346           happens on the output, described below.
2347
2348           This returns a list of strings without any prefix.  Thus if the
2349           directory structure was:
2350
2351            /tmp/a
2352            /tmp/b
2353            /tmp/c/d
2354
2355           then the returned list from "$g->find" /tmp would be 4 elements:
2356
2357            a
2358            b
2359            c
2360            c/d
2361
2362           If directory is not a directory, then this command returns an
2363           error.
2364
2365           The returned list is sorted.
2366
2367       $g->find0 ($directory, $files);
2368           This command lists out all files and directories, recursively,
2369           starting at directory, placing the resulting list in the external
2370           file called files.
2371
2372           This command works the same way as "$g->find" with the following
2373           exceptions:
2374
2375           •   The resulting list is written to an external file.
2376
2377           •   Items (filenames) in the result are separated by "\0"
2378               characters.  See find(1) option -print0.
2379
2380           •   The result list is not sorted.
2381
2382       @dirents = $g->find_inode ($device, $inode);
2383           Searches all the entries associated with the given inode.
2384
2385           For each entry, a "tsk_dirent" structure is returned.  See
2386           "filesystem_walk" for more information about "tsk_dirent"
2387           structures.
2388
2389           This function depends on the feature "libtsk".  See also
2390           "$g->feature-available".
2391
2392       $device = $g->findfs_label ($label);
2393           This command searches the filesystems and returns the one which has
2394           the given label.  An error is returned if no such filesystem can be
2395           found.
2396
2397           To find the label of a filesystem, use "$g->vfs_label".
2398
2399       $device = $g->findfs_uuid ($uuid);
2400           This command searches the filesystems and returns the one which has
2401           the given UUID.  An error is returned if no such filesystem can be
2402           found.
2403
2404           To find the UUID of a filesystem, use "$g->vfs_uuid".
2405
2406       $status = $g->fsck ($fstype, $device);
2407           This runs the filesystem checker (fsck) on "device" which should
2408           have filesystem type "fstype".
2409
2410           The returned integer is the status.  See fsck(8) for the list of
2411           status codes from "fsck".
2412
2413           Notes:
2414
2415           •   Multiple status codes can be summed together.
2416
2417           •   A non-zero return code can mean "success", for example if
2418               errors have been corrected on the filesystem.
2419
2420           •   Checking or repairing NTFS volumes is not supported (by linux-
2421               ntfs).
2422
2423           This command is entirely equivalent to running "fsck -a -t fstype
2424           device".
2425
2426       $g->fstrim ($mountpoint [, offset => $offset] [, length => $length] [,
2427       minimumfreeextent => $minimumfreeextent]);
2428           Trim the free space in the filesystem mounted on "mountpoint".  The
2429           filesystem must be mounted read-write.
2430
2431           The filesystem contents are not affected, but any free space in the
2432           filesystem is "trimmed", that is, given back to the host device,
2433           thus making disk images more sparse, allowing unused space in qcow2
2434           files to be reused, etc.
2435
2436           This operation requires support in libguestfs, the mounted
2437           filesystem, the host filesystem, qemu and the host kernel.  If this
2438           support isn't present it may give an error or even appear to run
2439           but do nothing.
2440
2441           In the case where the kernel vfs driver does not support trimming,
2442           this call will fail with errno set to "ENOTSUP".  Currently this
2443           happens when trying to trim FAT filesystems.
2444
2445           See also "$g->zero_free_space".  That is a slightly different
2446           operation that turns free space in the filesystem into zeroes.  It
2447           is valid to call "$g->fstrim" either instead of, or after calling
2448           "$g->zero_free_space".
2449
2450           This function depends on the feature "fstrim".  See also
2451           "$g->feature-available".
2452
2453       $append = $g->get_append ();
2454           Return the additional kernel options which are added to the
2455           libguestfs appliance kernel command line.
2456
2457           If "NULL" then no options are added.
2458
2459       $backend = $g->get_attach_method ();
2460           Return the current backend.
2461
2462           See "$g->set_backend" and "BACKEND" in guestfs(3).
2463
2464           This function is deprecated.  In new code, use the "get_backend"
2465           call instead.
2466
2467           Deprecated functions will not be removed from the API, but the fact
2468           that they are deprecated indicates that there are problems with
2469           correct use of these functions.
2470
2471       $autosync = $g->get_autosync ();
2472           Get the autosync flag.
2473
2474       $backend = $g->get_backend ();
2475           Return the current backend.
2476
2477           This handle property was previously called the "attach method".
2478
2479           See "$g->set_backend" and "BACKEND" in guestfs(3).
2480
2481       $val = $g->get_backend_setting ($name);
2482           Find a backend setting string which is either "name" or begins with
2483           "name=".  If "name", this returns the string "1".  If "name=", this
2484           returns the part after the equals sign (which may be an empty
2485           string).
2486
2487           If no such setting is found, this function throws an error.  The
2488           errno (see "$g->last_errno") will be "ESRCH" in this case.
2489
2490           See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
2491
2492       @settings = $g->get_backend_settings ();
2493           Return the current backend settings.
2494
2495           This call returns all backend settings strings.  If you want to
2496           find a single backend setting, see "$g->get_backend_setting".
2497
2498           See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
2499
2500       $cachedir = $g->get_cachedir ();
2501           Get the directory used by the handle to store the appliance cache.
2502
2503       $direct = $g->get_direct ();
2504           Return the direct appliance mode flag.
2505
2506           This function is deprecated.  In new code, use the
2507           "internal_get_console_socket" call instead.
2508
2509           Deprecated functions will not be removed from the API, but the fact
2510           that they are deprecated indicates that there are problems with
2511           correct use of these functions.
2512
2513       $attrs = $g->get_e2attrs ($file);
2514           This returns the file attributes associated with file.
2515
2516           The attributes are a set of bits associated with each inode which
2517           affect the behaviour of the file.  The attributes are returned as a
2518           string of letters (described below).  The string may be empty,
2519           indicating that no file attributes are set for this file.
2520
2521           These attributes are only present when the file is located on an
2522           ext2/3/4 filesystem.  Using this call on other filesystem types
2523           will result in an error.
2524
2525           The characters (file attributes) in the returned string are
2526           currently:
2527
2528           'A' When the file is accessed, its atime is not modified.
2529
2530           'a' The file is append-only.
2531
2532           'c' The file is compressed on-disk.
2533
2534           'D' (Directories only.)  Changes to this directory are written
2535               synchronously to disk.
2536
2537           'd' The file is not a candidate for backup (see dump(8)).
2538
2539           'E' The file has compression errors.
2540
2541           'e' The file is using extents.
2542
2543           'h' The file is storing its blocks in units of the filesystem
2544               blocksize instead of sectors.
2545
2546           'I' (Directories only.)  The directory is using hashed trees.
2547
2548           'i' The file is immutable.  It cannot be modified, deleted or
2549               renamed.  No link can be created to this file.
2550
2551           'j' The file is data-journaled.
2552
2553           's' When the file is deleted, all its blocks will be zeroed.
2554
2555           'S' Changes to this file are written synchronously to disk.
2556
2557           'T' (Directories only.)  This is a hint to the block allocator that
2558               subdirectories contained in this directory should be spread
2559               across blocks.  If not present, the block allocator will try to
2560               group subdirectories together.
2561
2562           't' For a file, this disables tail-merging.  (Not used by upstream
2563               implementations of ext2.)
2564
2565           'u' When the file is deleted, its blocks will be saved, allowing
2566               the file to be undeleted.
2567
2568           'X' The raw contents of the compressed file may be accessed.
2569
2570           'Z' The compressed file is dirty.
2571
2572           More file attributes may be added to this list later.  Not all file
2573           attributes may be set for all kinds of files.  For detailed
2574           information, consult the chattr(1) man page.
2575
2576           See also "$g->set_e2attrs".
2577
2578           Don't confuse these attributes with extended attributes (see
2579           "$g->getxattr").
2580
2581       $generation = $g->get_e2generation ($file);
2582           This returns the ext2 file generation of a file.  The generation
2583           (which used to be called the "version") is a number associated with
2584           an inode.  This is most commonly used by NFS servers.
2585
2586           The generation is only present when the file is located on an
2587           ext2/3/4 filesystem.  Using this call on other filesystem types
2588           will result in an error.
2589
2590           See "$g->set_e2generation".
2591
2592       $label = $g->get_e2label ($device);
2593           This returns the ext2/3/4 filesystem label of the filesystem on
2594           "device".
2595
2596           This function is deprecated.  In new code, use the "vfs_label" call
2597           instead.
2598
2599           Deprecated functions will not be removed from the API, but the fact
2600           that they are deprecated indicates that there are problems with
2601           correct use of these functions.
2602
2603       $uuid = $g->get_e2uuid ($device);
2604           This returns the ext2/3/4 filesystem UUID of the filesystem on
2605           "device".
2606
2607           This function is deprecated.  In new code, use the "vfs_uuid" call
2608           instead.
2609
2610           Deprecated functions will not be removed from the API, but the fact
2611           that they are deprecated indicates that there are problems with
2612           correct use of these functions.
2613
2614       $hv = $g->get_hv ();
2615           Return the current hypervisor binary.
2616
2617           This is always non-NULL.  If it wasn't set already, then this will
2618           return the default qemu binary name.
2619
2620       $identifier = $g->get_identifier ();
2621           Get the handle identifier.  See "$g->set_identifier".
2622
2623       $challenge = $g->get_libvirt_requested_credential_challenge ($index);
2624           Get the challenge (provided by libvirt) for the "index"'th
2625           requested credential.  If libvirt did not provide a challenge, this
2626           returns the empty string "".
2627
2628           See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2629           example code.
2630
2631       $defresult = $g->get_libvirt_requested_credential_defresult ($index);
2632           Get the default result (provided by libvirt) for the "index"'th
2633           requested credential.  If libvirt did not provide a default result,
2634           this returns the empty string "".
2635
2636           See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2637           example code.
2638
2639       $prompt = $g->get_libvirt_requested_credential_prompt ($index);
2640           Get the prompt (provided by libvirt) for the "index"'th requested
2641           credential.  If libvirt did not provide a prompt, this returns the
2642           empty string "".
2643
2644           See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2645           example code.
2646
2647       @creds = $g->get_libvirt_requested_credentials ();
2648           This should only be called during the event callback for events of
2649           type "GUESTFS_EVENT_LIBVIRT_AUTH".
2650
2651           Return the list of credentials requested by libvirt.  Possible
2652           values are a subset of the strings provided when you called
2653           "$g->set_libvirt_supported_credentials".
2654
2655           See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2656           example code.
2657
2658       $memsize = $g->get_memsize ();
2659           This gets the memory size in megabytes allocated to the hypervisor.
2660
2661           If "$g->set_memsize" was not called on this handle, and if
2662           "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
2663           default value for memsize.
2664
2665           For more information on the architecture of libguestfs, see
2666           guestfs(3).
2667
2668       $network = $g->get_network ();
2669           This returns the enable network flag.
2670
2671       $path = $g->get_path ();
2672           Return the current search path.
2673
2674           This is always non-NULL.  If it wasn't set already, then this will
2675           return the default path.
2676
2677       $pgroup = $g->get_pgroup ();
2678           This returns the process group flag.
2679
2680       $pid = $g->get_pid ();
2681           Return the process ID of the hypervisor.  If there is no hypervisor
2682           running, then this will return an error.
2683
2684           This is an internal call used for debugging and testing.
2685
2686       $program = $g->get_program ();
2687           Get the program name.  See "$g->set_program".
2688
2689       $hv = $g->get_qemu ();
2690           Return the current hypervisor binary (usually qemu).
2691
2692           This is always non-NULL.  If it wasn't set already, then this will
2693           return the default qemu binary name.
2694
2695           This function is deprecated.  In new code, use the "get_hv" call
2696           instead.
2697
2698           Deprecated functions will not be removed from the API, but the fact
2699           that they are deprecated indicates that there are problems with
2700           correct use of these functions.
2701
2702       $recoveryproc = $g->get_recovery_proc ();
2703           Return the recovery process enabled flag.
2704
2705       $selinux = $g->get_selinux ();
2706           This returns the current setting of the selinux flag which is
2707           passed to the appliance at boot time.  See "$g->set_selinux".
2708
2709           For more information on the architecture of libguestfs, see
2710           guestfs(3).
2711
2712           This function is deprecated.  In new code, use the
2713           "selinux_relabel" call instead.
2714
2715           Deprecated functions will not be removed from the API, but the fact
2716           that they are deprecated indicates that there are problems with
2717           correct use of these functions.
2718
2719       $smp = $g->get_smp ();
2720           This returns the number of virtual CPUs assigned to the appliance.
2721
2722       $sockdir = $g->get_sockdir ();
2723           Get the directory used by the handle to store temporary socket
2724           files.
2725
2726           This is different from "$g->get_tmpdir", as we need shorter paths
2727           for sockets (due to the limited buffers of filenames for UNIX
2728           sockets), and "$g->get_tmpdir" may be too long for them.
2729
2730           The environment variable "XDG_RUNTIME_DIR" controls the default
2731           value: If "XDG_RUNTIME_DIR" is set, then that is the default.  Else
2732           /tmp is the default.
2733
2734       $state = $g->get_state ();
2735           This returns the current state as an opaque integer.  This is only
2736           useful for printing debug and internal error messages.
2737
2738           For more information on states, see guestfs(3).
2739
2740       $tmpdir = $g->get_tmpdir ();
2741           Get the directory used by the handle to store temporary files.
2742
2743       $trace = $g->get_trace ();
2744           Return the command trace flag.
2745
2746       $mask = $g->get_umask ();
2747           Return the current umask.  By default the umask is 022 unless it
2748           has been set by calling "$g->umask".
2749
2750       $verbose = $g->get_verbose ();
2751           This returns the verbose messages flag.
2752
2753       $context = $g->getcon ();
2754           This gets the SELinux security context of the daemon.
2755
2756           See the documentation about SELINUX in guestfs(3), and "$g->setcon"
2757
2758           This function depends on the feature "selinux".  See also
2759           "$g->feature-available".
2760
2761           This function is deprecated.  In new code, use the
2762           "selinux_relabel" call instead.
2763
2764           Deprecated functions will not be removed from the API, but the fact
2765           that they are deprecated indicates that there are problems with
2766           correct use of these functions.
2767
2768       $xattr = $g->getxattr ($path, $name);
2769           Get a single extended attribute from file "path" named "name".
2770           This call follows symlinks.  If you want to lookup an extended
2771           attribute for the symlink itself, use "$g->lgetxattr".
2772
2773           Normally it is better to get all extended attributes from a file in
2774           one go by calling "$g->getxattrs".  However some Linux filesystem
2775           implementations are buggy and do not provide a way to list out
2776           attributes.  For these filesystems (notably ntfs-3g) you have to
2777           know the names of the extended attributes you want in advance and
2778           call this function.
2779
2780           Extended attribute values are blobs of binary data.  If there is no
2781           extended attribute named "name", this returns an error.
2782
2783           See also: "$g->getxattrs", "$g->lgetxattr", attr(5).
2784
2785           This function depends on the feature "linuxxattrs".  See also
2786           "$g->feature-available".
2787
2788       @xattrs = $g->getxattrs ($path);
2789           This call lists the extended attributes of the file or directory
2790           "path".
2791
2792           At the system call level, this is a combination of the listxattr(2)
2793           and getxattr(2) calls.
2794
2795           See also: "$g->lgetxattrs", attr(5).
2796
2797           This function depends on the feature "linuxxattrs".  See also
2798           "$g->feature-available".
2799
2800       @paths = $g->glob_expand ($pattern [, directoryslash =>
2801       $directoryslash]);
2802           This command searches for all the pathnames matching "pattern"
2803           according to the wildcard expansion rules used by the shell.
2804
2805           If no paths match, then this returns an empty list (note: not an
2806           error).
2807
2808           It is just a wrapper around the C glob(3) function with flags
2809           "GLOB_MARK|GLOB_BRACE".  See that manual page for more details.
2810
2811           "directoryslash" controls whether use the "GLOB_MARK" flag for
2812           glob(3), and it defaults to true.  It can be explicitly set as off
2813           to return no trailing slashes in filenames of directories.
2814
2815           Notice that there is no equivalent command for expanding a device
2816           name (eg. /dev/sd*).  Use "$g->list_devices", "$g->list_partitions"
2817           etc functions instead.
2818
2819       @paths = $g->glob_expand_opts ($pattern [, directoryslash =>
2820       $directoryslash]);
2821           This is an alias of "glob_expand".
2822
2823       @lines = $g->grep ($regex, $path [, extended => $extended] [, fixed =>
2824       $fixed] [, insensitive => $insensitive] [, compressed => $compressed]);
2825           This calls the external grep(1) program and returns the matching
2826           lines.
2827
2828           The optional flags are:
2829
2830           "extended"
2831               Use extended regular expressions.  This is the same as using
2832               the -E flag.
2833
2834           "fixed"
2835               Match fixed (don't use regular expressions).  This is the same
2836               as using the -F flag.
2837
2838           "insensitive"
2839               Match case-insensitive.  This is the same as using the -i flag.
2840
2841           "compressed"
2842               Use zgrep(1) instead of grep(1).  This allows the input to be
2843               compress- or gzip-compressed.
2844
2845           Because of the message protocol, there is a transfer limit of
2846           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
2847           guestfs(3).
2848
2849       @lines = $g->grep_opts ($regex, $path [, extended => $extended] [,
2850       fixed => $fixed] [, insensitive => $insensitive] [, compressed =>
2851       $compressed]);
2852           This is an alias of "grep".
2853
2854       @lines = $g->grepi ($regex, $path);
2855           This calls the external "grep -i" program and returns the matching
2856           lines.
2857
2858           Because of the message protocol, there is a transfer limit of
2859           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
2860           guestfs(3).
2861
2862           This function is deprecated.  In new code, use the "grep" call
2863           instead.
2864
2865           Deprecated functions will not be removed from the API, but the fact
2866           that they are deprecated indicates that there are problems with
2867           correct use of these functions.
2868
2869       $g->grub_install ($root, $device);
2870           This command installs GRUB 1 (the Grand Unified Bootloader) on
2871           "device", with the root directory being "root".
2872
2873           Notes:
2874
2875           •   There is currently no way in the API to install grub2, which is
2876               used by most modern Linux guests.  It is possible to run the
2877               grub2 command from the guest, although see the caveats in
2878               "RUNNING COMMANDS" in guestfs(3).
2879
2880           •   This uses grub-install(8) from the host.  Unfortunately grub is
2881               not always compatible with itself, so this only works in rather
2882               narrow circumstances.  Careful testing with each guest version
2883               is advisable.
2884
2885           •   If grub-install reports the error "No suitable drive was found
2886               in the generated device map."  it may be that you need to
2887               create a /boot/grub/device.map file first that contains the
2888               mapping between grub device names and Linux device names.  It
2889               is usually sufficient to create a file containing:
2890
2891                (hd0) /dev/vda
2892
2893               replacing /dev/vda with the name of the installation device.
2894
2895           This function depends on the feature "grub".  See also
2896           "$g->feature-available".
2897
2898       @lines = $g->head ($path);
2899           This command returns up to the first 10 lines of a file as a list
2900           of strings.
2901
2902           Because of the message protocol, there is a transfer limit of
2903           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
2904           guestfs(3).
2905
2906       @lines = $g->head_n ($nrlines, $path);
2907           If the parameter "nrlines" is a positive number, this returns the
2908           first "nrlines" lines of the file "path".
2909
2910           If the parameter "nrlines" is a negative number, this returns lines
2911           from the file "path", excluding the last "nrlines" lines.
2912
2913           If the parameter "nrlines" is zero, this returns an empty list.
2914
2915           Because of the message protocol, there is a transfer limit of
2916           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
2917           guestfs(3).
2918
2919       $dump = $g->hexdump ($path);
2920           This runs "hexdump -C" on the given "path".  The result is the
2921           human-readable, canonical hex dump of the file.
2922
2923           Because of the message protocol, there is a transfer limit of
2924           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
2925           guestfs(3).
2926
2927       $g->hivex_close ();
2928           Close the current hivex handle.
2929
2930           This is a wrapper around the hivex(3) call of the same name.
2931
2932           This function depends on the feature "hivex".  See also
2933           "$g->feature-available".
2934
2935       $g->hivex_commit ($filename);
2936           Commit (write) changes to the hive.
2937
2938           If the optional filename parameter is null, then the changes are
2939           written back to the same hive that was opened.  If this is not null
2940           then they are written to the alternate filename given and the
2941           original hive is left untouched.
2942
2943           This is a wrapper around the hivex(3) call of the same name.
2944
2945           This function depends on the feature "hivex".  See also
2946           "$g->feature-available".
2947
2948       $nodeh = $g->hivex_node_add_child ($parent, $name);
2949           Add a child node to "parent" named "name".
2950
2951           This is a wrapper around the hivex(3) call of the same name.
2952
2953           This function depends on the feature "hivex".  See also
2954           "$g->feature-available".
2955
2956       @nodehs = $g->hivex_node_children ($nodeh);
2957           Return the list of nodes which are subkeys of "nodeh".
2958
2959           This is a wrapper around the hivex(3) call of the same name.
2960
2961           This function depends on the feature "hivex".  See also
2962           "$g->feature-available".
2963
2964       $g->hivex_node_delete_child ($nodeh);
2965           Delete "nodeh", recursively if necessary.
2966
2967           This is a wrapper around the hivex(3) call of the same name.
2968
2969           This function depends on the feature "hivex".  See also
2970           "$g->feature-available".
2971
2972       $child = $g->hivex_node_get_child ($nodeh, $name);
2973           Return the child of "nodeh" with the name "name", if it exists.
2974           This can return 0 meaning the name was not found.
2975
2976           This is a wrapper around the hivex(3) call of the same name.
2977
2978           This function depends on the feature "hivex".  See also
2979           "$g->feature-available".
2980
2981       $valueh = $g->hivex_node_get_value ($nodeh, $key);
2982           Return the value attached to "nodeh" which has the name "key", if
2983           it exists.  This can return 0 meaning the key was not found.
2984
2985           This is a wrapper around the hivex(3) call of the same name.
2986
2987           This function depends on the feature "hivex".  See also
2988           "$g->feature-available".
2989
2990       $name = $g->hivex_node_name ($nodeh);
2991           Return the name of "nodeh".
2992
2993           This is a wrapper around the hivex(3) call of the same name.
2994
2995           This function depends on the feature "hivex".  See also
2996           "$g->feature-available".
2997
2998       $parent = $g->hivex_node_parent ($nodeh);
2999           Return the parent node of "nodeh".
3000
3001           This is a wrapper around the hivex(3) call of the same name.
3002
3003           This function depends on the feature "hivex".  See also
3004           "$g->feature-available".
3005
3006       $g->hivex_node_set_value ($nodeh, $key, $t, $val);
3007           Set or replace a single value under the node "nodeh".  The "key" is
3008           the name, "t" is the type, and "val" is the data.
3009
3010           This is a wrapper around the hivex(3) call of the same name.
3011
3012           This function depends on the feature "hivex".  See also
3013           "$g->feature-available".
3014
3015       @valuehs = $g->hivex_node_values ($nodeh);
3016           Return the array of (key, datatype, data) tuples attached to
3017           "nodeh".
3018
3019           This is a wrapper around the hivex(3) call of the same name.
3020
3021           This function depends on the feature "hivex".  See also
3022           "$g->feature-available".
3023
3024       $g->hivex_open ($filename [, verbose => $verbose] [, debug => $debug]
3025       [, write => $write] [, unsafe => $unsafe]);
3026           Open the Windows Registry hive file named filename.  If there was
3027           any previous hivex handle associated with this guestfs session,
3028           then it is closed.
3029
3030           This is a wrapper around the hivex(3) call of the same name.
3031
3032           This function depends on the feature "hivex".  See also
3033           "$g->feature-available".
3034
3035       $nodeh = $g->hivex_root ();
3036           Return the root node of the hive.
3037
3038           This is a wrapper around the hivex(3) call of the same name.
3039
3040           This function depends on the feature "hivex".  See also
3041           "$g->feature-available".
3042
3043       $key = $g->hivex_value_key ($valueh);
3044           Return the key (name) field of a (key, datatype, data) tuple.
3045
3046           This is a wrapper around the hivex(3) call of the same name.
3047
3048           This function depends on the feature "hivex".  See also
3049           "$g->feature-available".
3050
3051       $databuf = $g->hivex_value_string ($valueh);
3052           This calls "$g->hivex_value_value" (which returns the data field
3053           from a hivex value tuple).  It then assumes that the field is a
3054           UTF-16LE string and converts the result to UTF-8 (or if this is not
3055           possible, it returns an error).
3056
3057           This is useful for reading strings out of the Windows registry.
3058           However it is not foolproof because the registry is not strongly-
3059           typed and fields can contain arbitrary or unexpected data.
3060
3061           This function depends on the feature "hivex".  See also
3062           "$g->feature-available".
3063
3064       $datatype = $g->hivex_value_type ($valueh);
3065           Return the data type field from a (key, datatype, data) tuple.
3066
3067           This is a wrapper around the hivex(3) call of the same name.
3068
3069           This function depends on the feature "hivex".  See also
3070           "$g->feature-available".
3071
3072       $databuf = $g->hivex_value_utf8 ($valueh);
3073           This calls "$g->hivex_value_value" (which returns the data field
3074           from a hivex value tuple).  It then assumes that the field is a
3075           UTF-16LE string and converts the result to UTF-8 (or if this is not
3076           possible, it returns an error).
3077
3078           This is useful for reading strings out of the Windows registry.
3079           However it is not foolproof because the registry is not strongly-
3080           typed and fields can contain arbitrary or unexpected data.
3081
3082           This function depends on the feature "hivex".  See also
3083           "$g->feature-available".
3084
3085           This function is deprecated.  In new code, use the
3086           "hivex_value_string" call instead.
3087
3088           Deprecated functions will not be removed from the API, but the fact
3089           that they are deprecated indicates that there are problems with
3090           correct use of these functions.
3091
3092       $databuf = $g->hivex_value_value ($valueh);
3093           Return the data field of a (key, datatype, data) tuple.
3094
3095           This is a wrapper around the hivex(3) call of the same name.
3096
3097           See also: "$g->hivex_value_utf8".
3098
3099           This function depends on the feature "hivex".  See also
3100           "$g->feature-available".
3101
3102       $content = $g->initrd_cat ($initrdpath, $filename);
3103           This command unpacks the file filename from the initrd file called
3104           initrdpath.  The filename must be given without the initial /
3105           character.
3106
3107           For example, in guestfish you could use the following command to
3108           examine the boot script (usually called /init) contained in a Linux
3109           initrd or initramfs image:
3110
3111            initrd-cat /boot/initrd-<version>.img init
3112
3113           See also "$g->initrd_list".
3114
3115           Because of the message protocol, there is a transfer limit of
3116           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
3117           guestfs(3).
3118
3119       @filenames = $g->initrd_list ($path);
3120           This command lists out files contained in an initrd.
3121
3122           The files are listed without any initial / character.  The files
3123           are listed in the order they appear (not necessarily alphabetical).
3124           Directory names are listed as separate items.
3125
3126           Old Linux kernels (2.4 and earlier) used a compressed ext2
3127           filesystem as initrd.  We only support the newer initramfs format
3128           (compressed cpio files).
3129
3130       $wd = $g->inotify_add_watch ($path, $mask);
3131           Watch "path" for the events listed in "mask".
3132
3133           Note that if "path" is a directory then events within that
3134           directory are watched, but this does not happen recursively (in
3135           subdirectories).
3136
3137           Note for non-C or non-Linux callers: the inotify events are defined
3138           by the Linux kernel ABI and are listed in
3139           /usr/include/sys/inotify.h.
3140
3141           This function depends on the feature "inotify".  See also
3142           "$g->feature-available".
3143
3144       $g->inotify_close ();
3145           This closes the inotify handle which was previously opened by
3146           inotify_init.  It removes all watches, throws away any pending
3147           events, and deallocates all resources.
3148
3149           This function depends on the feature "inotify".  See also
3150           "$g->feature-available".
3151
3152       @paths = $g->inotify_files ();
3153           This function is a helpful wrapper around "$g->inotify_read" which
3154           just returns a list of pathnames of objects that were touched.  The
3155           returned pathnames are sorted and deduplicated.
3156
3157           This function depends on the feature "inotify".  See also
3158           "$g->feature-available".
3159
3160       $g->inotify_init ($maxevents);
3161           This command creates a new inotify handle.  The inotify subsystem
3162           can be used to notify events which happen to objects in the guest
3163           filesystem.
3164
3165           "maxevents" is the maximum number of events which will be queued up
3166           between calls to "$g->inotify_read" or "$g->inotify_files".  If
3167           this is passed as 0, then the kernel (or previously set) default is
3168           used.  For Linux 2.6.29 the default was 16384 events.  Beyond this
3169           limit, the kernel throws away events, but records the fact that it
3170           threw them away by setting a flag "IN_Q_OVERFLOW" in the returned
3171           structure list (see "$g->inotify_read").
3172
3173           Before any events are generated, you have to add some watches to
3174           the internal watch list.  See: "$g->inotify_add_watch" and
3175           "$g->inotify_rm_watch".
3176
3177           Queued up events should be read periodically by calling
3178           "$g->inotify_read" (or "$g->inotify_files" which is just a helpful
3179           wrapper around "$g->inotify_read").  If you don't read the events
3180           out often enough then you risk the internal queue overflowing.
3181
3182           The handle should be closed after use by calling
3183           "$g->inotify_close".  This also removes any watches automatically.
3184
3185           See also inotify(7) for an overview of the inotify interface as
3186           exposed by the Linux kernel, which is roughly what we expose via
3187           libguestfs.  Note that there is one global inotify handle per
3188           libguestfs instance.
3189
3190           This function depends on the feature "inotify".  See also
3191           "$g->feature-available".
3192
3193       @events = $g->inotify_read ();
3194           Return the complete queue of events that have happened since the
3195           previous read call.
3196
3197           If no events have happened, this returns an empty list.
3198
3199           Note: In order to make sure that all events have been read, you
3200           must call this function repeatedly until it returns an empty list.
3201           The reason is that the call will read events up to the maximum
3202           appliance-to-host message size and leave remaining events in the
3203           queue.
3204
3205           This function depends on the feature "inotify".  See also
3206           "$g->feature-available".
3207
3208       $g->inotify_rm_watch ($wd);
3209           Remove a previously defined inotify watch.  See
3210           "$g->inotify_add_watch".
3211
3212           This function depends on the feature "inotify".  See also
3213           "$g->feature-available".
3214
3215       $arch = $g->inspect_get_arch ($root);
3216           This returns the architecture of the inspected operating system.
3217           The possible return values are listed under
3218           "$g->file_architecture".
3219
3220           If the architecture could not be determined, then the string
3221           "unknown" is returned.
3222
3223           Please read "INSPECTION" in guestfs(3) for more details.
3224
3225       $buildid = $g->inspect_get_build_id ($root);
3226           This returns the build ID of the system, or the string "unknown" if
3227           the system does not have a build ID.
3228
3229           For Windows, this gets the build number.  Although it is returned
3230           as a string, it is (so far) always a number.  See
3231           <https://en.wikipedia.org/wiki/List_of_Microsoft_Windows_versions>
3232           for some possible values.
3233
3234           For Linux, this returns the "BUILD_ID" string from /etc/os-release,
3235           although this is not often used.
3236
3237           Please read "INSPECTION" in guestfs(3) for more details.
3238
3239       $distro = $g->inspect_get_distro ($root);
3240           This returns the distro (distribution) of the inspected operating
3241           system.
3242
3243           Currently defined distros are:
3244
3245           "alpinelinux"
3246               Alpine Linux.
3247
3248           "altlinux"
3249               ALT Linux.
3250
3251           "archlinux"
3252               Arch Linux.
3253
3254           "buildroot"
3255               Buildroot-derived distro, but not one we specifically
3256               recognize.
3257
3258           "centos"
3259               CentOS.
3260
3261           "cirros"
3262               Cirros.
3263
3264           "coreos"
3265               CoreOS.
3266
3267           "debian"
3268               Debian.
3269
3270           "fedora"
3271               Fedora.
3272
3273           "freebsd"
3274               FreeBSD.
3275
3276           "freedos"
3277               FreeDOS.
3278
3279           "frugalware"
3280               Frugalware.
3281
3282           "gentoo"
3283               Gentoo.
3284
3285           "kalilinux"
3286               Kali Linux.
3287
3288           "kylin"
3289               Kylin.
3290
3291           "linuxmint"
3292               Linux Mint.
3293
3294           "mageia"
3295               Mageia.
3296
3297           "mandriva"
3298               Mandriva.
3299
3300           "meego"
3301               MeeGo.
3302
3303           "msdos"
3304               Microsoft DOS.
3305
3306           "neokylin"
3307               NeoKylin.
3308
3309           "netbsd"
3310               NetBSD.
3311
3312           "openbsd"
3313               OpenBSD.
3314
3315           "openmandriva"
3316               OpenMandriva Lx.
3317
3318           "opensuse"
3319               OpenSUSE.
3320
3321           "oraclelinux"
3322               Oracle Linux.
3323
3324           "pardus"
3325               Pardus.
3326
3327           "pldlinux"
3328               PLD Linux.
3329
3330           "redhat-based"
3331               Some Red Hat-derived distro.
3332
3333           "rhel"
3334               Red Hat Enterprise Linux.
3335
3336           "rocky"
3337               Rocky Linux.
3338
3339           "scientificlinux"
3340               Scientific Linux.
3341
3342           "slackware"
3343               Slackware.
3344
3345           "sles"
3346               SuSE Linux Enterprise Server or Desktop.
3347
3348           "suse-based"
3349               Some openSuSE-derived distro.
3350
3351           "ttylinux"
3352               ttylinux.
3353
3354           "ubuntu"
3355               Ubuntu.
3356
3357           "unknown"
3358               The distro could not be determined.
3359
3360           "voidlinux"
3361               Void Linux.
3362
3363           "windows"
3364               Windows does not have distributions.  This string is returned
3365               if the OS type is Windows.
3366
3367           Future versions of libguestfs may return other strings here.  The
3368           caller should be prepared to handle any string.
3369
3370           Please read "INSPECTION" in guestfs(3) for more details.
3371
3372       %drives = $g->inspect_get_drive_mappings ($root);
3373           This call is useful for Windows which uses a primitive system of
3374           assigning drive letters (like C:\) to partitions.  This inspection
3375           API examines the Windows Registry to find out how disks/partitions
3376           are mapped to drive letters, and returns a hash table as in the
3377           example below:
3378
3379            C      =>     /dev/vda2
3380            E      =>     /dev/vdb1
3381            F      =>     /dev/vdc1
3382
3383           Note that keys are drive letters.  For Windows, the key is case
3384           insensitive and just contains the drive letter, without the
3385           customary colon separator character.
3386
3387           In future we may support other operating systems that also used
3388           drive letters, but the keys for those might not be case insensitive
3389           and might be longer than 1 character.  For example in OS-9, hard
3390           drives were named "h0", "h1" etc.
3391
3392           For Windows guests, currently only hard drive mappings are
3393           returned.  Removable disks (eg. DVD-ROMs) are ignored.
3394
3395           For guests that do not use drive mappings, or if the drive mappings
3396           could not be determined, this returns an empty hash table.
3397
3398           Please read "INSPECTION" in guestfs(3) for more details.  See also
3399           "$g->inspect_get_mountpoints", "$g->inspect_get_filesystems".
3400
3401       @filesystems = $g->inspect_get_filesystems ($root);
3402           This returns a list of all the filesystems that we think are
3403           associated with this operating system.  This includes the root
3404           filesystem, other ordinary filesystems, and non-mounted devices
3405           like swap partitions.
3406
3407           In the case of a multi-boot virtual machine, it is possible for a
3408           filesystem to be shared between operating systems.
3409
3410           Please read "INSPECTION" in guestfs(3) for more details.  See also
3411           "$g->inspect_get_mountpoints".
3412
3413       $format = $g->inspect_get_format ($root);
3414           Before libguestfs 1.38, there was some unreliable support for
3415           detecting installer CDs.  This API would return:
3416
3417           "installed"
3418               This is an installed operating system.
3419
3420           "installer"
3421               The disk image being inspected is not an installed operating
3422               system, but a bootable install disk, live CD, or similar.
3423
3424           "unknown"
3425               The format of this disk image is not known.
3426
3427           In libguestfs ≥ 1.38, this only returns "installed".  Use libosinfo
3428           directly to detect installer CDs.
3429
3430           Please read "INSPECTION" in guestfs(3) for more details.
3431
3432           This function is deprecated.  There is no replacement.  Consult the
3433           API documentation in guestfs(3) for further information.
3434
3435           Deprecated functions will not be removed from the API, but the fact
3436           that they are deprecated indicates that there are problems with
3437           correct use of these functions.
3438
3439       $hostname = $g->inspect_get_hostname ($root);
3440           This function returns the hostname of the operating system as found
3441           by inspection of the guest’s configuration files.
3442
3443           If the hostname could not be determined, then the string "unknown"
3444           is returned.
3445
3446           Please read "INSPECTION" in guestfs(3) for more details.
3447
3448       $icon = $g->inspect_get_icon ($root [, favicon => $favicon] [,
3449       highquality => $highquality]);
3450           This function returns an icon corresponding to the inspected
3451           operating system.  The icon is returned as a buffer containing a
3452           PNG image (re-encoded to PNG if necessary).
3453
3454           If it was not possible to get an icon this function returns a zero-
3455           length (non-NULL) buffer.  Callers must check for this case.
3456
3457           Libguestfs will start by looking for a file called /etc/favicon.png
3458           or C:\etc\favicon.png and if it has the correct format, the
3459           contents of this file will be returned.  You can disable favicons
3460           by passing the optional "favicon" boolean as false (default is
3461           true).
3462
3463           If finding the favicon fails, then we look in other places in the
3464           guest for a suitable icon.
3465
3466           If the optional "highquality" boolean is true then only high
3467           quality icons are returned, which means only icons of high
3468           resolution with an alpha channel.  The default (false) is to return
3469           any icon we can, even if it is of substandard quality.
3470
3471           Notes:
3472
3473           •   Unlike most other inspection API calls, the guest’s disks must
3474               be mounted up before you call this, since it needs to read
3475               information from the guest filesystem during the call.
3476
3477Security: The icon data comes from the untrusted guest, and
3478               should be treated with caution.  PNG files have been known to
3479               contain exploits.  Ensure that libpng (or other relevant
3480               libraries) are fully up to date before trying to process or
3481               display the icon.
3482
3483           •   The PNG image returned can be any size.  It might not be
3484               square.  Libguestfs tries to return the largest, highest
3485               quality icon available.  The application must scale the icon to
3486               the required size.
3487
3488           •   Extracting icons from Windows guests requires the external
3489               wrestool(1) program from the "icoutils" package, and several
3490               programs (bmptopnm(1), pnmtopng(1), pamcut(1)) from the
3491               "netpbm" package.  These must be installed separately.
3492
3493           •   Operating system icons are usually trademarks.  Seek legal
3494               advice before using trademarks in applications.
3495
3496       $major = $g->inspect_get_major_version ($root);
3497           This returns the major version number of the inspected operating
3498           system.
3499
3500           Windows uses a consistent versioning scheme which is not reflected
3501           in the popular public names used by the operating system.  Notably
3502           the operating system known as "Windows 7" is really version 6.1
3503           (ie. major = 6, minor = 1).  You can find out the real versions
3504           corresponding to releases of Windows by consulting Wikipedia or
3505           MSDN.
3506
3507           If the version could not be determined, then 0 is returned.
3508
3509           Please read "INSPECTION" in guestfs(3) for more details.
3510
3511       $minor = $g->inspect_get_minor_version ($root);
3512           This returns the minor version number of the inspected operating
3513           system.
3514
3515           If the version could not be determined, then 0 is returned.
3516
3517           Please read "INSPECTION" in guestfs(3) for more details.  See also
3518           "$g->inspect_get_major_version".
3519
3520       %mountpoints = $g->inspect_get_mountpoints ($root);
3521           This returns a hash of where we think the filesystems associated
3522           with this operating system should be mounted.  Callers should note
3523           that this is at best an educated guess made by reading
3524           configuration files such as /etc/fstab.  In particular note that
3525           this may return filesystems which are non-existent or not mountable
3526           and callers should be prepared to handle or ignore failures if they
3527           try to mount them.
3528
3529           Each element in the returned hashtable has a key which is the path
3530           of the mountpoint (eg. /boot) and a value which is the filesystem
3531           that would be mounted there (eg. /dev/sda1).
3532
3533           Non-mounted devices such as swap devices are not returned in this
3534           list.
3535
3536           For operating systems like Windows which still use drive letters,
3537           this call will only return an entry for the first drive "mounted
3538           on" /.  For information about the mapping of drive letters to
3539           partitions, see "$g->inspect_get_drive_mappings".
3540
3541           Please read "INSPECTION" in guestfs(3) for more details.  See also
3542           "$g->inspect_get_filesystems".
3543
3544       $id = $g->inspect_get_osinfo ($root);
3545           This function returns a possible short ID for libosinfo
3546           corresponding to the guest.
3547
3548           Note: The returned ID is only a guess by libguestfs, and nothing
3549           ensures that it actually exists in osinfo-db.
3550
3551           If no ID could not be determined, then the string "unknown" is
3552           returned.
3553
3554       $packageformat = $g->inspect_get_package_format ($root);
3555           This function and "$g->inspect_get_package_management" return the
3556           package format and package management tool used by the inspected
3557           operating system.  For example for Fedora these functions would
3558           return "rpm" (package format), and "yum" or "dnf" (package
3559           management).
3560
3561           This returns the string "unknown" if we could not determine the
3562           package format or if the operating system does not have a real
3563           packaging system (eg. Windows).
3564
3565           Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
3566           "pkgsrc", "apk", "xbps".  Future versions of libguestfs may return
3567           other strings.
3568
3569           Please read "INSPECTION" in guestfs(3) for more details.
3570
3571       $packagemanagement = $g->inspect_get_package_management ($root);
3572           "$g->inspect_get_package_format" and this function return the
3573           package format and package management tool used by the inspected
3574           operating system.  For example for Fedora these functions would
3575           return "rpm" (package format), and "yum" or "dnf" (package
3576           management).
3577
3578           This returns the string "unknown" if we could not determine the
3579           package management tool or if the operating system does not have a
3580           real packaging system (eg. Windows).
3581
3582           Possible strings include: "yum", "dnf", "up2date", "apt" (for all
3583           Debian derivatives), "portage", "pisi", "pacman", "urpmi",
3584           "zypper", "apk", "xbps".  Future versions of libguestfs may return
3585           other strings.
3586
3587           Please read "INSPECTION" in guestfs(3) for more details.
3588
3589       $product = $g->inspect_get_product_name ($root);
3590           This returns the product name of the inspected operating system.
3591           The product name is generally some freeform string which can be
3592           displayed to the user, but should not be parsed by programs.
3593
3594           If the product name could not be determined, then the string
3595           "unknown" is returned.
3596
3597           Please read "INSPECTION" in guestfs(3) for more details.
3598
3599       $variant = $g->inspect_get_product_variant ($root);
3600           This returns the product variant of the inspected operating system.
3601
3602           For Windows guests, this returns the contents of the Registry key
3603           "HKLM\Software\Microsoft\Windows NT\CurrentVersion"
3604           "InstallationType" which is usually a string such as "Client" or
3605           "Server" (other values are possible).  This can be used to
3606           distinguish consumer and enterprise versions of Windows that have
3607           the same version number (for example, Windows 7 and Windows 2008
3608           Server are both version 6.1, but the former is "Client" and the
3609           latter is "Server").
3610
3611           For enterprise Linux guests, in future we intend this to return the
3612           product variant such as "Desktop", "Server" and so on.  But this is
3613           not implemented at present.
3614
3615           If the product variant could not be determined, then the string
3616           "unknown" is returned.
3617
3618           Please read "INSPECTION" in guestfs(3) for more details.  See also
3619           "$g->inspect_get_product_name", "$g->inspect_get_major_version".
3620
3621       @roots = $g->inspect_get_roots ();
3622           This function is a convenient way to get the list of root devices,
3623           as returned from a previous call to "$g->inspect_os", but without
3624           redoing the whole inspection process.
3625
3626           This returns an empty list if either no root devices were found or
3627           the caller has not called "$g->inspect_os".
3628
3629           Please read "INSPECTION" in guestfs(3) for more details.
3630
3631       $name = $g->inspect_get_type ($root);
3632           This returns the type of the inspected operating system.  Currently
3633           defined types are:
3634
3635           "linux"
3636               Any Linux-based operating system.
3637
3638           "windows"
3639               Any Microsoft Windows operating system.
3640
3641           "freebsd"
3642               FreeBSD.
3643
3644           "netbsd"
3645               NetBSD.
3646
3647           "openbsd"
3648               OpenBSD.
3649
3650           "hurd"
3651               GNU/Hurd.
3652
3653           "dos"
3654               MS-DOS, FreeDOS and others.
3655
3656           "minix"
3657               MINIX.
3658
3659           "unknown"
3660               The operating system type could not be determined.
3661
3662           Future versions of libguestfs may return other strings here.  The
3663           caller should be prepared to handle any string.
3664
3665           Please read "INSPECTION" in guestfs(3) for more details.
3666
3667       $controlset = $g->inspect_get_windows_current_control_set ($root);
3668           This returns the Windows CurrentControlSet of the inspected guest.
3669           The CurrentControlSet is a registry key name such as
3670           "ControlSet001".
3671
3672           This call assumes that the guest is Windows and that the Registry
3673           could be examined by inspection.  If this is not the case then an
3674           error is returned.
3675
3676           Please read "INSPECTION" in guestfs(3) for more details.
3677
3678       $path = $g->inspect_get_windows_software_hive ($root);
3679           This returns the path to the hive (binary Windows Registry file)
3680           corresponding to HKLM\SOFTWARE.
3681
3682           This call assumes that the guest is Windows and that the guest has
3683           a software hive file with the right name.  If this is not the case
3684           then an error is returned.  This call does not check that the hive
3685           is a valid Windows Registry hive.
3686
3687           You can use "$g->hivex_open" to read or write to the hive.
3688
3689           Please read "INSPECTION" in guestfs(3) for more details.
3690
3691       $path = $g->inspect_get_windows_system_hive ($root);
3692           This returns the path to the hive (binary Windows Registry file)
3693           corresponding to HKLM\SYSTEM.
3694
3695           This call assumes that the guest is Windows and that the guest has
3696           a system hive file with the right name.  If this is not the case
3697           then an error is returned.  This call does not check that the hive
3698           is a valid Windows Registry hive.
3699
3700           You can use "$g->hivex_open" to read or write to the hive.
3701
3702           Please read "INSPECTION" in guestfs(3) for more details.
3703
3704       $systemroot = $g->inspect_get_windows_systemroot ($root);
3705           This returns the Windows systemroot of the inspected guest.  The
3706           systemroot is a directory path such as /WINDOWS.
3707
3708           This call assumes that the guest is Windows and that the systemroot
3709           could be determined by inspection.  If this is not the case then an
3710           error is returned.
3711
3712           Please read "INSPECTION" in guestfs(3) for more details.
3713
3714       $live = $g->inspect_is_live ($root);
3715           This is deprecated and always returns "false".
3716
3717           Please read "INSPECTION" in guestfs(3) for more details.
3718
3719           This function is deprecated.  There is no replacement.  Consult the
3720           API documentation in guestfs(3) for further information.
3721
3722           Deprecated functions will not be removed from the API, but the fact
3723           that they are deprecated indicates that there are problems with
3724           correct use of these functions.
3725
3726       $multipart = $g->inspect_is_multipart ($root);
3727           This is deprecated and always returns "false".
3728
3729           Please read "INSPECTION" in guestfs(3) for more details.
3730
3731           This function is deprecated.  There is no replacement.  Consult the
3732           API documentation in guestfs(3) for further information.
3733
3734           Deprecated functions will not be removed from the API, but the fact
3735           that they are deprecated indicates that there are problems with
3736           correct use of these functions.
3737
3738       $netinst = $g->inspect_is_netinst ($root);
3739           This is deprecated and always returns "false".
3740
3741           Please read "INSPECTION" in guestfs(3) for more details.
3742
3743           This function is deprecated.  There is no replacement.  Consult the
3744           API documentation in guestfs(3) for further information.
3745
3746           Deprecated functions will not be removed from the API, but the fact
3747           that they are deprecated indicates that there are problems with
3748           correct use of these functions.
3749
3750       @applications = $g->inspect_list_applications ($root);
3751           Return the list of applications installed in the operating system.
3752
3753           Note: This call works differently from other parts of the
3754           inspection API.  You have to call "$g->inspect_os", then
3755           "$g->inspect_get_mountpoints", then mount up the disks, before
3756           calling this.  Listing applications is a significantly more
3757           difficult operation which requires access to the full filesystem.
3758           Also note that unlike the other "$g->inspect_get_*" calls which are
3759           just returning data cached in the libguestfs handle, this call
3760           actually reads parts of the mounted filesystems during the call.
3761
3762           This returns an empty list if the inspection code was not able to
3763           determine the list of applications.
3764
3765           The application structure contains the following fields:
3766
3767           "app_name"
3768               The name of the application.  For Linux guests, this is the
3769               package name.
3770
3771           "app_display_name"
3772               The display name of the application, sometimes localized to the
3773               install language of the guest operating system.
3774
3775               If unavailable this is returned as an empty string "".  Callers
3776               needing to display something can use "app_name" instead.
3777
3778           "app_epoch"
3779               For package managers which use epochs, this contains the epoch
3780               of the package (an integer).  If unavailable, this is returned
3781               as 0.
3782
3783           "app_version"
3784               The version string of the application or package.  If
3785               unavailable this is returned as an empty string "".
3786
3787           "app_release"
3788               The release string of the application or package, for package
3789               managers that use this.  If unavailable this is returned as an
3790               empty string "".
3791
3792           "app_install_path"
3793               The installation path of the application (on operating systems
3794               such as Windows which use installation paths).  This path is in
3795               the format used by the guest operating system, it is not a
3796               libguestfs path.
3797
3798               If unavailable this is returned as an empty string "".
3799
3800           "app_trans_path"
3801               The install path translated into a libguestfs path.  If
3802               unavailable this is returned as an empty string "".
3803
3804           "app_publisher"
3805               The name of the publisher of the application, for package
3806               managers that use this.  If unavailable this is returned as an
3807               empty string "".
3808
3809           "app_url"
3810               The URL (eg. upstream URL) of the application.  If unavailable
3811               this is returned as an empty string "".
3812
3813           "app_source_package"
3814               For packaging systems which support this, the name of the
3815               source package.  If unavailable this is returned as an empty
3816               string "".
3817
3818           "app_summary"
3819               A short (usually one line) description of the application or
3820               package.  If unavailable this is returned as an empty string
3821               "".
3822
3823           "app_description"
3824               A longer description of the application or package.  If
3825               unavailable this is returned as an empty string "".
3826
3827           Please read "INSPECTION" in guestfs(3) for more details.
3828
3829           This function is deprecated.  In new code, use the
3830           "inspect_list_applications2" call instead.
3831
3832           Deprecated functions will not be removed from the API, but the fact
3833           that they are deprecated indicates that there are problems with
3834           correct use of these functions.
3835
3836       @applications2 = $g->inspect_list_applications2 ($root);
3837           Return the list of applications installed in the operating system.
3838
3839           Note: This call works differently from other parts of the
3840           inspection API.  You have to call "$g->inspect_os", then
3841           "$g->inspect_get_mountpoints", then mount up the disks, before
3842           calling this.  Listing applications is a significantly more
3843           difficult operation which requires access to the full filesystem.
3844           Also note that unlike the other "$g->inspect_get_*" calls which are
3845           just returning data cached in the libguestfs handle, this call
3846           actually reads parts of the mounted filesystems during the call.
3847
3848           This returns an empty list if the inspection code was not able to
3849           determine the list of applications.
3850
3851           The application structure contains the following fields:
3852
3853           "app2_name"
3854               The name of the application.  For Linux guests, this is the
3855               package name.
3856
3857           "app2_display_name"
3858               The display name of the application, sometimes localized to the
3859               install language of the guest operating system.
3860
3861               If unavailable this is returned as an empty string "".  Callers
3862               needing to display something can use "app2_name" instead.
3863
3864           "app2_epoch"
3865               For package managers which use epochs, this contains the epoch
3866               of the package (an integer).  If unavailable, this is returned
3867               as 0.
3868
3869           "app2_version"
3870               The version string of the application or package.  If
3871               unavailable this is returned as an empty string "".
3872
3873           "app2_release"
3874               The release string of the application or package, for package
3875               managers that use this.  If unavailable this is returned as an
3876               empty string "".
3877
3878           "app2_arch"
3879               The architecture string of the application or package, for
3880               package managers that use this.  If unavailable this is
3881               returned as an empty string "".
3882
3883           "app2_install_path"
3884               The installation path of the application (on operating systems
3885               such as Windows which use installation paths).  This path is in
3886               the format used by the guest operating system, it is not a
3887               libguestfs path.
3888
3889               If unavailable this is returned as an empty string "".
3890
3891           "app2_trans_path"
3892               The install path translated into a libguestfs path.  If
3893               unavailable this is returned as an empty string "".
3894
3895           "app2_publisher"
3896               The name of the publisher of the application, for package
3897               managers that use this.  If unavailable this is returned as an
3898               empty string "".
3899
3900           "app2_url"
3901               The URL (eg. upstream URL) of the application.  If unavailable
3902               this is returned as an empty string "".
3903
3904           "app2_source_package"
3905               For packaging systems which support this, the name of the
3906               source package.  If unavailable this is returned as an empty
3907               string "".
3908
3909           "app2_summary"
3910               A short (usually one line) description of the application or
3911               package.  If unavailable this is returned as an empty string
3912               "".
3913
3914           "app2_description"
3915               A longer description of the application or package.  If
3916               unavailable this is returned as an empty string "".
3917
3918           Please read "INSPECTION" in guestfs(3) for more details.
3919
3920       @roots = $g->inspect_os ();
3921           This function uses other libguestfs functions and certain
3922           heuristics to inspect the disk(s) (usually disks belonging to a
3923           virtual machine), looking for operating systems.
3924
3925           The list returned is empty if no operating systems were found.
3926
3927           If one operating system was found, then this returns a list with a
3928           single element, which is the name of the root filesystem of this
3929           operating system.  It is also possible for this function to return
3930           a list containing more than one element, indicating a dual-boot or
3931           multi-boot virtual machine, with each element being the root
3932           filesystem of one of the operating systems.
3933
3934           You can pass the root string(s) returned to other
3935           "$g->inspect_get_*" functions in order to query further information
3936           about each operating system, such as the name and version.
3937
3938           This function uses other libguestfs features such as "$g->mount_ro"
3939           and "$g->umount_all" in order to mount and unmount filesystems and
3940           look at the contents.  This should be called with no disks
3941           currently mounted.  The function may also use Augeas, so any
3942           existing Augeas handle will be closed.
3943
3944           This function cannot decrypt encrypted disks.  The caller must do
3945           that first (supplying the necessary keys) if the disk is encrypted.
3946
3947           Please read "INSPECTION" in guestfs(3) for more details.
3948
3949           See also "$g->list_filesystems".
3950
3951       $flag = $g->is_blockdev ($path [, followsymlinks => $followsymlinks]);
3952           This returns "true" if and only if there is a block device with the
3953           given "path" name.
3954
3955           If the optional flag "followsymlinks" is true, then a symlink (or
3956           chain of symlinks) that ends with a block device also causes the
3957           function to return true.
3958
3959           This call only looks at files within the guest filesystem.
3960           Libguestfs partitions and block devices (eg. /dev/sda) cannot be
3961           used as the "path" parameter of this call.
3962
3963           See also "$g->stat".
3964
3965       $flag = $g->is_blockdev_opts ($path [, followsymlinks =>
3966       $followsymlinks]);
3967           This is an alias of "is_blockdev".
3968
3969       $busy = $g->is_busy ();
3970           This always returns false.  This function is deprecated with no
3971           replacement.  Do not use this function.
3972
3973           For more information on states, see guestfs(3).
3974
3975       $flag = $g->is_chardev ($path [, followsymlinks => $followsymlinks]);
3976           This returns "true" if and only if there is a character device with
3977           the given "path" name.
3978
3979           If the optional flag "followsymlinks" is true, then a symlink (or
3980           chain of symlinks) that ends with a chardev also causes the
3981           function to return true.
3982
3983           See also "$g->stat".
3984
3985       $flag = $g->is_chardev_opts ($path [, followsymlinks =>
3986       $followsymlinks]);
3987           This is an alias of "is_chardev".
3988
3989       $config = $g->is_config ();
3990           This returns true iff this handle is being configured (in the
3991           "CONFIG" state).
3992
3993           For more information on states, see guestfs(3).
3994
3995       $dirflag = $g->is_dir ($path [, followsymlinks => $followsymlinks]);
3996           This returns "true" if and only if there is a directory with the
3997           given "path" name.  Note that it returns false for other objects
3998           like files.
3999
4000           If the optional flag "followsymlinks" is true, then a symlink (or
4001           chain of symlinks) that ends with a directory also causes the
4002           function to return true.
4003
4004           See also "$g->stat".
4005
4006       $dirflag = $g->is_dir_opts ($path [, followsymlinks =>
4007       $followsymlinks]);
4008           This is an alias of "is_dir".
4009
4010       $flag = $g->is_fifo ($path [, followsymlinks => $followsymlinks]);
4011           This returns "true" if and only if there is a FIFO (named pipe)
4012           with the given "path" name.
4013
4014           If the optional flag "followsymlinks" is true, then a symlink (or
4015           chain of symlinks) that ends with a FIFO also causes the function
4016           to return true.
4017
4018           See also "$g->stat".
4019
4020       $flag = $g->is_fifo_opts ($path [, followsymlinks => $followsymlinks]);
4021           This is an alias of "is_fifo".
4022
4023       $fileflag = $g->is_file ($path [, followsymlinks => $followsymlinks]);
4024           This returns "true" if and only if there is a regular file with the
4025           given "path" name.  Note that it returns false for other objects
4026           like directories.
4027
4028           If the optional flag "followsymlinks" is true, then a symlink (or
4029           chain of symlinks) that ends with a file also causes the function
4030           to return true.
4031
4032           See also "$g->stat".
4033
4034       $fileflag = $g->is_file_opts ($path [, followsymlinks =>
4035       $followsymlinks]);
4036           This is an alias of "is_file".
4037
4038       $launching = $g->is_launching ();
4039           This returns true iff this handle is launching the subprocess (in
4040           the "LAUNCHING" state).
4041
4042           For more information on states, see guestfs(3).
4043
4044       $lvflag = $g->is_lv ($mountable);
4045           This command tests whether "mountable" is a logical volume, and
4046           returns true iff this is the case.
4047
4048       $ready = $g->is_ready ();
4049           This returns true iff this handle is ready to accept commands (in
4050           the "READY" state).
4051
4052           For more information on states, see guestfs(3).
4053
4054       $flag = $g->is_socket ($path [, followsymlinks => $followsymlinks]);
4055           This returns "true" if and only if there is a Unix domain socket
4056           with the given "path" name.
4057
4058           If the optional flag "followsymlinks" is true, then a symlink (or
4059           chain of symlinks) that ends with a socket also causes the function
4060           to return true.
4061
4062           See also "$g->stat".
4063
4064       $flag = $g->is_socket_opts ($path [, followsymlinks =>
4065       $followsymlinks]);
4066           This is an alias of "is_socket".
4067
4068       $flag = $g->is_symlink ($path);
4069           This returns "true" if and only if there is a symbolic link with
4070           the given "path" name.
4071
4072           See also "$g->stat".
4073
4074       $flag = $g->is_whole_device ($device);
4075           This returns "true" if and only if "device" refers to a whole block
4076           device. That is, not a partition or a logical device.
4077
4078       $zeroflag = $g->is_zero ($path);
4079           This returns true iff the file exists and the file is empty or it
4080           contains all zero bytes.
4081
4082       $zeroflag = $g->is_zero_device ($device);
4083           This returns true iff the device exists and contains all zero
4084           bytes.
4085
4086           Note that for large devices this can take a long time to run.
4087
4088       %isodata = $g->isoinfo ($isofile);
4089           This is the same as "$g->isoinfo_device" except that it works for
4090           an ISO file located inside some other mounted filesystem.  Note
4091           that in the common case where you have added an ISO file as a
4092           libguestfs device, you would not call this.  Instead you would call
4093           "$g->isoinfo_device".
4094
4095       %isodata = $g->isoinfo_device ($device);
4096           "device" is an ISO device.  This returns a struct of information
4097           read from the primary volume descriptor (the ISO equivalent of the
4098           superblock) of the device.
4099
4100           Usually it is more efficient to use the isoinfo(1) command with the
4101           -d option on the host to analyze ISO files, instead of going
4102           through libguestfs.
4103
4104           For information on the primary volume descriptor fields, see
4105           <https://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor>
4106
4107       $g->journal_close ();
4108           Close the journal handle.
4109
4110           This function depends on the feature "journal".  See also
4111           "$g->feature-available".
4112
4113       @fields = $g->journal_get ();
4114           Read the current journal entry.  This returns all the fields in the
4115           journal as a set of "(attrname, attrval)" pairs.  The "attrname" is
4116           the field name (a string).
4117
4118           The "attrval" is the field value (a binary blob, often but not
4119           always a string).  Please note that "attrval" is a byte array, not
4120           a \0-terminated C string.
4121
4122           The length of data may be truncated to the data threshold (see:
4123           "$g->journal_set_data_threshold",
4124           "$g->journal_get_data_threshold").
4125
4126           If you set the data threshold to unlimited (0) then this call can
4127           read a journal entry of any size, ie. it is not limited by the
4128           libguestfs protocol.
4129
4130           This function depends on the feature "journal".  See also
4131           "$g->feature-available".
4132
4133       $threshold = $g->journal_get_data_threshold ();
4134           Get the current data threshold for reading journal entries.  This
4135           is a hint to the journal that it may truncate data fields to this
4136           size when reading them (note also that it may not truncate them).
4137           If this returns 0, then the threshold is unlimited.
4138
4139           See also "$g->journal_set_data_threshold".
4140
4141           This function depends on the feature "journal".  See also
4142           "$g->feature-available".
4143
4144       $usec = $g->journal_get_realtime_usec ();
4145           Get the realtime (wallclock) timestamp of the current journal
4146           entry.
4147
4148           This function depends on the feature "journal".  See also
4149           "$g->feature-available".
4150
4151       $more = $g->journal_next ();
4152           Move to the next journal entry.  You have to call this at least
4153           once after opening the handle before you are able to read data.
4154
4155           The returned boolean tells you if there are any more journal
4156           records to read.  "true" means you can read the next record (eg.
4157           using "$g->journal_get"), and "false" means you have reached the
4158           end of the journal.
4159
4160           This function depends on the feature "journal".  See also
4161           "$g->feature-available".
4162
4163       $g->journal_open ($directory);
4164           Open the systemd journal located in directory.  Any previously
4165           opened journal handle is closed.
4166
4167           The contents of the journal can be read using "$g->journal_next"
4168           and "$g->journal_get".
4169
4170           After you have finished using the journal, you should close the
4171           handle by calling "$g->journal_close".
4172
4173           This function depends on the feature "journal".  See also
4174           "$g->feature-available".
4175
4176       $g->journal_set_data_threshold ($threshold);
4177           Set the data threshold for reading journal entries.  This is a hint
4178           to the journal that it may truncate data fields to this size when
4179           reading them (note also that it may not truncate them).  If you set
4180           this to 0, then the threshold is unlimited.
4181
4182           See also "$g->journal_get_data_threshold".
4183
4184           This function depends on the feature "journal".  See also
4185           "$g->feature-available".
4186
4187       $rskip = $g->journal_skip ($skip);
4188           Skip forwards ("skip ≥ 0") or backwards ("skip < 0") in the
4189           journal.
4190
4191           The number of entries actually skipped is returned (note
4192           "rskip ≥ 0").  If this is not the same as the absolute value of the
4193           skip parameter ("|skip|") you passed in then it means you have
4194           reached the end or the start of the journal.
4195
4196           This function depends on the feature "journal".  See also
4197           "$g->feature-available".
4198
4199       $g->kill_subprocess ();
4200           This kills the hypervisor.
4201
4202           Do not call this.  See: "$g->shutdown" instead.
4203
4204           This function is deprecated.  In new code, use the "shutdown" call
4205           instead.
4206
4207           Deprecated functions will not be removed from the API, but the fact
4208           that they are deprecated indicates that there are problems with
4209           correct use of these functions.
4210
4211       $g->launch ();
4212           You should call this after configuring the handle (eg. adding
4213           drives) but before performing any actions.
4214
4215           Do not call "$g->launch" twice on the same handle.  Although it
4216           will not give an error (for historical reasons), the precise
4217           behaviour when you do this is not well defined.  Handles are very
4218           cheap to create, so create a new one for each launch.
4219
4220       $g->lchown ($owner, $group, $path);
4221           Change the file owner to "owner" and group to "group".  This is
4222           like "$g->chown" but if "path" is a symlink then the link itself is
4223           changed, not the target.
4224
4225           Only numeric uid and gid are supported.  If you want to use names,
4226           you will need to locate and parse the password file yourself
4227           (Augeas support makes this relatively easy).
4228
4229       $g->ldmtool_create_all ();
4230           This function scans all block devices looking for Windows dynamic
4231           disk volumes and partitions, and creates devices for any that were
4232           found.
4233
4234           Call "$g->list_ldm_volumes" and "$g->list_ldm_partitions" to return
4235           all devices.
4236
4237           Note that you don't normally need to call this explicitly, since it
4238           is done automatically at "$g->launch" time.
4239
4240           This function depends on the feature "ldm".  See also
4241           "$g->feature-available".
4242
4243       @disks = $g->ldmtool_diskgroup_disks ($diskgroup);
4244           Return the disks in a Windows dynamic disk group.  The "diskgroup"
4245           parameter should be the GUID of a disk group, one element from the
4246           list returned by "$g->ldmtool_scan".
4247
4248           This function depends on the feature "ldm".  See also
4249           "$g->feature-available".
4250
4251       $name = $g->ldmtool_diskgroup_name ($diskgroup);
4252           Return the name of a Windows dynamic disk group.  The "diskgroup"
4253           parameter should be the GUID of a disk group, one element from the
4254           list returned by "$g->ldmtool_scan".
4255
4256           This function depends on the feature "ldm".  See also
4257           "$g->feature-available".
4258
4259       @volumes = $g->ldmtool_diskgroup_volumes ($diskgroup);
4260           Return the volumes in a Windows dynamic disk group.  The
4261           "diskgroup" parameter should be the GUID of a disk group, one
4262           element from the list returned by "$g->ldmtool_scan".
4263
4264           This function depends on the feature "ldm".  See also
4265           "$g->feature-available".
4266
4267       $g->ldmtool_remove_all ();
4268           This is essentially the opposite of "$g->ldmtool_create_all".  It
4269           removes the device mapper mappings for all Windows dynamic disk
4270           volumes
4271
4272           This function depends on the feature "ldm".  See also
4273           "$g->feature-available".
4274
4275       @guids = $g->ldmtool_scan ();
4276           This function scans for Windows dynamic disks.  It returns a list
4277           of identifiers (GUIDs) for all disk groups that were found.  These
4278           identifiers can be passed to other "$g->ldmtool_*" functions.
4279
4280           This function scans all block devices.  To scan a subset of block
4281           devices, call "$g->ldmtool_scan_devices" instead.
4282
4283           This function depends on the feature "ldm".  See also
4284           "$g->feature-available".
4285
4286       @guids = $g->ldmtool_scan_devices (\@devices);
4287           This function scans for Windows dynamic disks.  It returns a list
4288           of identifiers (GUIDs) for all disk groups that were found.  These
4289           identifiers can be passed to other "$g->ldmtool_*" functions.
4290
4291           The parameter "devices" is a list of block devices which are
4292           scanned.  If this list is empty, all block devices are scanned.
4293
4294           This function depends on the feature "ldm".  See also
4295           "$g->feature-available".
4296
4297       $hint = $g->ldmtool_volume_hint ($diskgroup, $volume);
4298           Return the hint field of the volume named "volume" in the disk
4299           group with GUID "diskgroup".  This may not be defined, in which
4300           case the empty string is returned.  The hint field is often, though
4301           not always, the name of a Windows drive, eg. "E:".
4302
4303           This function depends on the feature "ldm".  See also
4304           "$g->feature-available".
4305
4306       @partitions = $g->ldmtool_volume_partitions ($diskgroup, $volume);
4307           Return the list of partitions in the volume named "volume" in the
4308           disk group with GUID "diskgroup".
4309
4310           This function depends on the feature "ldm".  See also
4311           "$g->feature-available".
4312
4313       $voltype = $g->ldmtool_volume_type ($diskgroup, $volume);
4314           Return the type of the volume named "volume" in the disk group with
4315           GUID "diskgroup".
4316
4317           Possible volume types that can be returned here include: "simple",
4318           "spanned", "striped", "mirrored", "raid5".  Other types may also be
4319           returned.
4320
4321           This function depends on the feature "ldm".  See also
4322           "$g->feature-available".
4323
4324       $xattr = $g->lgetxattr ($path, $name);
4325           Get a single extended attribute from file "path" named "name".  If
4326           "path" is a symlink, then this call returns an extended attribute
4327           from the symlink.
4328
4329           Normally it is better to get all extended attributes from a file in
4330           one go by calling "$g->getxattrs".  However some Linux filesystem
4331           implementations are buggy and do not provide a way to list out
4332           attributes.  For these filesystems (notably ntfs-3g) you have to
4333           know the names of the extended attributes you want in advance and
4334           call this function.
4335
4336           Extended attribute values are blobs of binary data.  If there is no
4337           extended attribute named "name", this returns an error.
4338
4339           See also: "$g->lgetxattrs", "$g->getxattr", attr(5).
4340
4341           This function depends on the feature "linuxxattrs".  See also
4342           "$g->feature-available".
4343
4344       @xattrs = $g->lgetxattrs ($path);
4345           This is the same as "$g->getxattrs", but if "path" is a symbolic
4346           link, then it returns the extended attributes of the link itself.
4347
4348           This function depends on the feature "linuxxattrs".  See also
4349           "$g->feature-available".
4350
4351       @mounttags = $g->list_9p ();
4352           This call does nothing and returns an error.
4353
4354           This function is deprecated.  There is no replacement.  Consult the
4355           API documentation in guestfs(3) for further information.
4356
4357           Deprecated functions will not be removed from the API, but the fact
4358           that they are deprecated indicates that there are problems with
4359           correct use of these functions.
4360
4361       @devices = $g->list_devices ();
4362           List all the block devices.
4363
4364           The full block device names are returned, eg. /dev/sda.
4365
4366           See also "$g->list_filesystems".
4367
4368       %labels = $g->list_disk_labels ();
4369           If you add drives using the optional "label" parameter of
4370           "$g->add_drive_opts", you can use this call to map between disk
4371           labels, and raw block device and partition names (like /dev/sda and
4372           /dev/sda1).
4373
4374           This returns a hashtable, where keys are the disk labels (without
4375           the /dev/disk/guestfs prefix), and the values are the full raw
4376           block device and partition names (eg. /dev/sda and /dev/sda1).
4377
4378       @devices = $g->list_dm_devices ();
4379           List all device mapper devices.
4380
4381           The returned list contains /dev/mapper/* devices, eg. ones created
4382           by a previous call to "$g->luks_open".
4383
4384           Device mapper devices which correspond to logical volumes are not
4385           returned in this list.  Call "$g->lvs" if you want to list logical
4386           volumes.
4387
4388       %fses = $g->list_filesystems ();
4389           This inspection command looks for filesystems on partitions, block
4390           devices and logical volumes, returning a list of "mountables"
4391           containing filesystems and their type.
4392
4393           The return value is a hash, where the keys are the devices
4394           containing filesystems, and the values are the filesystem types.
4395           For example:
4396
4397            "/dev/sda1" => "ntfs"
4398            "/dev/sda2" => "ext2"
4399            "/dev/vg_guest/lv_root" => "ext4"
4400            "/dev/vg_guest/lv_swap" => "swap"
4401
4402           The key is not necessarily a block device. It may also be an opaque
4403           ‘mountable’ string which can be passed to "$g->mount".
4404
4405           The value can have the special value "unknown", meaning the content
4406           of the device is undetermined or empty.  "swap" means a Linux swap
4407           partition.
4408
4409           In libguestfs ≤ 1.36 this command ran other libguestfs commands,
4410           which might have included "$g->mount" and "$g->umount", and
4411           therefore you had to use this soon after launch and only when
4412           nothing else was mounted.  This restriction is removed in
4413           libguestfs ≥ 1.38.
4414
4415           Not all of the filesystems returned will be mountable.  In
4416           particular, swap partitions are returned in the list.  Also this
4417           command does not check that each filesystem found is valid and
4418           mountable, and some filesystems might be mountable but require
4419           special options.  Filesystems may not all belong to a single
4420           logical operating system (use "$g->inspect_os" to look for OSes).
4421
4422       @devices = $g->list_ldm_partitions ();
4423           This function returns all Windows dynamic disk partitions that were
4424           found at launch time.  It returns a list of device names.
4425
4426           This function depends on the feature "ldm".  See also
4427           "$g->feature-available".
4428
4429       @devices = $g->list_ldm_volumes ();
4430           This function returns all Windows dynamic disk volumes that were
4431           found at launch time.  It returns a list of device names.
4432
4433           This function depends on the feature "ldm".  See also
4434           "$g->feature-available".
4435
4436       @devices = $g->list_md_devices ();
4437           List all Linux md devices.
4438
4439       @partitions = $g->list_partitions ();
4440           List all the partitions detected on all block devices.
4441
4442           The full partition device names are returned, eg. /dev/sda1
4443
4444           This does not return logical volumes.  For that you will need to
4445           call "$g->lvs".
4446
4447           See also "$g->list_filesystems".
4448
4449       $listing = $g->ll ($directory);
4450           List the files in directory (relative to the root directory, there
4451           is no cwd) in the format of "ls -la".
4452
4453           This command is mostly useful for interactive sessions.  It is not
4454           intended that you try to parse the output string.
4455
4456       $listing = $g->llz ($directory);
4457           List the files in directory in the format of "ls -laZ".
4458
4459           This command is mostly useful for interactive sessions.  It is not
4460           intended that you try to parse the output string.
4461
4462           This function is deprecated.  In new code, use the "lgetxattrs"
4463           call instead.
4464
4465           Deprecated functions will not be removed from the API, but the fact
4466           that they are deprecated indicates that there are problems with
4467           correct use of these functions.
4468
4469       $g->ln ($target, $linkname);
4470           This command creates a hard link.
4471
4472       $g->ln_f ($target, $linkname);
4473           This command creates a hard link, removing the link "linkname" if
4474           it exists already.
4475
4476       $g->ln_s ($target, $linkname);
4477           This command creates a symbolic link using the "ln -s" command.
4478
4479       $g->ln_sf ($target, $linkname);
4480           This command creates a symbolic link using the "ln -sf" command,
4481           The -f option removes the link ("linkname") if it exists already.
4482
4483       $g->lremovexattr ($xattr, $path);
4484           This is the same as "$g->removexattr", but if "path" is a symbolic
4485           link, then it removes an extended attribute of the link itself.
4486
4487           This function depends on the feature "linuxxattrs".  See also
4488           "$g->feature-available".
4489
4490       @listing = $g->ls ($directory);
4491           List the files in directory (relative to the root directory, there
4492           is no cwd).  The "." and ".." entries are not returned, but hidden
4493           files are shown.
4494
4495       $g->ls0 ($dir, $filenames);
4496           This specialized command is used to get a listing of the filenames
4497           in the directory "dir".  The list of filenames is written to the
4498           local file filenames (on the host).
4499
4500           In the output file, the filenames are separated by "\0" characters.
4501
4502           "." and ".." are not returned.  The filenames are not sorted.
4503
4504       $g->lsetxattr ($xattr, $val, $vallen, $path);
4505           This is the same as "$g->setxattr", but if "path" is a symbolic
4506           link, then it sets an extended attribute of the link itself.
4507
4508           This function depends on the feature "linuxxattrs".  See also
4509           "$g->feature-available".
4510
4511       %statbuf = $g->lstat ($path);
4512           Returns file information for the given "path".
4513
4514           This is the same as "$g->stat" except that if "path" is a symbolic
4515           link, then the link is stat-ed, not the file it refers to.
4516
4517           This is the same as the lstat(2) system call.
4518
4519           This function is deprecated.  In new code, use the "lstatns" call
4520           instead.
4521
4522           Deprecated functions will not be removed from the API, but the fact
4523           that they are deprecated indicates that there are problems with
4524           correct use of these functions.
4525
4526       @statbufs = $g->lstatlist ($path, \@names);
4527           This call allows you to perform the "$g->lstat" operation on
4528           multiple files, where all files are in the directory "path".
4529           "names" is the list of files from this directory.
4530
4531           On return you get a list of stat structs, with a one-to-one
4532           correspondence to the "names" list.  If any name did not exist or
4533           could not be lstat'd, then the "st_ino" field of that structure is
4534           set to -1.
4535
4536           This call is intended for programs that want to efficiently list a
4537           directory contents without making many round-trips.  See also
4538           "$g->lxattrlist" for a similarly efficient call for getting
4539           extended attributes.
4540
4541           This function is deprecated.  In new code, use the "lstatnslist"
4542           call instead.
4543
4544           Deprecated functions will not be removed from the API, but the fact
4545           that they are deprecated indicates that there are problems with
4546           correct use of these functions.
4547
4548       %statbuf = $g->lstatns ($path);
4549           Returns file information for the given "path".
4550
4551           This is the same as "$g->statns" except that if "path" is a
4552           symbolic link, then the link is stat-ed, not the file it refers to.
4553
4554           This is the same as the lstat(2) system call.
4555
4556       @statbufs = $g->lstatnslist ($path, \@names);
4557           This call allows you to perform the "$g->lstatns" operation on
4558           multiple files, where all files are in the directory "path".
4559           "names" is the list of files from this directory.
4560
4561           On return you get a list of stat structs, with a one-to-one
4562           correspondence to the "names" list.  If any name did not exist or
4563           could not be lstat'd, then the "st_ino" field of that structure is
4564           set to -1.
4565
4566           This call is intended for programs that want to efficiently list a
4567           directory contents without making many round-trips.  See also
4568           "$g->lxattrlist" for a similarly efficient call for getting
4569           extended attributes.
4570
4571       $g->luks_add_key ($device, $key, $newkey, $keyslot);
4572           This command adds a new key on LUKS device "device".  "key" is any
4573           existing key, and is used to access the device.  "newkey" is the
4574           new key to add.  "keyslot" is the key slot that will be replaced.
4575
4576           Note that if "keyslot" already contains a key, then this command
4577           will fail.  You have to use "$g->luks_kill_slot" first to remove
4578           that key.
4579
4580           This function depends on the feature "luks".  See also
4581           "$g->feature-available".
4582
4583       $g->luks_close ($device);
4584           This closes a LUKS device that was created earlier by
4585           "$g->luks_open" or "$g->luks_open_ro".  The "device" parameter must
4586           be the name of the LUKS mapping device (ie. /dev/mapper/mapname)
4587           and not the name of the underlying block device.
4588
4589           This function depends on the feature "luks".  See also
4590           "$g->feature-available".
4591
4592           This function is deprecated.  In new code, use the
4593           "cryptsetup_close" call instead.
4594
4595           Deprecated functions will not be removed from the API, but the fact
4596           that they are deprecated indicates that there are problems with
4597           correct use of these functions.
4598
4599       $g->luks_format ($device, $key, $keyslot);
4600           This command erases existing data on "device" and formats the
4601           device as a LUKS encrypted device.  "key" is the initial key, which
4602           is added to key slot "keyslot".  (LUKS supports 8 key slots,
4603           numbered 0-7).
4604
4605           This function depends on the feature "luks".  See also
4606           "$g->feature-available".
4607
4608       $g->luks_format_cipher ($device, $key, $keyslot, $cipher);
4609           This command is the same as "$g->luks_format" but it also allows
4610           you to set the "cipher" used.
4611
4612           This function depends on the feature "luks".  See also
4613           "$g->feature-available".
4614
4615       $g->luks_kill_slot ($device, $key, $keyslot);
4616           This command deletes the key in key slot "keyslot" from the
4617           encrypted LUKS device "device".  "key" must be one of the other
4618           keys.
4619
4620           This function depends on the feature "luks".  See also
4621           "$g->feature-available".
4622
4623       $g->luks_open ($device, $key, $mapname);
4624           This command opens a block device which has been encrypted
4625           according to the Linux Unified Key Setup (LUKS) standard.
4626
4627           "device" is the encrypted block device or partition.
4628
4629           The caller must supply one of the keys associated with the LUKS
4630           block device, in the "key" parameter.
4631
4632           This creates a new block device called /dev/mapper/mapname.  Reads
4633           and writes to this block device are decrypted from and encrypted to
4634           the underlying "device" respectively.
4635
4636           If this block device contains LVM volume groups, then calling
4637           "$g->lvm_scan" with the "activate" parameter "true" will make them
4638           visible.
4639
4640           Use "$g->list_dm_devices" to list all device mapper devices.
4641
4642           This function depends on the feature "luks".  See also
4643           "$g->feature-available".
4644
4645           This function is deprecated.  In new code, use the
4646           "cryptsetup_open" call instead.
4647
4648           Deprecated functions will not be removed from the API, but the fact
4649           that they are deprecated indicates that there are problems with
4650           correct use of these functions.
4651
4652       $g->luks_open_ro ($device, $key, $mapname);
4653           This is the same as "$g->luks_open" except that a read-only mapping
4654           is created.
4655
4656           This function depends on the feature "luks".  See also
4657           "$g->feature-available".
4658
4659           This function is deprecated.  In new code, use the
4660           "cryptsetup_open" call instead.
4661
4662           Deprecated functions will not be removed from the API, but the fact
4663           that they are deprecated indicates that there are problems with
4664           correct use of these functions.
4665
4666       $uuid = $g->luks_uuid ($device);
4667           This returns the UUID of the LUKS device "device".
4668
4669           This function depends on the feature "luks".  See also
4670           "$g->feature-available".
4671
4672       $g->lvcreate ($logvol, $volgroup, $mbytes);
4673           This creates an LVM logical volume called "logvol" on the volume
4674           group "volgroup", with "size" megabytes.
4675
4676           This function depends on the feature "lvm2".  See also
4677           "$g->feature-available".
4678
4679       $g->lvcreate_free ($logvol, $volgroup, $percent);
4680           Create an LVM logical volume called /dev/volgroup/logvol, using
4681           approximately "percent" % of the free space remaining in the volume
4682           group.  Most usefully, when "percent" is 100 this will create the
4683           largest possible LV.
4684
4685           This function depends on the feature "lvm2".  See also
4686           "$g->feature-available".
4687
4688       $lv = $g->lvm_canonical_lv_name ($lvname);
4689           This converts alternative naming schemes for LVs that you might
4690           find to the canonical name.  For example, /dev/mapper/VG-LV is
4691           converted to /dev/VG/LV.
4692
4693           This command returns an error if the "lvname" parameter does not
4694           refer to a logical volume.  In this case errno will be set to
4695           "EINVAL".
4696
4697           See also "$g->is_lv", "$g->canonical_device_name".
4698
4699       $g->lvm_clear_filter ();
4700           This undoes the effect of "$g->lvm_set_filter".  LVM will be able
4701           to see every block device.
4702
4703           This command also clears the LVM cache and performs a volume group
4704           scan.
4705
4706       $g->lvm_remove_all ();
4707           This command removes all LVM logical volumes, volume groups and
4708           physical volumes.
4709
4710           This function depends on the feature "lvm2".  See also
4711           "$g->feature-available".
4712
4713       $g->lvm_scan ($activate);
4714           This scans all block devices and rebuilds the list of LVM physical
4715           volumes, volume groups and logical volumes.
4716
4717           If the "activate" parameter is "true" then newly found volume
4718           groups and logical volumes are activated, meaning the LV /dev/VG/LV
4719           devices become visible.
4720
4721           When a libguestfs handle is launched it scans for existing devices,
4722           so you do not normally need to use this API.  However it is useful
4723           when you have added a new device or deleted an existing device
4724           (such as when the "$g->luks_open" API is used).
4725
4726       $g->lvm_set_filter (\@devices);
4727           This sets the LVM device filter so that LVM will only be able to
4728           "see" the block devices in the list "devices", and will ignore all
4729           other attached block devices.
4730
4731           Where disk image(s) contain duplicate PVs or VGs, this command is
4732           useful to get LVM to ignore the duplicates, otherwise LVM can get
4733           confused.  Note also there are two types of duplication possible:
4734           either cloned PVs/VGs which have identical UUIDs; or VGs that are
4735           not cloned but just happen to have the same name.  In normal
4736           operation you cannot create this situation, but you can do it
4737           outside LVM, eg.  by cloning disk images or by bit twiddling inside
4738           the LVM metadata.
4739
4740           This command also clears the LVM cache and performs a volume group
4741           scan.
4742
4743           You can filter whole block devices or individual partitions.
4744
4745           You cannot use this if any VG is currently in use (eg.  contains a
4746           mounted filesystem), even if you are not filtering out that VG.
4747
4748           This function depends on the feature "lvm2".  See also
4749           "$g->feature-available".
4750
4751       $g->lvremove ($device);
4752           Remove an LVM logical volume "device", where "device" is the path
4753           to the LV, such as /dev/VG/LV.
4754
4755           You can also remove all LVs in a volume group by specifying the VG
4756           name, /dev/VG.
4757
4758           This function depends on the feature "lvm2".  See also
4759           "$g->feature-available".
4760
4761       $g->lvrename ($logvol, $newlogvol);
4762           Rename a logical volume "logvol" with the new name "newlogvol".
4763
4764       $g->lvresize ($device, $mbytes);
4765           This resizes (expands or shrinks) an existing LVM logical volume to
4766           "mbytes".  When reducing, data in the reduced part is lost.
4767
4768           This function depends on the feature "lvm2".  See also
4769           "$g->feature-available".
4770
4771       $g->lvresize_free ($lv, $percent);
4772           This expands an existing logical volume "lv" so that it fills "pc"
4773           % of the remaining free space in the volume group.  Commonly you
4774           would call this with pc = 100 which expands the logical volume as
4775           much as possible, using all remaining free space in the volume
4776           group.
4777
4778           This function depends on the feature "lvm2".  See also
4779           "$g->feature-available".
4780
4781       @logvols = $g->lvs ();
4782           List all the logical volumes detected.  This is the equivalent of
4783           the lvs(8) command.
4784
4785           This returns a list of the logical volume device names (eg.
4786           /dev/VolGroup00/LogVol00).
4787
4788           See also "$g->lvs_full", "$g->list_filesystems".
4789
4790           This function depends on the feature "lvm2".  See also
4791           "$g->feature-available".
4792
4793       @logvols = $g->lvs_full ();
4794           List all the logical volumes detected.  This is the equivalent of
4795           the lvs(8) command.  The "full" version includes all fields.
4796
4797           This function depends on the feature "lvm2".  See also
4798           "$g->feature-available".
4799
4800       $uuid = $g->lvuuid ($device);
4801           This command returns the UUID of the LVM LV "device".
4802
4803       @xattrs = $g->lxattrlist ($path, \@names);
4804           This call allows you to get the extended attributes of multiple
4805           files, where all files are in the directory "path".  "names" is the
4806           list of files from this directory.
4807
4808           On return you get a flat list of xattr structs which must be
4809           interpreted sequentially.  The first xattr struct always has a
4810           zero-length "attrname".  "attrval" in this struct is zero-length to
4811           indicate there was an error doing "$g->lgetxattr" for this file, or
4812           is a C string which is a decimal number (the number of following
4813           attributes for this file, which could be "0").  Then after the
4814           first xattr struct are the zero or more attributes for the first
4815           named file.  This repeats for the second and subsequent files.
4816
4817           This call is intended for programs that want to efficiently list a
4818           directory contents without making many round-trips.  See also
4819           "$g->lstatlist" for a similarly efficient call for getting standard
4820           stats.
4821
4822           This function depends on the feature "linuxxattrs".  See also
4823           "$g->feature-available".
4824
4825       $disks = $g->max_disks ();
4826           Return the maximum number of disks that may be added to a handle
4827           (eg. by "$g->add_drive_opts" and similar calls).
4828
4829           This function was added in libguestfs 1.19.7.  In previous versions
4830           of libguestfs the limit was 25.
4831
4832           See "MAXIMUM NUMBER OF DISKS" in guestfs(3) for additional
4833           information on this topic.
4834
4835       $g->md_create ($name, \@devices [, missingbitmap => $missingbitmap] [,
4836       nrdevices => $nrdevices] [, spare => $spare] [, chunk => $chunk] [,
4837       level => $level]);
4838           Create a Linux md (RAID) device named "name" on the devices in the
4839           list "devices".
4840
4841           The optional parameters are:
4842
4843           "missingbitmap"
4844               A bitmap of missing devices.  If a bit is set it means that a
4845               missing device is added to the array.  The least significant
4846               bit corresponds to the first device in the array.
4847
4848               As examples:
4849
4850               If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
4851               resulting array would be "[<missing>, "/dev/sda"]".
4852
4853               If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
4854               resulting array would be "["/dev/sda", <missing>]".
4855
4856               This defaults to 0 (no missing devices).
4857
4858               The length of "devices" + the number of bits set in
4859               "missingbitmap" must equal "nrdevices" + "spare".
4860
4861           "nrdevices"
4862               The number of active RAID devices.
4863
4864               If not set, this defaults to the length of "devices" plus the
4865               number of bits set in "missingbitmap".
4866
4867           "spare"
4868               The number of spare devices.
4869
4870               If not set, this defaults to 0.
4871
4872           "chunk"
4873               The chunk size in bytes.
4874
4875               The "chunk" parameter does not make sense, and should not be
4876               specified, when "level" is "raid1" (which is the default; see
4877               below).
4878
4879           "level"
4880               The RAID level, which can be one of: "linear", "raid0", 0,
4881               "stripe", "raid1", 1, "mirror", "raid4", 4, "raid5", 5,
4882               "raid6", 6, "raid10", 10.  Some of these are synonymous, and
4883               more levels may be added in future.
4884
4885               If not set, this defaults to "raid1".
4886
4887           This function depends on the feature "mdadm".  See also
4888           "$g->feature-available".
4889
4890       %info = $g->md_detail ($md);
4891           This command exposes the output of "mdadm -DY <md>".  The following
4892           fields are usually present in the returned hash.  Other fields may
4893           also be present.
4894
4895           "level"
4896               The raid level of the MD device.
4897
4898           "devices"
4899               The number of underlying devices in the MD device.
4900
4901           "metadata"
4902               The metadata version used.
4903
4904           "uuid"
4905               The UUID of the MD device.
4906
4907           "name"
4908               The name of the MD device.
4909
4910           This function depends on the feature "mdadm".  See also
4911           "$g->feature-available".
4912
4913       @devices = $g->md_stat ($md);
4914           This call returns a list of the underlying devices which make up
4915           the single software RAID array device "md".
4916
4917           To get a list of software RAID devices, call "$g->list_md_devices".
4918
4919           Each structure returned corresponds to one device along with
4920           additional status information:
4921
4922           "mdstat_device"
4923               The name of the underlying device.
4924
4925           "mdstat_index"
4926               The index of this device within the array.
4927
4928           "mdstat_flags"
4929               Flags associated with this device.  This is a string containing
4930               (in no specific order) zero or more of the following flags:
4931
4932               "W" write-mostly
4933
4934               "F" device is faulty
4935
4936               "S" device is a RAID spare
4937
4938               "R" replacement
4939
4940           This function depends on the feature "mdadm".  See also
4941           "$g->feature-available".
4942
4943       $g->md_stop ($md);
4944           This command deactivates the MD array named "md".  The device is
4945           stopped, but it is not destroyed or zeroed.
4946
4947           This function depends on the feature "mdadm".  See also
4948           "$g->feature-available".
4949
4950       $g->mkdir ($path);
4951           Create a directory named "path".
4952
4953       $g->mkdir_mode ($path, $mode);
4954           This command creates a directory, setting the initial permissions
4955           of the directory to "mode".
4956
4957           For common Linux filesystems, the actual mode which is set will be
4958           "mode & ~umask & 01777".  Non-native-Linux filesystems may
4959           interpret the mode in other ways.
4960
4961           See also "$g->mkdir", "$g->umask"
4962
4963       $g->mkdir_p ($path);
4964           Create a directory named "path", creating any parent directories as
4965           necessary.  This is like the "mkdir -p" shell command.
4966
4967       $dir = $g->mkdtemp ($tmpl);
4968           This command creates a temporary directory.  The "tmpl" parameter
4969           should be a full pathname for the temporary directory name with the
4970           final six characters being "XXXXXX".
4971
4972           For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the
4973           second one being suitable for Windows filesystems.
4974
4975           The name of the temporary directory that was created is returned.
4976
4977           The temporary directory is created with mode 0700 and is owned by
4978           root.
4979
4980           The caller is responsible for deleting the temporary directory and
4981           its contents after use.
4982
4983           See also: mkdtemp(3)
4984
4985       $g->mke2fs ($device [, blockscount => $blockscount] [, blocksize =>
4986       $blocksize] [, fragsize => $fragsize] [, blockspergroup =>
4987       $blockspergroup] [, numberofgroups => $numberofgroups] [, bytesperinode
4988       => $bytesperinode] [, inodesize => $inodesize] [, journalsize =>
4989       $journalsize] [, numberofinodes => $numberofinodes] [, stridesize =>
4990       $stridesize] [, stripewidth => $stripewidth] [, maxonlineresize =>
4991       $maxonlineresize] [, reservedblockspercentage =>
4992       $reservedblockspercentage] [, mmpupdateinterval => $mmpupdateinterval]
4993       [, journaldevice => $journaldevice] [, label => $label] [,
4994       lastmounteddir => $lastmounteddir] [, creatoros => $creatoros] [,
4995       fstype => $fstype] [, usagetype => $usagetype] [, uuid => $uuid] [,
4996       forcecreate => $forcecreate] [, writesbandgrouponly =>
4997       $writesbandgrouponly] [, lazyitableinit => $lazyitableinit] [,
4998       lazyjournalinit => $lazyjournalinit] [, testfs => $testfs] [, discard
4999       => $discard] [, quotatype => $quotatype] [, extent => $extent] [,
5000       filetype => $filetype] [, flexbg => $flexbg] [, hasjournal =>
5001       $hasjournal] [, journaldev => $journaldev] [, largefile => $largefile]
5002       [, quota => $quota] [, resizeinode => $resizeinode] [, sparsesuper =>
5003       $sparsesuper] [, uninitbg => $uninitbg]);
5004           "mke2fs" is used to create an ext2, ext3, or ext4 filesystem on
5005           "device".
5006
5007           The optional "blockscount" is the size of the filesystem in blocks.
5008           If omitted it defaults to the size of "device".  Note if the
5009           filesystem is too small to contain a journal, "mke2fs" will
5010           silently create an ext2 filesystem instead.
5011
5012       $g->mke2fs_J ($fstype, $blocksize, $device, $journal);
5013           This creates an ext2/3/4 filesystem on "device" with an external
5014           journal on "journal".  It is equivalent to the command:
5015
5016            mke2fs -t fstype -b blocksize -J device=<journal> <device>
5017
5018           See also "$g->mke2journal".
5019
5020           This function is deprecated.  In new code, use the "mke2fs" call
5021           instead.
5022
5023           Deprecated functions will not be removed from the API, but the fact
5024           that they are deprecated indicates that there are problems with
5025           correct use of these functions.
5026
5027       $g->mke2fs_JL ($fstype, $blocksize, $device, $label);
5028           This creates an ext2/3/4 filesystem on "device" with an external
5029           journal on the journal labeled "label".
5030
5031           See also "$g->mke2journal_L".
5032
5033           This function is deprecated.  In new code, use the "mke2fs" call
5034           instead.
5035
5036           Deprecated functions will not be removed from the API, but the fact
5037           that they are deprecated indicates that there are problems with
5038           correct use of these functions.
5039
5040       $g->mke2fs_JU ($fstype, $blocksize, $device, $uuid);
5041           This creates an ext2/3/4 filesystem on "device" with an external
5042           journal on the journal with UUID "uuid".
5043
5044           See also "$g->mke2journal_U".
5045
5046           This function depends on the feature "linuxfsuuid".  See also
5047           "$g->feature-available".
5048
5049           This function is deprecated.  In new code, use the "mke2fs" call
5050           instead.
5051
5052           Deprecated functions will not be removed from the API, but the fact
5053           that they are deprecated indicates that there are problems with
5054           correct use of these functions.
5055
5056       $g->mke2journal ($blocksize, $device);
5057           This creates an ext2 external journal on "device".  It is
5058           equivalent to the command:
5059
5060            mke2fs -O journal_dev -b blocksize device
5061
5062           This function is deprecated.  In new code, use the "mke2fs" call
5063           instead.
5064
5065           Deprecated functions will not be removed from the API, but the fact
5066           that they are deprecated indicates that there are problems with
5067           correct use of these functions.
5068
5069       $g->mke2journal_L ($blocksize, $label, $device);
5070           This creates an ext2 external journal on "device" with label
5071           "label".
5072
5073           This function is deprecated.  In new code, use the "mke2fs" call
5074           instead.
5075
5076           Deprecated functions will not be removed from the API, but the fact
5077           that they are deprecated indicates that there are problems with
5078           correct use of these functions.
5079
5080       $g->mke2journal_U ($blocksize, $uuid, $device);
5081           This creates an ext2 external journal on "device" with UUID "uuid".
5082
5083           This function depends on the feature "linuxfsuuid".  See also
5084           "$g->feature-available".
5085
5086           This function is deprecated.  In new code, use the "mke2fs" call
5087           instead.
5088
5089           Deprecated functions will not be removed from the API, but the fact
5090           that they are deprecated indicates that there are problems with
5091           correct use of these functions.
5092
5093       $g->mkfifo ($mode, $path);
5094           This call creates a FIFO (named pipe) called "path" with mode
5095           "mode".  It is just a convenient wrapper around "$g->mknod".
5096
5097           Unlike with "$g->mknod", "mode" must contain only permissions bits.
5098
5099           The mode actually set is affected by the umask.
5100
5101           This function depends on the feature "mknod".  See also
5102           "$g->feature-available".
5103
5104       $g->mkfs ($fstype, $device [, blocksize => $blocksize] [, features =>
5105       $features] [, inode => $inode] [, sectorsize => $sectorsize] [, label
5106       => $label]);
5107           This function creates a filesystem on "device".  The filesystem
5108           type is "fstype", for example "ext3".
5109
5110           The optional arguments are:
5111
5112           "blocksize"
5113               The filesystem block size.  Supported block sizes depend on the
5114               filesystem type, but typically they are 1024, 2048 or 4096 for
5115               Linux ext2/3 filesystems.
5116
5117               For VFAT and NTFS the "blocksize" parameter is treated as the
5118               requested cluster size.
5119
5120               For UFS block sizes, please see mkfs.ufs(8).
5121
5122           "features"
5123               This passes the -O parameter to the external mkfs program.
5124
5125               For certain filesystem types, this allows extra filesystem
5126               features to be selected.  See mke2fs(8) and mkfs.ufs(8) for
5127               more details.
5128
5129               You cannot use this optional parameter with the "gfs" or "gfs2"
5130               filesystem type.
5131
5132           "inode"
5133               This passes the -I parameter to the external mke2fs(8) program
5134               which sets the inode size (only for ext2/3/4 filesystems at
5135               present).
5136
5137           "sectorsize"
5138               This passes the -S parameter to external mkfs.ufs(8) program,
5139               which sets sector size for ufs filesystem.
5140
5141       $g->mkfs_opts ($fstype, $device [, blocksize => $blocksize] [, features
5142       => $features] [, inode => $inode] [, sectorsize => $sectorsize] [,
5143       label => $label]);
5144           This is an alias of "mkfs".
5145
5146       $g->mkfs_b ($fstype, $blocksize, $device);
5147           This call is similar to "$g->mkfs", but it allows you to control
5148           the block size of the resulting filesystem.  Supported block sizes
5149           depend on the filesystem type, but typically they are 1024, 2048 or
5150           4096 only.
5151
5152           For VFAT and NTFS the "blocksize" parameter is treated as the
5153           requested cluster size.
5154
5155           This function is deprecated.  In new code, use the "mkfs" call
5156           instead.
5157
5158           Deprecated functions will not be removed from the API, but the fact
5159           that they are deprecated indicates that there are problems with
5160           correct use of these functions.
5161
5162       $g->mkfs_btrfs (\@devices [, allocstart => $allocstart] [, bytecount =>
5163       $bytecount] [, datatype => $datatype] [, leafsize => $leafsize] [,
5164       label => $label] [, metadata => $metadata] [, nodesize => $nodesize] [,
5165       sectorsize => $sectorsize]);
5166           Create a btrfs filesystem, allowing all configurables to be set.
5167           For more information on the optional arguments, see mkfs.btrfs(8).
5168
5169           Since btrfs filesystems can span multiple devices, this takes a
5170           non-empty list of devices.
5171
5172           To create general filesystems, use "$g->mkfs".
5173
5174           This function depends on the feature "btrfs".  See also
5175           "$g->feature-available".
5176
5177       $g->mklost_and_found ($mountpoint);
5178           Make the "lost+found" directory, normally in the root directory of
5179           an ext2/3/4 filesystem.  "mountpoint" is the directory under which
5180           we try to create the "lost+found" directory.
5181
5182       $g->mkmountpoint ($exemptpath);
5183           "$g->mkmountpoint" and "$g->rmmountpoint" are specialized calls
5184           that can be used to create extra mountpoints before mounting the
5185           first filesystem.
5186
5187           These calls are only necessary in some very limited circumstances,
5188           mainly the case where you want to mount a mix of unrelated and/or
5189           read-only filesystems together.
5190
5191           For example, live CDs often contain a "Russian doll" nest of
5192           filesystems, an ISO outer layer, with a squashfs image inside, with
5193           an ext2/3 image inside that.  You can unpack this as follows in
5194           guestfish:
5195
5196            add-ro Fedora-11-i686-Live.iso
5197            run
5198            mkmountpoint /cd
5199            mkmountpoint /sqsh
5200            mkmountpoint /ext3fs
5201            mount /dev/sda /cd
5202            mount-loop /cd/LiveOS/squashfs.img /sqsh
5203            mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
5204
5205           The inner filesystem is now unpacked under the /ext3fs mountpoint.
5206
5207           "$g->mkmountpoint" is not compatible with "$g->umount_all".  You
5208           may get unexpected errors if you try to mix these calls.  It is
5209           safest to manually unmount filesystems and remove mountpoints after
5210           use.
5211
5212           "$g->umount_all" unmounts filesystems by sorting the paths longest
5213           first, so for this to work for manual mountpoints, you must ensure
5214           that the innermost mountpoints have the longest pathnames, as in
5215           the example code above.
5216
5217           For more details see
5218           <https://bugzilla.redhat.com/show_bug.cgi?id=599503>
5219
5220           Autosync [see "$g->set_autosync", this is set by default on
5221           handles] can cause "$g->umount_all" to be called when the handle is
5222           closed which can also trigger these issues.
5223
5224       $g->mknod ($mode, $devmajor, $devminor, $path);
5225           This call creates block or character special devices, or named
5226           pipes (FIFOs).
5227
5228           The "mode" parameter should be the mode, using the standard
5229           constants.  "devmajor" and "devminor" are the device major and
5230           minor numbers, only used when creating block and character special
5231           devices.
5232
5233           Note that, just like mknod(2), the mode must be bitwise OR'd with
5234           S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just
5235           creates a regular file).  These constants are available in the
5236           standard Linux header files, or you can use "$g->mknod_b",
5237           "$g->mknod_c" or "$g->mkfifo" which are wrappers around this
5238           command which bitwise OR in the appropriate constant for you.
5239
5240           The mode actually set is affected by the umask.
5241
5242           This function depends on the feature "mknod".  See also
5243           "$g->feature-available".
5244
5245       $g->mknod_b ($mode, $devmajor, $devminor, $path);
5246           This call creates a block device node called "path" with mode
5247           "mode" and device major/minor "devmajor" and "devminor".  It is
5248           just a convenient wrapper around "$g->mknod".
5249
5250           Unlike with "$g->mknod", "mode" must contain only permissions bits.
5251
5252           The mode actually set is affected by the umask.
5253
5254           This function depends on the feature "mknod".  See also
5255           "$g->feature-available".
5256
5257       $g->mknod_c ($mode, $devmajor, $devminor, $path);
5258           This call creates a char device node called "path" with mode "mode"
5259           and device major/minor "devmajor" and "devminor".  It is just a
5260           convenient wrapper around "$g->mknod".
5261
5262           Unlike with "$g->mknod", "mode" must contain only permissions bits.
5263
5264           The mode actually set is affected by the umask.
5265
5266           This function depends on the feature "mknod".  See also
5267           "$g->feature-available".
5268
5269       $g->mksquashfs ($path, $filename [, compress => $compress] [, excludes
5270       => $excludes]);
5271           Create a squashfs filesystem for the specified "path".
5272
5273           The optional "compress" flag controls compression.  If not given,
5274           then the output compressed using "gzip".  Otherwise one of the
5275           following strings may be given to select the compression type of
5276           the squashfs: "gzip", "lzma", "lzo", "lz4", "xz".
5277
5278           The other optional arguments are:
5279
5280           "excludes"
5281               A list of wildcards.  Files are excluded if they match any of
5282               the wildcards.
5283
5284           Please note that this API may fail when used to compress
5285           directories with large files, such as the resulting squashfs will
5286           be over 3GB big.
5287
5288           This function depends on the feature "squashfs".  See also
5289           "$g->feature-available".
5290
5291       $g->mkswap ($device [, label => $label] [, uuid => $uuid]);
5292           Create a Linux swap partition on "device".
5293
5294           The option arguments "label" and "uuid" allow you to set the label
5295           and/or UUID of the new swap partition.
5296
5297       $g->mkswap_opts ($device [, label => $label] [, uuid => $uuid]);
5298           This is an alias of "mkswap".
5299
5300       $g->mkswap_L ($label, $device);
5301           Create a swap partition on "device" with label "label".
5302
5303           Note that you cannot attach a swap label to a block device (eg.
5304           /dev/sda), just to a partition.  This appears to be a limitation of
5305           the kernel or swap tools.
5306
5307           This function is deprecated.  In new code, use the "mkswap" call
5308           instead.
5309
5310           Deprecated functions will not be removed from the API, but the fact
5311           that they are deprecated indicates that there are problems with
5312           correct use of these functions.
5313
5314       $g->mkswap_U ($uuid, $device);
5315           Create a swap partition on "device" with UUID "uuid".
5316
5317           This function depends on the feature "linuxfsuuid".  See also
5318           "$g->feature-available".
5319
5320           This function is deprecated.  In new code, use the "mkswap" call
5321           instead.
5322
5323           Deprecated functions will not be removed from the API, but the fact
5324           that they are deprecated indicates that there are problems with
5325           correct use of these functions.
5326
5327       $g->mkswap_file ($path);
5328           Create a swap file.
5329
5330           This command just writes a swap file signature to an existing file.
5331           To create the file itself, use something like "$g->fallocate".
5332
5333       $path = $g->mktemp ($tmpl [, suffix => $suffix]);
5334           This command creates a temporary file.  The "tmpl" parameter should
5335           be a full pathname for the temporary directory name with the final
5336           six characters being "XXXXXX".
5337
5338           For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the
5339           second one being suitable for Windows filesystems.
5340
5341           The name of the temporary file that was created is returned.
5342
5343           The temporary file is created with mode 0600 and is owned by root.
5344
5345           The caller is responsible for deleting the temporary file after
5346           use.
5347
5348           If the optional "suffix" parameter is given, then the suffix (eg.
5349           ".txt") is appended to the temporary name.
5350
5351           See also: "$g->mkdtemp".
5352
5353       $g->modprobe ($modulename);
5354           This loads a kernel module in the appliance.
5355
5356           This function depends on the feature "linuxmodules".  See also
5357           "$g->feature-available".
5358
5359       $g->mount ($mountable, $mountpoint);
5360           Mount a guest disk at a position in the filesystem.  Block devices
5361           are named /dev/sda, /dev/sdb and so on, as they were added to the
5362           guest.  If those block devices contain partitions, they will have
5363           the usual names (eg. /dev/sda1).  Also LVM /dev/VG/LV-style names
5364           can be used, or ‘mountable’ strings returned by
5365           "$g->list_filesystems" or "$g->inspect_get_mountpoints".
5366
5367           The rules are the same as for mount(2):  A filesystem must first be
5368           mounted on / before others can be mounted.  Other filesystems can
5369           only be mounted on directories which already exist.
5370
5371           The mounted filesystem is writable, if we have sufficient
5372           permissions on the underlying device.
5373
5374           Before libguestfs 1.13.16, this call implicitly added the options
5375           "sync" and "noatime".  The "sync" option greatly slowed writes and
5376           caused many problems for users.  If your program might need to work
5377           with older versions of libguestfs, use "$g->mount_options" instead
5378           (using an empty string for the first parameter if you don't want
5379           any options).
5380
5381       $g->mount_9p ($mounttag, $mountpoint [, options => $options]);
5382           This call does nothing and returns an error.
5383
5384           This function is deprecated.  There is no replacement.  Consult the
5385           API documentation in guestfs(3) for further information.
5386
5387           Deprecated functions will not be removed from the API, but the fact
5388           that they are deprecated indicates that there are problems with
5389           correct use of these functions.
5390
5391       $g->mount_local ($localmountpoint [, readonly => $readonly] [, options
5392       => $options] [, cachetimeout => $cachetimeout] [, debugcalls =>
5393       $debugcalls]);
5394           This call exports the libguestfs-accessible filesystem to a local
5395           mountpoint (directory) called "localmountpoint".  Ordinary reads
5396           and writes to files and directories under "localmountpoint" are
5397           redirected through libguestfs.
5398
5399           If the optional "readonly" flag is set to true, then writes to the
5400           filesystem return error "EROFS".
5401
5402           "options" is a comma-separated list of mount options.  See
5403           guestmount(1) for some useful options.
5404
5405           "cachetimeout" sets the timeout (in seconds) for cached directory
5406           entries.  The default is 60 seconds.  See guestmount(1) for further
5407           information.
5408
5409           If "debugcalls" is set to true, then additional debugging
5410           information is generated for every FUSE call.
5411
5412           When "$g->mount_local" returns, the filesystem is ready, but is not
5413           processing requests (access to it will block).  You have to call
5414           "$g->mount_local_run" to run the main loop.
5415
5416           See "MOUNT LOCAL" in guestfs(3) for full documentation.
5417
5418       $g->mount_local_run ();
5419           Run the main loop which translates kernel calls to libguestfs
5420           calls.
5421
5422           This should only be called after "$g->mount_local" returns
5423           successfully.  The call will not return until the filesystem is
5424           unmounted.
5425
5426           Note you must not make concurrent libguestfs calls on the same
5427           handle from another thread.
5428
5429           You may call this from a different thread than the one which called
5430           "$g->mount_local", subject to the usual rules for threads and
5431           libguestfs (see "MULTIPLE HANDLES AND MULTIPLE THREADS" in
5432           guestfs(3)).
5433
5434           See "MOUNT LOCAL" in guestfs(3) for full documentation.
5435
5436       $g->mount_loop ($file, $mountpoint);
5437           This command lets you mount file (a filesystem image in a file) on
5438           a mount point.  It is entirely equivalent to the command "mount -o
5439           loop file mountpoint".
5440
5441       $g->mount_options ($options, $mountable, $mountpoint);
5442           This is the same as the "$g->mount" command, but it allows you to
5443           set the mount options as for the mount(8) -o flag.
5444
5445           If the "options" parameter is an empty string, then no options are
5446           passed (all options default to whatever the filesystem uses).
5447
5448       $g->mount_ro ($mountable, $mountpoint);
5449           This is the same as the "$g->mount" command, but it mounts the
5450           filesystem with the read-only (-o ro) flag.
5451
5452       $g->mount_vfs ($options, $vfstype, $mountable, $mountpoint);
5453           This is the same as the "$g->mount" command, but it allows you to
5454           set both the mount options and the vfstype as for the mount(8) -o
5455           and -t flags.
5456
5457       $device = $g->mountable_device ($mountable);
5458           Returns the device name of a mountable. In quite a lot of cases,
5459           the mountable is the device name.
5460
5461           However this doesn't apply for btrfs subvolumes, where the
5462           mountable is a combination of both the device name and the
5463           subvolume path (see also "$g->mountable_subvolume" to extract the
5464           subvolume path of the mountable if any).
5465
5466       $subvolume = $g->mountable_subvolume ($mountable);
5467           Returns the subvolume path of a mountable. Btrfs subvolumes
5468           mountables are a combination of both the device name and the
5469           subvolume path (see also "$g->mountable_device" to extract the
5470           device of the mountable).
5471
5472           If the mountable does not represent a btrfs subvolume, then this
5473           function fails and the "errno" is set to "EINVAL".
5474
5475       %mps = $g->mountpoints ();
5476           This call is similar to "$g->mounts".  That call returns a list of
5477           devices.  This one returns a hash table (map) of device name to
5478           directory where the device is mounted.
5479
5480       @devices = $g->mounts ();
5481           This returns the list of currently mounted filesystems.  It returns
5482           the list of devices (eg. /dev/sda1, /dev/VG/LV).
5483
5484           Some internal mounts are not shown.
5485
5486           See also: "$g->mountpoints"
5487
5488       $g->mv ($src, $dest);
5489           This moves a file from "src" to "dest" where "dest" is either a
5490           destination filename or destination directory.
5491
5492           See also: "$g->rename".
5493
5494       $nrdisks = $g->nr_devices ();
5495           This returns the number of whole block devices that were added.
5496           This is the same as the number of devices that would be returned if
5497           you called "$g->list_devices".
5498
5499           To find out the maximum number of devices that could be added, call
5500           "$g->max_disks".
5501
5502       $status = $g->ntfs_3g_probe ($rw, $device);
5503           This command runs the ntfs-3g.probe(8) command which probes an NTFS
5504           "device" for mountability.  (Not all NTFS volumes can be mounted
5505           read-write, and some cannot be mounted at all).
5506
5507           "rw" is a boolean flag.  Set it to true if you want to test if the
5508           volume can be mounted read-write.  Set it to false if you want to
5509           test if the volume can be mounted read-only.
5510
5511           The return value is an integer which 0 if the operation would
5512           succeed, or some non-zero value documented in the ntfs-3g.probe(8)
5513           manual page.
5514
5515           This function depends on the feature "ntfs3g".  See also
5516           "$g->feature-available".
5517
5518       $g->ntfscat_i ($device, $inode, $filename);
5519           Download a file given its inode from a NTFS filesystem and save it
5520           as filename on the local machine.
5521
5522           This allows to download some otherwise inaccessible files such as
5523           the ones within the $Extend folder.
5524
5525           The filesystem from which to extract the file must be unmounted,
5526           otherwise the call will fail.
5527
5528       $g->ntfsclone_in ($backupfile, $device);
5529           Restore the "backupfile" (from a previous call to
5530           "$g->ntfsclone_out") to "device", overwriting any existing contents
5531           of this device.
5532
5533           This function depends on the feature "ntfs3g".  See also
5534           "$g->feature-available".
5535
5536       $g->ntfsclone_out ($device, $backupfile [, metadataonly =>
5537       $metadataonly] [, rescue => $rescue] [, ignorefscheck =>
5538       $ignorefscheck] [, preservetimestamps => $preservetimestamps] [, force
5539       => $force]);
5540           Stream the NTFS filesystem "device" to the local file "backupfile".
5541           The format used for the backup file is a special format used by the
5542           ntfsclone(8) tool.
5543
5544           If the optional "metadataonly" flag is true, then only the metadata
5545           is saved, losing all the user data (this is useful for diagnosing
5546           some filesystem problems).
5547
5548           The optional "rescue", "ignorefscheck", "preservetimestamps" and
5549           "force" flags have precise meanings detailed in the ntfsclone(8)
5550           man page.
5551
5552           Use "$g->ntfsclone_in" to restore the file back to a libguestfs
5553           device.
5554
5555           This function depends on the feature "ntfs3g".  See also
5556           "$g->feature-available".
5557
5558       $g->ntfsfix ($device [, clearbadsectors => $clearbadsectors]);
5559           This command repairs some fundamental NTFS inconsistencies, resets
5560           the NTFS journal file, and schedules an NTFS consistency check for
5561           the first boot into Windows.
5562
5563           This is not an equivalent of Windows "chkdsk".  It does not scan
5564           the filesystem for inconsistencies.
5565
5566           The optional "clearbadsectors" flag clears the list of bad sectors.
5567           This is useful after cloning a disk with bad sectors to a new disk.
5568
5569           This function depends on the feature "ntfs3g".  See also
5570           "$g->feature-available".
5571
5572       $g->ntfsresize ($device [, size => $size] [, force => $force]);
5573           This command resizes an NTFS filesystem, expanding or shrinking it
5574           to the size of the underlying device.
5575
5576           The optional parameters are:
5577
5578           "size"
5579               The new size (in bytes) of the filesystem.  If omitted, the
5580               filesystem is resized to fit the container (eg. partition).
5581
5582           "force"
5583               If this option is true, then force the resize of the filesystem
5584               even if the filesystem is marked as requiring a consistency
5585               check.
5586
5587               After the resize operation, the filesystem is always marked as
5588               requiring a consistency check (for safety).  You have to boot
5589               into Windows to perform this check and clear this condition.
5590               If you don't set the "force" option then it is not possible to
5591               call "$g->ntfsresize" multiple times on a single filesystem
5592               without booting into Windows between each resize.
5593
5594           See also ntfsresize(8).
5595
5596           This function depends on the feature "ntfsprogs".  See also
5597           "$g->feature-available".
5598
5599       $g->ntfsresize_opts ($device [, size => $size] [, force => $force]);
5600           This is an alias of "ntfsresize".
5601
5602       $g->ntfsresize_size ($device, $size);
5603           This command is the same as "$g->ntfsresize" except that it allows
5604           you to specify the new size (in bytes) explicitly.
5605
5606           This function depends on the feature "ntfsprogs".  See also
5607           "$g->feature-available".
5608
5609           This function is deprecated.  In new code, use the "ntfsresize"
5610           call instead.
5611
5612           Deprecated functions will not be removed from the API, but the fact
5613           that they are deprecated indicates that there are problems with
5614           correct use of these functions.
5615
5616       $g->parse_environment ();
5617           Parse the program’s environment and set flags in the handle
5618           accordingly.  For example if "LIBGUESTFS_DEBUG=1" then the
5619           ‘verbose’ flag is set in the handle.
5620
5621           Most programs do not need to call this.  It is done implicitly when
5622           you call "$g->create".
5623
5624           See "ENVIRONMENT VARIABLES" in guestfs(3) for a list of environment
5625           variables that can affect libguestfs handles.  See also
5626           "guestfs_create_flags" in guestfs(3), and
5627           "$g->parse_environment_list".
5628
5629       $g->parse_environment_list (\@environment);
5630           Parse the list of strings in the argument "environment" and set
5631           flags in the handle accordingly.  For example if
5632           "LIBGUESTFS_DEBUG=1" is a string in the list, then the ‘verbose’
5633           flag is set in the handle.
5634
5635           This is the same as "$g->parse_environment" except that it parses
5636           an explicit list of strings instead of the program's environment.
5637
5638       $g->part_add ($device, $prlogex, $startsect, $endsect);
5639           This command adds a partition to "device".  If there is no
5640           partition table on the device, call "$g->part_init" first.
5641
5642           The "prlogex" parameter is the type of partition.  Normally you
5643           should pass "p" or "primary" here, but MBR partition tables also
5644           support "l" (or "logical") and "e" (or "extended") partition types.
5645
5646           "startsect" and "endsect" are the start and end of the partition in
5647           sectors.  "endsect" may be negative, which means it counts
5648           backwards from the end of the disk (-1 is the last sector).
5649
5650           Creating a partition which covers the whole disk is not so easy.
5651           Use "$g->part_disk" to do that.
5652
5653       $g->part_del ($device, $partnum);
5654           This command deletes the partition numbered "partnum" on "device".
5655
5656           Note that in the case of MBR partitioning, deleting an extended
5657           partition also deletes any logical partitions it contains.
5658
5659       $g->part_disk ($device, $parttype);
5660           This command is simply a combination of "$g->part_init" followed by
5661           "$g->part_add" to create a single primary partition covering the
5662           whole disk.
5663
5664           "parttype" is the partition table type, usually "mbr" or "gpt", but
5665           other possible values are described in "$g->part_init".
5666
5667       $g->part_expand_gpt ($device);
5668           Move backup GPT data structures to the end of the disk.  This is
5669           useful in case of in-place image expand since disk space after
5670           backup GPT header is not usable.  This is equivalent to "sgdisk
5671           -e".
5672
5673           See also sgdisk(8).
5674
5675           This function depends on the feature "gdisk".  See also
5676           "$g->feature-available".
5677
5678       $bootable = $g->part_get_bootable ($device, $partnum);
5679           This command returns true if the partition "partnum" on "device"
5680           has the bootable flag set.
5681
5682           See also "$g->part_set_bootable".
5683
5684       $guid = $g->part_get_disk_guid ($device);
5685           Return the disk identifier (GUID) of a GPT-partitioned "device".
5686           Behaviour is undefined for other partition types.
5687
5688           This function depends on the feature "gdisk".  See also
5689           "$g->feature-available".
5690
5691       $attributes = $g->part_get_gpt_attributes ($device, $partnum);
5692           Return the attribute flags of numbered GPT partition "partnum".  An
5693           error is returned for MBR partitions.
5694
5695           This function depends on the feature "gdisk".  See also
5696           "$g->feature-available".
5697
5698       $guid = $g->part_get_gpt_guid ($device, $partnum);
5699           Return the GUID of numbered GPT partition "partnum".
5700
5701           This function depends on the feature "gdisk".  See also
5702           "$g->feature-available".
5703
5704       $guid = $g->part_get_gpt_type ($device, $partnum);
5705           Return the type GUID of numbered GPT partition "partnum". For MBR
5706           partitions, return an appropriate GUID corresponding to the MBR
5707           type. Behaviour is undefined for other partition types.
5708
5709           This function depends on the feature "gdisk".  See also
5710           "$g->feature-available".
5711
5712       $idbyte = $g->part_get_mbr_id ($device, $partnum);
5713           Returns the MBR type byte (also known as the ID byte) from the
5714           numbered partition "partnum".
5715
5716           Note that only MBR (old DOS-style) partitions have type bytes.  You
5717           will get undefined results for other partition table types (see
5718           "$g->part_get_parttype").
5719
5720       $partitiontype = $g->part_get_mbr_part_type ($device, $partnum);
5721           This returns the partition type of an MBR partition numbered
5722           "partnum" on device "device".
5723
5724           It returns "primary", "logical", or "extended".
5725
5726       $name = $g->part_get_name ($device, $partnum);
5727           This gets the partition name on partition numbered "partnum" on
5728           device "device".  Note that partitions are numbered from 1.
5729
5730           The partition name can only be read on certain types of partition
5731           table.  This works on "gpt" but not on "mbr" partitions.
5732
5733       $parttype = $g->part_get_parttype ($device);
5734           This command examines the partition table on "device" and returns
5735           the partition table type (format) being used.
5736
5737           Common return values include: "msdos" (a DOS/Windows style MBR
5738           partition table), "gpt" (a GPT/EFI-style partition table).  Other
5739           values are possible, although unusual.  See "$g->part_init" for a
5740           full list.
5741
5742       $g->part_init ($device, $parttype);
5743           This creates an empty partition table on "device" of one of the
5744           partition types listed below.  Usually "parttype" should be either
5745           "msdos" or "gpt" (for large disks).
5746
5747           Initially there are no partitions.  Following this, you should call
5748           "$g->part_add" for each partition required.
5749
5750           Possible values for "parttype" are:
5751
5752           "efi"
5753           "gpt"
5754               Intel EFI / GPT partition table.
5755
5756               This is recommended for >= 2 TB partitions that will be
5757               accessed from Linux and Intel-based Mac OS X.  It also has
5758               limited backwards compatibility with the "mbr" format.
5759
5760           "mbr"
5761           "msdos"
5762               The standard PC "Master Boot Record" (MBR) format used by MS-
5763               DOS and Windows.  This partition type will only work for device
5764               sizes up to 2 TB.  For large disks we recommend using "gpt".
5765
5766           Other partition table types that may work but are not supported
5767           include:
5768
5769           "aix"
5770               AIX disk labels.
5771
5772           "amiga"
5773           "rdb"
5774               Amiga "Rigid Disk Block" format.
5775
5776           "bsd"
5777               BSD disk labels.
5778
5779           "dasd"
5780               DASD, used on IBM mainframes.
5781
5782           "dvh"
5783               MIPS/SGI volumes.
5784
5785           "mac"
5786               Old Mac partition format.  Modern Macs use "gpt".
5787
5788           "pc98"
5789               NEC PC-98 format, common in Japan apparently.
5790
5791           "sun"
5792               Sun disk labels.
5793
5794       @partitions = $g->part_list ($device);
5795           This command parses the partition table on "device" and returns the
5796           list of partitions found.
5797
5798           The fields in the returned structure are:
5799
5800           "part_num"
5801               Partition number, counting from 1.
5802
5803           "part_start"
5804               Start of the partition in bytes.  To get sectors you have to
5805               divide by the device’s sector size, see "$g->blockdev_getss".
5806
5807           "part_end"
5808               End of the partition in bytes.
5809
5810           "part_size"
5811               Size of the partition in bytes.
5812
5813       $g->part_resize ($device, $partnum, $endsect);
5814           This command resizes the partition numbered "partnum" on "device"
5815           by moving the end position.
5816
5817           Note that this does not modify any filesystem present in the
5818           partition.  If you wish to do this, you will need to use filesystem
5819           resizing commands like "$g->resize2fs".
5820
5821           When growing a partition you will want to grow the filesystem
5822           afterwards, but when shrinking, you need to shrink the filesystem
5823           before the partition.
5824
5825       $g->part_set_bootable ($device, $partnum, $bootable);
5826           This sets the bootable flag on partition numbered "partnum" on
5827           device "device".  Note that partitions are numbered from 1.
5828
5829           The bootable flag is used by some operating systems (notably
5830           Windows) to determine which partition to boot from.  It is by no
5831           means universally recognized.
5832
5833       $g->part_set_disk_guid ($device, $guid);
5834           Set the disk identifier (GUID) of a GPT-partitioned "device" to
5835           "guid".  Return an error if the partition table of "device" isn't
5836           GPT, or if "guid" is not a valid GUID.
5837
5838           This function depends on the feature "gdisk".  See also
5839           "$g->feature-available".
5840
5841       $g->part_set_disk_guid_random ($device);
5842           Set the disk identifier (GUID) of a GPT-partitioned "device" to a
5843           randomly generated value.  Return an error if the partition table
5844           of "device" isn't GPT.
5845
5846           This function depends on the feature "gdisk".  See also
5847           "$g->feature-available".
5848
5849       $g->part_set_gpt_attributes ($device, $partnum, $attributes);
5850           Set the attribute flags of numbered GPT partition "partnum" to
5851           "attributes". Return an error if the partition table of "device"
5852           isn't GPT.
5853
5854           See
5855           <https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_entries>
5856           for a useful list of partition attributes.
5857
5858           This function depends on the feature "gdisk".  See also
5859           "$g->feature-available".
5860
5861       $g->part_set_gpt_guid ($device, $partnum, $guid);
5862           Set the GUID of numbered GPT partition "partnum" to "guid".  Return
5863           an error if the partition table of "device" isn't GPT, or if "guid"
5864           is not a valid GUID.
5865
5866           This function depends on the feature "gdisk".  See also
5867           "$g->feature-available".
5868
5869       $g->part_set_gpt_type ($device, $partnum, $guid);
5870           Set the type GUID of numbered GPT partition "partnum" to "guid".
5871           Return an error if the partition table of "device" isn't GPT, or if
5872           "guid" is not a valid GUID.
5873
5874           See
5875           <https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs>
5876           for a useful list of type GUIDs.
5877
5878           This function depends on the feature "gdisk".  See also
5879           "$g->feature-available".
5880
5881       $g->part_set_mbr_id ($device, $partnum, $idbyte);
5882           Sets the MBR type byte (also known as the ID byte) of the numbered
5883           partition "partnum" to "idbyte".  Note that the type bytes quoted
5884           in most documentation are in fact hexadecimal numbers, but usually
5885           documented without any leading "0x" which might be confusing.
5886
5887           Note that only MBR (old DOS-style) partitions have type bytes.  You
5888           will get undefined results for other partition table types (see
5889           "$g->part_get_parttype").
5890
5891       $g->part_set_name ($device, $partnum, $name);
5892           This sets the partition name on partition numbered "partnum" on
5893           device "device".  Note that partitions are numbered from 1.
5894
5895           The partition name can only be set on certain types of partition
5896           table.  This works on "gpt" but not on "mbr" partitions.
5897
5898       $device = $g->part_to_dev ($partition);
5899           This function takes a partition name (eg. "/dev/sdb1") and removes
5900           the partition number, returning the device name (eg. "/dev/sdb").
5901
5902           The named partition must exist, for example as a string returned
5903           from "$g->list_partitions".
5904
5905           See also "$g->part_to_partnum", "$g->device_index".
5906
5907       $partnum = $g->part_to_partnum ($partition);
5908           This function takes a partition name (eg. "/dev/sdb1") and returns
5909           the partition number (eg. 1).
5910
5911           The named partition must exist, for example as a string returned
5912           from "$g->list_partitions".
5913
5914           See also "$g->part_to_dev".
5915
5916       $g->ping_daemon ();
5917           This is a test probe into the guestfs daemon running inside the
5918           libguestfs appliance.  Calling this function checks that the daemon
5919           responds to the ping message, without affecting the daemon or
5920           attached block device(s) in any other way.
5921
5922       $content = $g->pread ($path, $count, $offset);
5923           This command lets you read part of a file.  It reads "count" bytes
5924           of the file, starting at "offset", from file "path".
5925
5926           This may read fewer bytes than requested.  For further details see
5927           the pread(2) system call.
5928
5929           See also "$g->pwrite", "$g->pread_device".
5930
5931           Because of the message protocol, there is a transfer limit of
5932           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
5933           guestfs(3).
5934
5935       $content = $g->pread_device ($device, $count, $offset);
5936           This command lets you read part of a block device.  It reads
5937           "count" bytes of "device", starting at "offset".
5938
5939           This may read fewer bytes than requested.  For further details see
5940           the pread(2) system call.
5941
5942           See also "$g->pread".
5943
5944           Because of the message protocol, there is a transfer limit of
5945           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
5946           guestfs(3).
5947
5948       $g->pvchange_uuid ($device);
5949           Generate a new random UUID for the physical volume "device".
5950
5951           This function depends on the feature "lvm2".  See also
5952           "$g->feature-available".
5953
5954       $g->pvchange_uuid_all ();
5955           Generate new random UUIDs for all physical volumes.
5956
5957           This function depends on the feature "lvm2".  See also
5958           "$g->feature-available".
5959
5960       $g->pvcreate ($device);
5961           This creates an LVM physical volume on the named "device", where
5962           "device" should usually be a partition name such as /dev/sda1.
5963
5964           This function depends on the feature "lvm2".  See also
5965           "$g->feature-available".
5966
5967       $g->pvremove ($device);
5968           This wipes a physical volume "device" so that LVM will no longer
5969           recognise it.
5970
5971           The implementation uses the pvremove(8) command which refuses to
5972           wipe physical volumes that contain any volume groups, so you have
5973           to remove those first.
5974
5975           This function depends on the feature "lvm2".  See also
5976           "$g->feature-available".
5977
5978       $g->pvresize ($device);
5979           This resizes (expands or shrinks) an existing LVM physical volume
5980           to match the new size of the underlying device.
5981
5982           This function depends on the feature "lvm2".  See also
5983           "$g->feature-available".
5984
5985       $g->pvresize_size ($device, $size);
5986           This command is the same as "$g->pvresize" except that it allows
5987           you to specify the new size (in bytes) explicitly.
5988
5989           This function depends on the feature "lvm2".  See also
5990           "$g->feature-available".
5991
5992       @physvols = $g->pvs ();
5993           List all the physical volumes detected.  This is the equivalent of
5994           the pvs(8) command.
5995
5996           This returns a list of just the device names that contain PVs (eg.
5997           /dev/sda2).
5998
5999           See also "$g->pvs_full".
6000
6001           This function depends on the feature "lvm2".  See also
6002           "$g->feature-available".
6003
6004       @physvols = $g->pvs_full ();
6005           List all the physical volumes detected.  This is the equivalent of
6006           the pvs(8) command.  The "full" version includes all fields.
6007
6008           This function depends on the feature "lvm2".  See also
6009           "$g->feature-available".
6010
6011       $uuid = $g->pvuuid ($device);
6012           This command returns the UUID of the LVM PV "device".
6013
6014       $nbytes = $g->pwrite ($path, $content, $offset);
6015           This command writes to part of a file.  It writes the data buffer
6016           "content" to the file "path" starting at offset "offset".
6017
6018           This command implements the pwrite(2) system call, and like that
6019           system call it may not write the full data requested.  The return
6020           value is the number of bytes that were actually written to the
6021           file.  This could even be 0, although short writes are unlikely for
6022           regular files in ordinary circumstances.
6023
6024           See also "$g->pread", "$g->pwrite_device".
6025
6026           Because of the message protocol, there is a transfer limit of
6027           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
6028           guestfs(3).
6029
6030       $nbytes = $g->pwrite_device ($device, $content, $offset);
6031           This command writes to part of a device.  It writes the data buffer
6032           "content" to "device" starting at offset "offset".
6033
6034           This command implements the pwrite(2) system call, and like that
6035           system call it may not write the full data requested (although
6036           short writes to disk devices and partitions are probably impossible
6037           with standard Linux kernels).
6038
6039           See also "$g->pwrite".
6040
6041           Because of the message protocol, there is a transfer limit of
6042           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
6043           guestfs(3).
6044
6045       $content = $g->read_file ($path);
6046           This calls returns the contents of the file "path" as a buffer.
6047
6048           Unlike "$g->cat", this function can correctly handle files that
6049           contain embedded ASCII NUL characters.
6050
6051       @lines = $g->read_lines ($path);
6052           Return the contents of the file named "path".
6053
6054           The file contents are returned as a list of lines.  Trailing "LF"
6055           and "CRLF" character sequences are not returned.
6056
6057           Note that this function cannot correctly handle binary files
6058           (specifically, files containing "\0" character which is treated as
6059           end of string).  For those you need to use the "$g->read_file"
6060           function and split the buffer into lines yourself.
6061
6062       @entries = $g->readdir ($dir);
6063           This returns the list of directory entries in directory "dir".
6064
6065           All entries in the directory are returned, including "." and "..".
6066           The entries are not sorted, but returned in the same order as the
6067           underlying filesystem.
6068
6069           Also this call returns basic file type information about each file.
6070           The "ftyp" field will contain one of the following characters:
6071
6072           'b' Block special
6073
6074           'c' Char special
6075
6076           'd' Directory
6077
6078           'f' FIFO (named pipe)
6079
6080           'l' Symbolic link
6081
6082           'r' Regular file
6083
6084           's' Socket
6085
6086           'u' Unknown file type
6087
6088           '?' The readdir(3) call returned a "d_type" field with an
6089               unexpected value
6090
6091           This function is primarily intended for use by programs.  To get a
6092           simple list of names, use "$g->ls".  To get a printable directory
6093           for human consumption, use "$g->ll".
6094
6095       $link = $g->readlink ($path);
6096           This command reads the target of a symbolic link.
6097
6098       @links = $g->readlinklist ($path, \@names);
6099           This call allows you to do a "readlink" operation on multiple
6100           files, where all files are in the directory "path".  "names" is the
6101           list of files from this directory.
6102
6103           On return you get a list of strings, with a one-to-one
6104           correspondence to the "names" list.  Each string is the value of
6105           the symbolic link.
6106
6107           If the readlink(2) operation fails on any name, then the
6108           corresponding result string is the empty string "".  However the
6109           whole operation is completed even if there were readlink(2) errors,
6110           and so you can call this function with names where you don't know
6111           if they are symbolic links already (albeit slightly less
6112           efficient).
6113
6114           This call is intended for programs that want to efficiently list a
6115           directory contents without making many round-trips.
6116
6117       $rpath = $g->realpath ($path);
6118           Return the canonicalized absolute pathname of "path".  The returned
6119           path has no ".", ".." or symbolic link path elements.
6120
6121       $g->remount ($mountpoint [, rw => $rw]);
6122           This call allows you to change the "rw" (readonly/read-write) flag
6123           on an already mounted filesystem at "mountpoint", converting a
6124           readonly filesystem to be read-write, or vice-versa.
6125
6126           Note that at the moment you must supply the "optional" "rw"
6127           parameter.  In future we may allow other flags to be adjusted.
6128
6129       $g->remove_drive ($label);
6130           This call does nothing and returns an error.
6131
6132           This function is deprecated.  There is no replacement.  Consult the
6133           API documentation in guestfs(3) for further information.
6134
6135           Deprecated functions will not be removed from the API, but the fact
6136           that they are deprecated indicates that there are problems with
6137           correct use of these functions.
6138
6139       $g->removexattr ($xattr, $path);
6140           This call removes the extended attribute named "xattr" of the file
6141           "path".
6142
6143           See also: "$g->lremovexattr", attr(5).
6144
6145           This function depends on the feature "linuxxattrs".  See also
6146           "$g->feature-available".
6147
6148       $g->rename ($oldpath, $newpath);
6149           Rename a file to a new place on the same filesystem.  This is the
6150           same as the Linux rename(2) system call.  In most cases you are
6151           better to use "$g->mv" instead.
6152
6153       $g->resize2fs ($device);
6154           This resizes an ext2, ext3 or ext4 filesystem to match the size of
6155           the underlying device.
6156
6157           See also "RESIZE2FS ERRORS" in guestfs(3).
6158
6159       $g->resize2fs_M ($device);
6160           This command is the same as "$g->resize2fs", but the filesystem is
6161           resized to its minimum size.  This works like the -M option to the
6162           resize2fs(8) command.
6163
6164           To get the resulting size of the filesystem you should call
6165           "$g->tune2fs_l" and read the "Block size" and "Block count" values.
6166           These two numbers, multiplied together, give the resulting size of
6167           the minimal filesystem in bytes.
6168
6169           See also "RESIZE2FS ERRORS" in guestfs(3).
6170
6171       $g->resize2fs_size ($device, $size);
6172           This command is the same as "$g->resize2fs" except that it allows
6173           you to specify the new size (in bytes) explicitly.
6174
6175           See also "RESIZE2FS ERRORS" in guestfs(3).
6176
6177       $g->rm ($path);
6178           Remove the single file "path".
6179
6180       $g->rm_f ($path);
6181           Remove the file "path".
6182
6183           If the file doesn't exist, that error is ignored.  (Other errors,
6184           eg. I/O errors or bad paths, are not ignored)
6185
6186           This call cannot remove directories.  Use "$g->rmdir" to remove an
6187           empty directory, or "$g->rm_rf" to remove directories recursively.
6188
6189       $g->rm_rf ($path);
6190           Remove the file or directory "path", recursively removing the
6191           contents if its a directory.  This is like the "rm -rf" shell
6192           command.
6193
6194       $g->rmdir ($path);
6195           Remove the single directory "path".
6196
6197       $g->rmmountpoint ($exemptpath);
6198           This call removes a mountpoint that was previously created with
6199           "$g->mkmountpoint".  See "$g->mkmountpoint" for full details.
6200
6201       $g->rsync ($src, $dest [, archive => $archive] [, deletedest =>
6202       $deletedest]);
6203           This call may be used to copy or synchronize two directories under
6204           the same libguestfs handle.  This uses the rsync(1) program which
6205           uses a fast algorithm that avoids copying files unnecessarily.
6206
6207           "src" and "dest" are the source and destination directories.  Files
6208           are copied from "src" to "dest".
6209
6210           The optional arguments are:
6211
6212           "archive"
6213               Turns on archive mode.  This is the same as passing the
6214               --archive flag to "rsync".
6215
6216           "deletedest"
6217               Delete files at the destination that do not exist at the
6218               source.
6219
6220           This function depends on the feature "rsync".  See also
6221           "$g->feature-available".
6222
6223       $g->rsync_in ($remote, $dest [, archive => $archive] [, deletedest =>
6224       $deletedest]);
6225           This call may be used to copy or synchronize the filesystem on the
6226           host or on a remote computer with the filesystem within libguestfs.
6227           This uses the rsync(1) program which uses a fast algorithm that
6228           avoids copying files unnecessarily.
6229
6230           This call only works if the network is enabled.  See
6231           "$g->set_network" or the --network option to various tools like
6232           guestfish(1).
6233
6234           Files are copied from the remote server and directory specified by
6235           "remote" to the destination directory "dest".
6236
6237           The format of the remote server string is defined by rsync(1).
6238           Note that there is no way to supply a password or passphrase so the
6239           target must be set up not to require one.
6240
6241           The optional arguments are the same as those of "$g->rsync".
6242
6243           This function depends on the feature "rsync".  See also
6244           "$g->feature-available".
6245
6246       $g->rsync_out ($src, $remote [, archive => $archive] [, deletedest =>
6247       $deletedest]);
6248           This call may be used to copy or synchronize the filesystem within
6249           libguestfs with a filesystem on the host or on a remote computer.
6250           This uses the rsync(1) program which uses a fast algorithm that
6251           avoids copying files unnecessarily.
6252
6253           This call only works if the network is enabled.  See
6254           "$g->set_network" or the --network option to various tools like
6255           guestfish(1).
6256
6257           Files are copied from the source directory "src" to the remote
6258           server and directory specified by "remote".
6259
6260           The format of the remote server string is defined by rsync(1).
6261           Note that there is no way to supply a password or passphrase so the
6262           target must be set up not to require one.
6263
6264           The optional arguments are the same as those of "$g->rsync".
6265
6266           Globbing does not happen on the "src" parameter.  In programs which
6267           use the API directly you have to expand wildcards yourself (see
6268           "$g->glob_expand").  In guestfish you can use the "glob" command
6269           (see "glob" in guestfish(1)), for example:
6270
6271            ><fs> glob rsync-out /* rsync://remote/
6272
6273           This function depends on the feature "rsync".  See also
6274           "$g->feature-available".
6275
6276       $g->scrub_device ($device);
6277           This command writes patterns over "device" to make data retrieval
6278           more difficult.
6279
6280           It is an interface to the scrub(1) program.  See that manual page
6281           for more details.
6282
6283           This function depends on the feature "scrub".  See also
6284           "$g->feature-available".
6285
6286       $g->scrub_file ($file);
6287           This command writes patterns over a file to make data retrieval
6288           more difficult.
6289
6290           The file is removed after scrubbing.
6291
6292           It is an interface to the scrub(1) program.  See that manual page
6293           for more details.
6294
6295           This function depends on the feature "scrub".  See also
6296           "$g->feature-available".
6297
6298       $g->scrub_freespace ($dir);
6299           This command creates the directory "dir" and then fills it with
6300           files until the filesystem is full, and scrubs the files as for
6301           "$g->scrub_file", and deletes them.  The intention is to scrub any
6302           free space on the partition containing "dir".
6303
6304           It is an interface to the scrub(1) program.  See that manual page
6305           for more details.
6306
6307           This function depends on the feature "scrub".  See also
6308           "$g->feature-available".
6309
6310       $g->selinux_relabel ($specfile, $path [, force => $force]);
6311           SELinux relabel parts of the filesystem.
6312
6313           The "specfile" parameter controls the policy spec file used.  You
6314           have to parse "/etc/selinux/config" to find the correct SELinux
6315           policy and then pass the spec file, usually: "/etc/selinux/" +
6316           selinuxtype + "/contexts/files/file_contexts".
6317
6318           The required "path" parameter is the top level directory where
6319           relabelling starts.  Normally you should pass "path" as "/" to
6320           relabel the whole guest filesystem.
6321
6322           The optional "force" boolean controls whether the context is reset
6323           for customizable files, and also whether the user, role and range
6324           parts of the file context is changed.
6325
6326           This function depends on the feature "selinuxrelabel".  See also
6327           "$g->feature-available".
6328
6329       $g->set_append ($append);
6330           This function is used to add additional options to the libguestfs
6331           appliance kernel command line.
6332
6333           The default is "NULL" unless overridden by setting
6334           "LIBGUESTFS_APPEND" environment variable.
6335
6336           Setting "append" to "NULL" means no additional options are passed
6337           (libguestfs always adds a few of its own).
6338
6339       $g->set_attach_method ($backend);
6340           Set the method that libguestfs uses to connect to the backend
6341           guestfsd daemon.
6342
6343           See "BACKEND" in guestfs(3).
6344
6345           This function is deprecated.  In new code, use the "set_backend"
6346           call instead.
6347
6348           Deprecated functions will not be removed from the API, but the fact
6349           that they are deprecated indicates that there are problems with
6350           correct use of these functions.
6351
6352       $g->set_autosync ($autosync);
6353           If "autosync" is true, this enables autosync.  Libguestfs will make
6354           a best effort attempt to make filesystems consistent and
6355           synchronized when the handle is closed (also if the program exits
6356           without closing handles).
6357
6358           This is enabled by default (since libguestfs 1.5.24, previously it
6359           was disabled by default).
6360
6361       $g->set_backend ($backend);
6362           Set the method that libguestfs uses to connect to the backend
6363           guestfsd daemon.
6364
6365           This handle property was previously called the "attach method".
6366
6367           See "BACKEND" in guestfs(3).
6368
6369       $g->set_backend_setting ($name, $val);
6370           Append "name=value" to the backend settings string list.  However
6371           if a string already exists matching "name" or beginning with
6372           "name=", then that setting is replaced.
6373
6374           See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
6375
6376       $g->set_backend_settings (\@settings);
6377           Set a list of zero or more settings which are passed through to the
6378           current backend.  Each setting is a string which is interpreted in
6379           a backend-specific way, or ignored if not understood by the
6380           backend.
6381
6382           The default value is an empty list, unless the environment variable
6383           "LIBGUESTFS_BACKEND_SETTINGS" was set when the handle was created.
6384           This environment variable contains a colon-separated list of
6385           settings.
6386
6387           This call replaces all backend settings.  If you want to replace a
6388           single backend setting, see "$g->set_backend_setting".  If you want
6389           to clear a single backend setting, see "$g->clear_backend_setting".
6390
6391           See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
6392
6393       $g->set_cachedir ($cachedir);
6394           Set the directory used by the handle to store the appliance cache,
6395           when using a supermin appliance.  The appliance is cached and
6396           shared between all handles which have the same effective user ID.
6397
6398           The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR"
6399           control the default value: If "LIBGUESTFS_CACHEDIR" is set, then
6400           that is the default.  Else if "TMPDIR" is set, then that is the
6401           default.  Else /var/tmp is the default.
6402
6403       $g->set_direct ($direct);
6404           If the direct appliance mode flag is enabled, then stdin and stdout
6405           are passed directly through to the appliance once it is launched.
6406
6407           One consequence of this is that log messages aren't caught by the
6408           library and handled by "$g->set_log_message_callback", but go
6409           straight to stdout.
6410
6411           You probably don't want to use this unless you know what you are
6412           doing.
6413
6414           The default is disabled.
6415
6416           This function is deprecated.  In new code, use the
6417           "internal_get_console_socket" call instead.
6418
6419           Deprecated functions will not be removed from the API, but the fact
6420           that they are deprecated indicates that there are problems with
6421           correct use of these functions.
6422
6423       $g->set_e2attrs ($file, $attrs [, clear => $clear]);
6424           This sets or clears the file attributes "attrs" associated with the
6425           inode file.
6426
6427           "attrs" is a string of characters representing file attributes.
6428           See "$g->get_e2attrs" for a list of possible attributes.  Not all
6429           attributes can be changed.
6430
6431           If optional boolean "clear" is not present or false, then the
6432           "attrs" listed are set in the inode.
6433
6434           If "clear" is true, then the "attrs" listed are cleared in the
6435           inode.
6436
6437           In both cases, other attributes not present in the "attrs" string
6438           are left unchanged.
6439
6440           These attributes are only present when the file is located on an
6441           ext2/3/4 filesystem.  Using this call on other filesystem types
6442           will result in an error.
6443
6444       $g->set_e2generation ($file, $generation);
6445           This sets the ext2 file generation of a file.
6446
6447           See "$g->get_e2generation".
6448
6449       $g->set_e2label ($device, $label);
6450           This sets the ext2/3/4 filesystem label of the filesystem on
6451           "device" to "label".  Filesystem labels are limited to 16
6452           characters.
6453
6454           You can use either "$g->tune2fs_l" or "$g->get_e2label" to return
6455           the existing label on a filesystem.
6456
6457           This function is deprecated.  In new code, use the "set_label" call
6458           instead.
6459
6460           Deprecated functions will not be removed from the API, but the fact
6461           that they are deprecated indicates that there are problems with
6462           correct use of these functions.
6463
6464       $g->set_e2uuid ($device, $uuid);
6465           This sets the ext2/3/4 filesystem UUID of the filesystem on
6466           "device" to "uuid".  The format of the UUID and alternatives such
6467           as "clear", "random" and "time" are described in the tune2fs(8)
6468           manpage.
6469
6470           You can use "$g->vfs_uuid" to return the existing UUID of a
6471           filesystem.
6472
6473           This function is deprecated.  In new code, use the "set_uuid" call
6474           instead.
6475
6476           Deprecated functions will not be removed from the API, but the fact
6477           that they are deprecated indicates that there are problems with
6478           correct use of these functions.
6479
6480       $g->set_hv ($hv);
6481           Set the hypervisor binary that we will use.  The hypervisor depends
6482           on the backend, but is usually the location of the qemu/KVM
6483           hypervisor.
6484
6485           The default is chosen when the library was compiled by the
6486           configure script.
6487
6488           You can also override this by setting the "LIBGUESTFS_HV"
6489           environment variable.
6490
6491           Note that you should call this function as early as possible after
6492           creating the handle.  This is because some pre-launch operations
6493           depend on testing qemu features (by running "qemu -help").  If the
6494           qemu binary changes, we don't retest features, and so you might see
6495           inconsistent results.  Using the environment variable
6496           "LIBGUESTFS_HV" is safest of all since that picks the qemu binary
6497           at the same time as the handle is created.
6498
6499       $g->set_identifier ($identifier);
6500           This is an informative string which the caller may optionally set
6501           in the handle.  It is printed in various places, allowing the
6502           current handle to be identified in debugging output.
6503
6504           One important place is when tracing is enabled.  If the identifier
6505           string is not an empty string, then trace messages change from
6506           this:
6507
6508            libguestfs: trace: get_tmpdir
6509            libguestfs: trace: get_tmpdir = "/tmp"
6510
6511           to this:
6512
6513            libguestfs: trace: ID: get_tmpdir
6514            libguestfs: trace: ID: get_tmpdir = "/tmp"
6515
6516           where "ID" is the identifier string set by this call.
6517
6518           The identifier must only contain alphanumeric ASCII characters,
6519           underscore and minus sign.  The default is the empty string.
6520
6521           See also "$g->set_program", "$g->set_trace", "$g->get_identifier".
6522
6523       $g->set_label ($mountable, $label);
6524           Set the filesystem label on "mountable" to "label".
6525
6526           Only some filesystem types support labels, and libguestfs supports
6527           setting labels on only a subset of these.
6528
6529           ext2, ext3, ext4
6530               Labels are limited to 16 bytes.
6531
6532           NTFS
6533               Labels are limited to 128 unicode characters.
6534
6535           XFS The label is limited to 12 bytes.  The filesystem must not be
6536               mounted when trying to set the label.
6537
6538           btrfs
6539               The label is limited to 255 bytes and some characters are not
6540               allowed.  Setting the label on a btrfs subvolume will set the
6541               label on its parent filesystem.  The filesystem must not be
6542               mounted when trying to set the label.
6543
6544           fat The label is limited to 11 bytes.
6545
6546           swap
6547               The label is limited to 16 bytes.
6548
6549           If there is no support for changing the label for the type of the
6550           specified filesystem, set_label will fail and set errno as ENOTSUP.
6551
6552           To read the label on a filesystem, call "$g->vfs_label".
6553
6554       $g->set_libvirt_requested_credential ($index, $cred);
6555           After requesting the "index"'th credential from the user, call this
6556           function to pass the answer back to libvirt.
6557
6558           See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
6559           example code.
6560
6561       $g->set_libvirt_supported_credentials (\@creds);
6562           Call this function before setting an event handler for
6563           "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential
6564           types that the program knows how to process.
6565
6566           The "creds" list must be a non-empty list of strings.  Possible
6567           strings are:
6568
6569           "username"
6570           "authname"
6571           "language"
6572           "cnonce"
6573           "passphrase"
6574           "echoprompt"
6575           "noechoprompt"
6576           "realm"
6577           "external"
6578
6579           See libvirt documentation for the meaning of these credential
6580           types.
6581
6582           See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
6583           example code.
6584
6585       $g->set_memsize ($memsize);
6586           This sets the memory size in megabytes allocated to the hypervisor.
6587           This only has any effect if called before "$g->launch".
6588
6589           You can also change this by setting the environment variable
6590           "LIBGUESTFS_MEMSIZE" before the handle is created.
6591
6592           For more information on the architecture of libguestfs, see
6593           guestfs(3).
6594
6595       $g->set_network ($network);
6596           If "network" is true, then the network is enabled in the libguestfs
6597           appliance.  The default is false.
6598
6599           This affects whether commands are able to access the network (see
6600           "RUNNING COMMANDS" in guestfs(3)).
6601
6602           You must call this before calling "$g->launch", otherwise it has no
6603           effect.
6604
6605       $g->set_path ($searchpath);
6606           Set the path that libguestfs searches for kernel and initrd.img.
6607
6608           The default is "$libdir/guestfs" unless overridden by setting
6609           "LIBGUESTFS_PATH" environment variable.
6610
6611           Setting "path" to "NULL" restores the default path.
6612
6613       $g->set_pgroup ($pgroup);
6614           If "pgroup" is true, child processes are placed into their own
6615           process group.
6616
6617           The practical upshot of this is that signals like "SIGINT" (from
6618           users pressing "^C") won't be received by the child process.
6619
6620           The default for this flag is false, because usually you want "^C"
6621           to kill the subprocess.  Guestfish sets this flag to true when used
6622           interactively, so that "^C" can cancel long-running commands
6623           gracefully (see "$g->user_cancel").
6624
6625       $g->set_program ($program);
6626           Set the program name.  This is an informative string which the main
6627           program may optionally set in the handle.
6628
6629           When the handle is created, the program name in the handle is set
6630           to the basename from "argv[0]".  The program name can never be
6631           "NULL".
6632
6633       $g->set_qemu ($hv);
6634           Set the hypervisor binary (usually qemu) that we will use.
6635
6636           The default is chosen when the library was compiled by the
6637           configure script.
6638
6639           You can also override this by setting the "LIBGUESTFS_HV"
6640           environment variable.
6641
6642           Setting "hv" to "NULL" restores the default qemu binary.
6643
6644           Note that you should call this function as early as possible after
6645           creating the handle.  This is because some pre-launch operations
6646           depend on testing qemu features (by running "qemu -help").  If the
6647           qemu binary changes, we don't retest features, and so you might see
6648           inconsistent results.  Using the environment variable
6649           "LIBGUESTFS_HV" is safest of all since that picks the qemu binary
6650           at the same time as the handle is created.
6651
6652           This function is deprecated.  In new code, use the "set_hv" call
6653           instead.
6654
6655           Deprecated functions will not be removed from the API, but the fact
6656           that they are deprecated indicates that there are problems with
6657           correct use of these functions.
6658
6659       $g->set_recovery_proc ($recoveryproc);
6660           If this is called with the parameter "false" then "$g->launch" does
6661           not create a recovery process.  The purpose of the recovery process
6662           is to stop runaway hypervisor processes in the case where the main
6663           program aborts abruptly.
6664
6665           This only has any effect if called before "$g->launch", and the
6666           default is true.
6667
6668           About the only time when you would want to disable this is if the
6669           main process will fork itself into the background ("daemonize"
6670           itself).  In this case the recovery process thinks that the main
6671           program has disappeared and so kills the hypervisor, which is not
6672           very helpful.
6673
6674       $g->set_selinux ($selinux);
6675           This sets the selinux flag that is passed to the appliance at boot
6676           time.  The default is "selinux=0" (disabled).
6677
6678           Note that if SELinux is enabled, it is always in Permissive mode
6679           ("enforcing=0").
6680
6681           For more information on the architecture of libguestfs, see
6682           guestfs(3).
6683
6684           This function is deprecated.  In new code, use the
6685           "selinux_relabel" call instead.
6686
6687           Deprecated functions will not be removed from the API, but the fact
6688           that they are deprecated indicates that there are problems with
6689           correct use of these functions.
6690
6691       $g->set_smp ($smp);
6692           Change the number of virtual CPUs assigned to the appliance.  The
6693           default is 1.  Increasing this may improve performance, though
6694           often it has no effect.
6695
6696           This function must be called before "$g->launch".
6697
6698       $g->set_tmpdir ($tmpdir);
6699           Set the directory used by the handle to store temporary files.
6700
6701           The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control
6702           the default value: If "LIBGUESTFS_TMPDIR" is set, then that is the
6703           default.  Else if "TMPDIR" is set, then that is the default.  Else
6704           /tmp is the default.
6705
6706       $g->set_trace ($trace);
6707           If the command trace flag is set to 1, then libguestfs calls,
6708           parameters and return values are traced.
6709
6710           If you want to trace C API calls into libguestfs (and other
6711           libraries) then possibly a better way is to use the external
6712           ltrace(1) command.
6713
6714           Command traces are disabled unless the environment variable
6715           "LIBGUESTFS_TRACE" is defined and set to 1.
6716
6717           Trace messages are normally sent to "stderr", unless you register a
6718           callback to send them somewhere else (see
6719           "$g->set_event_callback").
6720
6721       $g->set_uuid ($device, $uuid);
6722           Set the filesystem UUID on "device" to "uuid".  If this fails and
6723           the errno is ENOTSUP, means that there is no support for changing
6724           the UUID for the type of the specified filesystem.
6725
6726           Only some filesystem types support setting UUIDs.
6727
6728           To read the UUID on a filesystem, call "$g->vfs_uuid".
6729
6730       $g->set_uuid_random ($device);
6731           Set the filesystem UUID on "device" to a random UUID.  If this
6732           fails and the errno is ENOTSUP, means that there is no support for
6733           changing the UUID for the type of the specified filesystem.
6734
6735           Only some filesystem types support setting UUIDs.
6736
6737           To read the UUID on a filesystem, call "$g->vfs_uuid".
6738
6739       $g->set_verbose ($verbose);
6740           If "verbose" is true, this turns on verbose messages.
6741
6742           Verbose messages are disabled unless the environment variable
6743           "LIBGUESTFS_DEBUG" is defined and set to 1.
6744
6745           Verbose messages are normally sent to "stderr", unless you register
6746           a callback to send them somewhere else (see
6747           "$g->set_event_callback").
6748
6749       $g->setcon ($context);
6750           This sets the SELinux security context of the daemon to the string
6751           "context".
6752
6753           See the documentation about SELINUX in guestfs(3).
6754
6755           This function depends on the feature "selinux".  See also
6756           "$g->feature-available".
6757
6758           This function is deprecated.  In new code, use the
6759           "selinux_relabel" call instead.
6760
6761           Deprecated functions will not be removed from the API, but the fact
6762           that they are deprecated indicates that there are problems with
6763           correct use of these functions.
6764
6765       $g->setxattr ($xattr, $val, $vallen, $path);
6766           This call sets the extended attribute named "xattr" of the file
6767           "path" to the value "val" (of length "vallen").  The value is
6768           arbitrary 8 bit data.
6769
6770           See also: "$g->lsetxattr", attr(5).
6771
6772           This function depends on the feature "linuxxattrs".  See also
6773           "$g->feature-available".
6774
6775       $g->sfdisk ($device, $cyls, $heads, $sectors, \@lines);
6776           This is a direct interface to the sfdisk(8) program for creating
6777           partitions on block devices.
6778
6779           "device" should be a block device, for example /dev/sda.
6780
6781           "cyls", "heads" and "sectors" are the number of cylinders, heads
6782           and sectors on the device, which are passed directly to sfdisk(8)
6783           as the -C, -H and -S parameters.  If you pass 0 for any of these,
6784           then the corresponding parameter is omitted.  Usually for ‘large’
6785           disks, you can just pass 0 for these, but for small (floppy-sized)
6786           disks, sfdisk(8) (or rather, the kernel) cannot work out the right
6787           geometry and you will need to tell it.
6788
6789           "lines" is a list of lines that we feed to sfdisk(8).  For more
6790           information refer to the sfdisk(8) manpage.
6791
6792           To create a single partition occupying the whole disk, you would
6793           pass "lines" as a single element list, when the single element
6794           being the string "," (comma).
6795
6796           See also: "$g->sfdisk_l", "$g->sfdisk_N", "$g->part_init"
6797
6798           This function is deprecated.  In new code, use the "part_add" call
6799           instead.
6800
6801           Deprecated functions will not be removed from the API, but the fact
6802           that they are deprecated indicates that there are problems with
6803           correct use of these functions.
6804
6805       $g->sfdiskM ($device, \@lines);
6806           This is a simplified interface to the "$g->sfdisk" command, where
6807           partition sizes are specified in megabytes only (rounded to the
6808           nearest cylinder) and you don't need to specify the cyls, heads and
6809           sectors parameters which were rarely if ever used anyway.
6810
6811           See also: "$g->sfdisk", the sfdisk(8) manpage and "$g->part_disk"
6812
6813           This function is deprecated.  In new code, use the "part_add" call
6814           instead.
6815
6816           Deprecated functions will not be removed from the API, but the fact
6817           that they are deprecated indicates that there are problems with
6818           correct use of these functions.
6819
6820       $g->sfdisk_N ($device, $partnum, $cyls, $heads, $sectors, $line);
6821           This runs sfdisk(8) option to modify just the single partition "n"
6822           (note: "n" counts from 1).
6823
6824           For other parameters, see "$g->sfdisk".  You should usually pass 0
6825           for the cyls/heads/sectors parameters.
6826
6827           See also: "$g->part_add"
6828
6829           This function is deprecated.  In new code, use the "part_add" call
6830           instead.
6831
6832           Deprecated functions will not be removed from the API, but the fact
6833           that they are deprecated indicates that there are problems with
6834           correct use of these functions.
6835
6836       $partitions = $g->sfdisk_disk_geometry ($device);
6837           This displays the disk geometry of "device" read from the partition
6838           table.  Especially in the case where the underlying block device
6839           has been resized, this can be different from the kernel’s idea of
6840           the geometry (see "$g->sfdisk_kernel_geometry").
6841
6842           The result is in human-readable format, and not designed to be
6843           parsed.
6844
6845       $partitions = $g->sfdisk_kernel_geometry ($device);
6846           This displays the kernel’s idea of the geometry of "device".
6847
6848           The result is in human-readable format, and not designed to be
6849           parsed.
6850
6851       $partitions = $g->sfdisk_l ($device);
6852           This displays the partition table on "device", in the human-
6853           readable output of the sfdisk(8) command.  It is not intended to be
6854           parsed.
6855
6856           See also: "$g->part_list"
6857
6858           This function is deprecated.  In new code, use the "part_list" call
6859           instead.
6860
6861           Deprecated functions will not be removed from the API, but the fact
6862           that they are deprecated indicates that there are problems with
6863           correct use of these functions.
6864
6865       $output = $g->sh ($command);
6866           This call runs a command from the guest filesystem via the guest’s
6867           /bin/sh.
6868
6869           This is like "$g->command", but passes the command to:
6870
6871            /bin/sh -c "command"
6872
6873           Depending on the guest’s shell, this usually results in wildcards
6874           being expanded, shell expressions being interpolated and so on.
6875
6876           All the provisos about "$g->command" apply to this call.
6877
6878       @lines = $g->sh_lines ($command);
6879           This is the same as "$g->sh", but splits the result into a list of
6880           lines.
6881
6882           See also: "$g->command_lines"
6883
6884       $g->shutdown ();
6885           This is the opposite of "$g->launch".  It performs an orderly
6886           shutdown of the backend process(es).  If the autosync flag is set
6887           (which is the default) then the disk image is synchronized.
6888
6889           If the subprocess exits with an error then this function will
6890           return an error, which should not be ignored (it may indicate that
6891           the disk image could not be written out properly).
6892
6893           It is safe to call this multiple times.  Extra calls are ignored.
6894
6895           This call does not close or free up the handle.  You still need to
6896           call "$g->close" afterwards.
6897
6898           "$g->close" will call this if you don't do it explicitly, but note
6899           that any errors are ignored in that case.
6900
6901       $g->sleep ($secs);
6902           Sleep for "secs" seconds.
6903
6904       %statbuf = $g->stat ($path);
6905           Returns file information for the given "path".
6906
6907           This is the same as the stat(2) system call.
6908
6909           This function is deprecated.  In new code, use the "statns" call
6910           instead.
6911
6912           Deprecated functions will not be removed from the API, but the fact
6913           that they are deprecated indicates that there are problems with
6914           correct use of these functions.
6915
6916       %statbuf = $g->statns ($path);
6917           Returns file information for the given "path".
6918
6919           This is the same as the stat(2) system call.
6920
6921       %statbuf = $g->statvfs ($path);
6922           Returns file system statistics for any mounted file system.  "path"
6923           should be a file or directory in the mounted file system (typically
6924           it is the mount point itself, but it doesn't need to be).
6925
6926           This is the same as the statvfs(2) system call.
6927
6928       @stringsout = $g->strings ($path);
6929           This runs the strings(1) command on a file and returns the list of
6930           printable strings found.
6931
6932           The "strings" command has, in the past, had problems with parsing
6933           untrusted files.  These are mitigated in the current version of
6934           libguestfs, but see "CVE-2014-8484" in guestfs(3).
6935
6936           Because of the message protocol, there is a transfer limit of
6937           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
6938           guestfs(3).
6939
6940       @stringsout = $g->strings_e ($encoding, $path);
6941           This is like the "$g->strings" command, but allows you to specify
6942           the encoding of strings that are looked for in the source file
6943           "path".
6944
6945           Allowed encodings are:
6946
6947           s   Single 7-bit-byte characters like ASCII and the ASCII-
6948               compatible parts of ISO-8859-X (this is what "$g->strings"
6949               uses).
6950
6951           S   Single 8-bit-byte characters.
6952
6953           b   16-bit big endian strings such as those encoded in UTF-16BE or
6954               UCS-2BE.
6955
6956           l (lower case letter L)
6957               16-bit little endian such as UTF-16LE and UCS-2LE.  This is
6958               useful for examining binaries in Windows guests.
6959
6960           B   32-bit big endian such as UCS-4BE.
6961
6962           L   32-bit little endian such as UCS-4LE.
6963
6964           The returned strings are transcoded to UTF-8.
6965
6966           The "strings" command has, in the past, had problems with parsing
6967           untrusted files.  These are mitigated in the current version of
6968           libguestfs, but see "CVE-2014-8484" in guestfs(3).
6969
6970           Because of the message protocol, there is a transfer limit of
6971           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
6972           guestfs(3).
6973
6974       $g->swapoff_device ($device);
6975           This command disables the libguestfs appliance swap device or
6976           partition named "device".  See "$g->swapon_device".
6977
6978       $g->swapoff_file ($file);
6979           This command disables the libguestfs appliance swap on file.
6980
6981       $g->swapoff_label ($label);
6982           This command disables the libguestfs appliance swap on labeled swap
6983           partition.
6984
6985       $g->swapoff_uuid ($uuid);
6986           This command disables the libguestfs appliance swap partition with
6987           the given UUID.
6988
6989           This function depends on the feature "linuxfsuuid".  See also
6990           "$g->feature-available".
6991
6992       $g->swapon_device ($device);
6993           This command enables the libguestfs appliance to use the swap
6994           device or partition named "device".  The increased memory is made
6995           available for all commands, for example those run using
6996           "$g->command" or "$g->sh".
6997
6998           Note that you should not swap to existing guest swap partitions
6999           unless you know what you are doing.  They may contain hibernation
7000           information, or other information that the guest doesn't want you
7001           to trash.  You also risk leaking information about the host to the
7002           guest this way.  Instead, attach a new host device to the guest and
7003           swap on that.
7004
7005       $g->swapon_file ($file);
7006           This command enables swap to a file.  See "$g->swapon_device" for
7007           other notes.
7008
7009       $g->swapon_label ($label);
7010           This command enables swap to a labeled swap partition.  See
7011           "$g->swapon_device" for other notes.
7012
7013       $g->swapon_uuid ($uuid);
7014           This command enables swap to a swap partition with the given UUID.
7015           See "$g->swapon_device" for other notes.
7016
7017           This function depends on the feature "linuxfsuuid".  See also
7018           "$g->feature-available".
7019
7020       $g->sync ();
7021           This syncs the disk, so that any writes are flushed through to the
7022           underlying disk image.
7023
7024           You should always call this if you have modified a disk image,
7025           before closing the handle.
7026
7027       $g->syslinux ($device [, directory => $directory]);
7028           Install the SYSLINUX bootloader on "device".
7029
7030           The device parameter must be either a whole disk formatted as a FAT
7031           filesystem, or a partition formatted as a FAT filesystem.  In the
7032           latter case, the partition should be marked as "active"
7033           ("$g->part_set_bootable") and a Master Boot Record must be
7034           installed (eg. using "$g->pwrite_device") on the first sector of
7035           the whole disk.  The SYSLINUX package comes with some suitable
7036           Master Boot Records.  See the syslinux(1) man page for further
7037           information.
7038
7039           The optional arguments are:
7040
7041           directory
7042               Install SYSLINUX in the named subdirectory, instead of in the
7043               root directory of the FAT filesystem.
7044
7045           Additional configuration can be supplied to SYSLINUX by placing a
7046           file called syslinux.cfg on the FAT filesystem, either in the root
7047           directory, or under directory if that optional argument is being
7048           used.  For further information about the contents of this file, see
7049           syslinux(1).
7050
7051           See also "$g->extlinux".
7052
7053           This function depends on the feature "syslinux".  See also
7054           "$g->feature-available".
7055
7056       @lines = $g->tail ($path);
7057           This command returns up to the last 10 lines of a file as a list of
7058           strings.
7059
7060           Because of the message protocol, there is a transfer limit of
7061           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
7062           guestfs(3).
7063
7064       @lines = $g->tail_n ($nrlines, $path);
7065           If the parameter "nrlines" is a positive number, this returns the
7066           last "nrlines" lines of the file "path".
7067
7068           If the parameter "nrlines" is a negative number, this returns lines
7069           from the file "path", starting with the "-nrlines"'th line.
7070
7071           If the parameter "nrlines" is zero, this returns an empty list.
7072
7073           Because of the message protocol, there is a transfer limit of
7074           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
7075           guestfs(3).
7076
7077       $g->tar_in ($tarfile, $directory [, compress => $compress] [, xattrs =>
7078       $xattrs] [, selinux => $selinux] [, acls => $acls]);
7079           This command uploads and unpacks local file "tarfile" into
7080           directory.
7081
7082           The optional "compress" flag controls compression.  If not given,
7083           then the input should be an uncompressed tar file.  Otherwise one
7084           of the following strings may be given to select the compression
7085           type of the input file: "compress", "gzip", "bzip2", "xz", "lzop".
7086           (Note that not all builds of libguestfs will support all of these
7087           compression types).
7088
7089           The other optional arguments are:
7090
7091           "xattrs"
7092               If set to true, extended attributes are restored from the tar
7093               file.
7094
7095           "selinux"
7096               If set to true, SELinux contexts are restored from the tar
7097               file.
7098
7099           "acls"
7100               If set to true, POSIX ACLs are restored from the tar file.
7101
7102       $g->tar_in_opts ($tarfile, $directory [, compress => $compress] [,
7103       xattrs => $xattrs] [, selinux => $selinux] [, acls => $acls]);
7104           This is an alias of "tar_in".
7105
7106       $g->tar_out ($directory, $tarfile [, compress => $compress] [,
7107       numericowner => $numericowner] [, excludes => $excludes] [, xattrs =>
7108       $xattrs] [, selinux => $selinux] [, acls => $acls]);
7109           This command packs the contents of directory and downloads it to
7110           local file "tarfile".
7111
7112           The optional "compress" flag controls compression.  If not given,
7113           then the output will be an uncompressed tar file.  Otherwise one of
7114           the following strings may be given to select the compression type
7115           of the output file: "compress", "gzip", "bzip2", "xz", "lzop".
7116           (Note that not all builds of libguestfs will support all of these
7117           compression types).
7118
7119           The other optional arguments are:
7120
7121           "excludes"
7122               A list of wildcards.  Files are excluded if they match any of
7123               the wildcards.
7124
7125           "numericowner"
7126               If set to true, the output tar file will contain UID/GID
7127               numbers instead of user/group names.
7128
7129           "xattrs"
7130               If set to true, extended attributes are saved in the output
7131               tar.
7132
7133           "selinux"
7134               If set to true, SELinux contexts are saved in the output tar.
7135
7136           "acls"
7137               If set to true, POSIX ACLs are saved in the output tar.
7138
7139       $g->tar_out_opts ($directory, $tarfile [, compress => $compress] [,
7140       numericowner => $numericowner] [, excludes => $excludes] [, xattrs =>
7141       $xattrs] [, selinux => $selinux] [, acls => $acls]);
7142           This is an alias of "tar_out".
7143
7144       $g->tgz_in ($tarball, $directory);
7145           This command uploads and unpacks local file "tarball" (a gzip
7146           compressed tar file) into directory.
7147
7148           This function is deprecated.  In new code, use the "tar_in" call
7149           instead.
7150
7151           Deprecated functions will not be removed from the API, but the fact
7152           that they are deprecated indicates that there are problems with
7153           correct use of these functions.
7154
7155       $g->tgz_out ($directory, $tarball);
7156           This command packs the contents of directory and downloads it to
7157           local file "tarball".
7158
7159           This function is deprecated.  In new code, use the "tar_out" call
7160           instead.
7161
7162           Deprecated functions will not be removed from the API, but the fact
7163           that they are deprecated indicates that there are problems with
7164           correct use of these functions.
7165
7166       $g->touch ($path);
7167           Touch acts like the touch(1) command.  It can be used to update the
7168           timestamps on a file, or, if the file does not exist, to create a
7169           new zero-length file.
7170
7171           This command only works on regular files, and will fail on other
7172           file types such as directories, symbolic links, block special etc.
7173
7174       $g->truncate ($path);
7175           This command truncates "path" to a zero-length file.  The file must
7176           exist already.
7177
7178       $g->truncate_size ($path, $size);
7179           This command truncates "path" to size "size" bytes.  The file must
7180           exist already.
7181
7182           If the current file size is less than "size" then the file is
7183           extended to the required size with zero bytes.  This creates a
7184           sparse file (ie. disk blocks are not allocated for the file until
7185           you write to it).  To create a non-sparse file of zeroes, use
7186           "$g->fallocate64" instead.
7187
7188       $g->tune2fs ($device [, force => $force] [, maxmountcount =>
7189       $maxmountcount] [, mountcount => $mountcount] [, errorbehavior =>
7190       $errorbehavior] [, group => $group] [, intervalbetweenchecks =>
7191       $intervalbetweenchecks] [, reservedblockspercentage =>
7192       $reservedblockspercentage] [, lastmounteddirectory =>
7193       $lastmounteddirectory] [, reservedblockscount => $reservedblockscount]
7194       [, user => $user]);
7195           This call allows you to adjust various filesystem parameters of an
7196           ext2/ext3/ext4 filesystem called "device".
7197
7198           The optional parameters are:
7199
7200           "force"
7201               Force tune2fs to complete the operation even in the face of
7202               errors.  This is the same as the tune2fs(8) "-f" option.
7203
7204           "maxmountcount"
7205               Set the number of mounts after which the filesystem is checked
7206               by e2fsck(8).  If this is 0 then the number of mounts is
7207               disregarded.  This is the same as the tune2fs(8) "-c" option.
7208
7209           "mountcount"
7210               Set the number of times the filesystem has been mounted.  This
7211               is the same as the tune2fs(8) "-C" option.
7212
7213           "errorbehavior"
7214               Change the behavior of the kernel code when errors are
7215               detected.  Possible values currently are: "continue",
7216               "remount-ro", "panic".  In practice these options don't really
7217               make any difference, particularly for write errors.
7218
7219               This is the same as the tune2fs(8) "-e" option.
7220
7221           "group"
7222               Set the group which can use reserved filesystem blocks.  This
7223               is the same as the tune2fs(8) "-g" option except that it can
7224               only be specified as a number.
7225
7226           "intervalbetweenchecks"
7227               Adjust the maximal time between two filesystem checks (in
7228               seconds).  If the option is passed as 0 then time-dependent
7229               checking is disabled.
7230
7231               This is the same as the tune2fs(8) "-i" option.
7232
7233           "reservedblockspercentage"
7234               Set the percentage of the filesystem which may only be
7235               allocated by privileged processes.  This is the same as the
7236               tune2fs(8) "-m" option.
7237
7238           "lastmounteddirectory"
7239               Set the last mounted directory.  This is the same as the
7240               tune2fs(8) "-M" option.
7241
7242           "reservedblockscount" Set the number of reserved filesystem blocks.
7243           This is the same as the tune2fs(8) "-r" option.
7244           "user"
7245               Set the user who can use the reserved filesystem blocks.  This
7246               is the same as the tune2fs(8) "-u" option except that it can
7247               only be specified as a number.
7248
7249           To get the current values of filesystem parameters, see
7250           "$g->tune2fs_l".  For precise details of how tune2fs works, see the
7251           tune2fs(8) man page.
7252
7253       %superblock = $g->tune2fs_l ($device);
7254           This returns the contents of the ext2, ext3 or ext4 filesystem
7255           superblock on "device".
7256
7257           It is the same as running "tune2fs -l device".  See tune2fs(8)
7258           manpage for more details.  The list of fields returned isn't
7259           clearly defined, and depends on both the version of "tune2fs" that
7260           libguestfs was built against, and the filesystem itself.
7261
7262       $g->txz_in ($tarball, $directory);
7263           This command uploads and unpacks local file "tarball" (an xz
7264           compressed tar file) into directory.
7265
7266           This function depends on the feature "xz".  See also
7267           "$g->feature-available".
7268
7269           This function is deprecated.  In new code, use the "tar_in" call
7270           instead.
7271
7272           Deprecated functions will not be removed from the API, but the fact
7273           that they are deprecated indicates that there are problems with
7274           correct use of these functions.
7275
7276       $g->txz_out ($directory, $tarball);
7277           This command packs the contents of directory and downloads it to
7278           local file "tarball" (as an xz compressed tar archive).
7279
7280           This function depends on the feature "xz".  See also
7281           "$g->feature-available".
7282
7283           This function is deprecated.  In new code, use the "tar_out" call
7284           instead.
7285
7286           Deprecated functions will not be removed from the API, but the fact
7287           that they are deprecated indicates that there are problems with
7288           correct use of these functions.
7289
7290       $oldmask = $g->umask ($mask);
7291           This function sets the mask used for creating new files and device
7292           nodes to "mask & 0777".
7293
7294           Typical umask values would be 022 which creates new files with
7295           permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which
7296           creates new files with permissions like "-rw-rw-r--" or
7297           "-rwxrwxr-x".
7298
7299           The default umask is 022.  This is important because it means that
7300           directories and device nodes will be created with 0644 or 0755 mode
7301           even if you specify 0777.
7302
7303           See also "$g->get_umask", umask(2), "$g->mknod", "$g->mkdir".
7304
7305           This call returns the previous umask.
7306
7307       $g->umount ($pathordevice [, force => $force] [, lazyunmount =>
7308       $lazyunmount]);
7309           This unmounts the given filesystem.  The filesystem may be
7310           specified either by its mountpoint (path) or the device which
7311           contains the filesystem.
7312
7313       $g->umount_opts ($pathordevice [, force => $force] [, lazyunmount =>
7314       $lazyunmount]);
7315           This is an alias of "umount".
7316
7317       $g->umount_all ();
7318           This unmounts all mounted filesystems.
7319
7320           Some internal mounts are not unmounted by this call.
7321
7322       $g->umount_local ([retry => $retry]);
7323           If libguestfs is exporting the filesystem on a local mountpoint,
7324           then this unmounts it.
7325
7326           See "MOUNT LOCAL" in guestfs(3) for full documentation.
7327
7328       $g->upload ($filename, $remotefilename);
7329           Upload local file filename to remotefilename on the filesystem.
7330
7331           filename can also be a named pipe.
7332
7333           See also "$g->download".
7334
7335       $g->upload_offset ($filename, $remotefilename, $offset);
7336           Upload local file filename to remotefilename on the filesystem.
7337
7338           remotefilename is overwritten starting at the byte "offset"
7339           specified.  The intention is to overwrite parts of existing files
7340           or devices, although if a non-existent file is specified then it is
7341           created with a "hole" before "offset".  The size of the data
7342           written is implicit in the size of the source filename.
7343
7344           Note that there is no limit on the amount of data that can be
7345           uploaded with this call, unlike with "$g->pwrite", and this call
7346           always writes the full amount unless an error occurs.
7347
7348           See also "$g->upload", "$g->pwrite".
7349
7350       $g->user_cancel ();
7351           This function cancels the current upload or download operation.
7352
7353           Unlike most other libguestfs calls, this function is signal safe
7354           and thread safe.  You can call it from a signal handler or from
7355           another thread, without needing to do any locking.
7356
7357           The transfer that was in progress (if there is one) will stop
7358           shortly afterwards, and will return an error.  The errno (see
7359           "guestfs_last_errno") is set to "EINTR", so you can test for this
7360           to find out if the operation was cancelled or failed because of
7361           another error.
7362
7363           No cleanup is performed: for example, if a file was being uploaded
7364           then after cancellation there may be a partially uploaded file.  It
7365           is the caller’s responsibility to clean up if necessary.
7366
7367           There are two common places that you might call "$g->user_cancel":
7368
7369           In an interactive text-based program, you might call it from a
7370           "SIGINT" signal handler so that pressing "^C" cancels the current
7371           operation.  (You also need to call "$g->set_pgroup" so that child
7372           processes don't receive the "^C" signal).
7373
7374           In a graphical program, when the main thread is displaying a
7375           progress bar with a cancel button, wire up the cancel button to
7376           call this function.
7377
7378       $g->utimens ($path, $atsecs, $atnsecs, $mtsecs, $mtnsecs);
7379           This command sets the timestamps of a file with nanosecond
7380           precision.
7381
7382           "atsecs", "atnsecs" are the last access time (atime) in secs and
7383           nanoseconds from the epoch.
7384
7385           "mtsecs", "mtnsecs" are the last modification time (mtime) in secs
7386           and nanoseconds from the epoch.
7387
7388           If the *nsecs field contains the special value -1 then the
7389           corresponding timestamp is set to the current time.  (The *secs
7390           field is ignored in this case).
7391
7392           If the *nsecs field contains the special value -2 then the
7393           corresponding timestamp is left unchanged.  (The *secs field is
7394           ignored in this case).
7395
7396       %uts = $g->utsname ();
7397           This returns the kernel version of the appliance, where this is
7398           available.  This information is only useful for debugging.  Nothing
7399           in the returned structure is defined by the API.
7400
7401       %version = $g->version ();
7402           Return the libguestfs version number that the program is linked
7403           against.
7404
7405           Note that because of dynamic linking this is not necessarily the
7406           version of libguestfs that you compiled against.  You can compile
7407           the program, and then at runtime dynamically link against a
7408           completely different libguestfs.so library.
7409
7410           This call was added in version 1.0.58.  In previous versions of
7411           libguestfs there was no way to get the version number.  From C code
7412           you can use dynamic linker functions to find out if this symbol
7413           exists (if it doesn't, then it’s an earlier version).
7414
7415           The call returns a structure with four elements.  The first three
7416           ("major", "minor" and "release") are numbers and correspond to the
7417           usual version triplet.  The fourth element ("extra") is a string
7418           and is normally empty, but may be used for distro-specific
7419           information.
7420
7421           To construct the original version string:
7422           "$major.$minor.$release$extra"
7423
7424           See also: "LIBGUESTFS VERSION NUMBERS" in guestfs(3).
7425
7426           Note: Don't use this call to test for availability of features.  In
7427           enterprise distributions we backport features from later versions
7428           into earlier versions, making this an unreliable way to test for
7429           features.  Use "$g->available" or "$g->feature_available" instead.
7430
7431       $label = $g->vfs_label ($mountable);
7432           This returns the label of the filesystem on "mountable".
7433
7434           If the filesystem is unlabeled, this returns the empty string.
7435
7436           To find a filesystem from the label, use "$g->findfs_label".
7437
7438       $sizeinbytes = $g->vfs_minimum_size ($mountable);
7439           Get the minimum size of filesystem in bytes.  This is the minimum
7440           possible size for filesystem shrinking.
7441
7442           If getting minimum size of specified filesystem is not supported,
7443           this will fail and set errno as ENOTSUP.
7444
7445           See also ntfsresize(8), resize2fs(8), btrfs(8), xfs_info(8).
7446
7447       $fstype = $g->vfs_type ($mountable);
7448           This command gets the filesystem type corresponding to the
7449           filesystem on "mountable".
7450
7451           For most filesystems, the result is the name of the Linux VFS
7452           module which would be used to mount this filesystem if you mounted
7453           it without specifying the filesystem type.  For example a string
7454           such as "ext3" or "ntfs".
7455
7456       $uuid = $g->vfs_uuid ($mountable);
7457           This returns the filesystem UUID of the filesystem on "mountable".
7458
7459           If the filesystem does not have a UUID, this returns the empty
7460           string.
7461
7462           To find a filesystem from the UUID, use "$g->findfs_uuid".
7463
7464       $g->vg_activate ($activate, \@volgroups);
7465           This command activates or (if "activate" is false) deactivates all
7466           logical volumes in the listed volume groups "volgroups".
7467
7468           This command is the same as running "vgchange -a y|n volgroups..."
7469
7470           Note that if "volgroups" is an empty list then all volume groups
7471           are activated or deactivated.
7472
7473           This function depends on the feature "lvm2".  See also
7474           "$g->feature-available".
7475
7476       $g->vg_activate_all ($activate);
7477           This command activates or (if "activate" is false) deactivates all
7478           logical volumes in all volume groups.
7479
7480           This command is the same as running "vgchange -a y|n"
7481
7482           This function depends on the feature "lvm2".  See also
7483           "$g->feature-available".
7484
7485       $g->vgchange_uuid ($vg);
7486           Generate a new random UUID for the volume group "vg".
7487
7488           This function depends on the feature "lvm2".  See also
7489           "$g->feature-available".
7490
7491       $g->vgchange_uuid_all ();
7492           Generate new random UUIDs for all volume groups.
7493
7494           This function depends on the feature "lvm2".  See also
7495           "$g->feature-available".
7496
7497       $g->vgcreate ($volgroup, \@physvols);
7498           This creates an LVM volume group called "volgroup" from the non-
7499           empty list of physical volumes "physvols".
7500
7501           This function depends on the feature "lvm2".  See also
7502           "$g->feature-available".
7503
7504       @uuids = $g->vglvuuids ($vgname);
7505           Given a VG called "vgname", this returns the UUIDs of all the
7506           logical volumes created in this volume group.
7507
7508           You can use this along with "$g->lvs" and "$g->lvuuid" calls to
7509           associate logical volumes and volume groups.
7510
7511           See also "$g->vgpvuuids".
7512
7513       $metadata = $g->vgmeta ($vgname);
7514           "vgname" is an LVM volume group.  This command examines the volume
7515           group and returns its metadata.
7516
7517           Note that the metadata is an internal structure used by LVM,
7518           subject to change at any time, and is provided for information
7519           only.
7520
7521           This function depends on the feature "lvm2".  See also
7522           "$g->feature-available".
7523
7524       @uuids = $g->vgpvuuids ($vgname);
7525           Given a VG called "vgname", this returns the UUIDs of all the
7526           physical volumes that this volume group resides on.
7527
7528           You can use this along with "$g->pvs" and "$g->pvuuid" calls to
7529           associate physical volumes and volume groups.
7530
7531           See also "$g->vglvuuids".
7532
7533       $g->vgremove ($vgname);
7534           Remove an LVM volume group "vgname", (for example "VG").
7535
7536           This also forcibly removes all logical volumes in the volume group
7537           (if any).
7538
7539           This function depends on the feature "lvm2".  See also
7540           "$g->feature-available".
7541
7542       $g->vgrename ($volgroup, $newvolgroup);
7543           Rename a volume group "volgroup" with the new name "newvolgroup".
7544
7545       @volgroups = $g->vgs ();
7546           List all the volumes groups detected.  This is the equivalent of
7547           the vgs(8) command.
7548
7549           This returns a list of just the volume group names that were
7550           detected (eg. "VolGroup00").
7551
7552           See also "$g->vgs_full".
7553
7554           This function depends on the feature "lvm2".  See also
7555           "$g->feature-available".
7556
7557       @volgroups = $g->vgs_full ();
7558           List all the volumes groups detected.  This is the equivalent of
7559           the vgs(8) command.  The "full" version includes all fields.
7560
7561           This function depends on the feature "lvm2".  See also
7562           "$g->feature-available".
7563
7564       $g->vgscan ();
7565           This rescans all block devices and rebuilds the list of LVM
7566           physical volumes, volume groups and logical volumes.
7567
7568           This function is deprecated.  In new code, use the "lvm_scan" call
7569           instead.
7570
7571           Deprecated functions will not be removed from the API, but the fact
7572           that they are deprecated indicates that there are problems with
7573           correct use of these functions.
7574
7575       $uuid = $g->vguuid ($vgname);
7576           This command returns the UUID of the LVM VG named "vgname".
7577
7578       $g->wait_ready ();
7579           This function is a no op.
7580
7581           In versions of the API < 1.0.71 you had to call this function just
7582           after calling "$g->launch" to wait for the launch to complete.
7583           However this is no longer necessary because "$g->launch" now does
7584           the waiting.
7585
7586           If you see any calls to this function in code then you can just
7587           remove them, unless you want to retain compatibility with older
7588           versions of the API.
7589
7590           This function is deprecated.  There is no replacement.  Consult the
7591           API documentation in guestfs(3) for further information.
7592
7593           Deprecated functions will not be removed from the API, but the fact
7594           that they are deprecated indicates that there are problems with
7595           correct use of these functions.
7596
7597       $chars = $g->wc_c ($path);
7598           This command counts the characters in a file, using the "wc -c"
7599           external command.
7600
7601       $lines = $g->wc_l ($path);
7602           This command counts the lines in a file, using the "wc -l" external
7603           command.
7604
7605       $words = $g->wc_w ($path);
7606           This command counts the words in a file, using the "wc -w" external
7607           command.
7608
7609       $g->wipefs ($device);
7610           This command erases filesystem or RAID signatures from the
7611           specified "device" to make the filesystem invisible to libblkid.
7612
7613           This does not erase the filesystem itself nor any other data from
7614           the "device".
7615
7616           Compare with "$g->zero" which zeroes the first few blocks of a
7617           device.
7618
7619           This function depends on the feature "wipefs".  See also
7620           "$g->feature-available".
7621
7622       $g->write ($path, $content);
7623           This call creates a file called "path".  The content of the file is
7624           the string "content" (which can contain any 8 bit data).
7625
7626           See also "$g->write_append".
7627
7628       $g->write_append ($path, $content);
7629           This call appends "content" to the end of file "path".  If "path"
7630           does not exist, then a new file is created.
7631
7632           See also "$g->write".
7633
7634       $g->write_file ($path, $content, $size);
7635           This call creates a file called "path".  The contents of the file
7636           is the string "content" (which can contain any 8 bit data), with
7637           length "size".
7638
7639           As a special case, if "size" is 0 then the length is calculated
7640           using "strlen" (so in this case the content cannot contain embedded
7641           ASCII NULs).
7642
7643           NB. Owing to a bug, writing content containing ASCII NUL characters
7644           does not work, even if the length is specified.
7645
7646           Because of the message protocol, there is a transfer limit of
7647           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
7648           guestfs(3).
7649
7650           This function is deprecated.  In new code, use the "write" call
7651           instead.
7652
7653           Deprecated functions will not be removed from the API, but the fact
7654           that they are deprecated indicates that there are problems with
7655           correct use of these functions.
7656
7657       $g->xfs_admin ($device [, extunwritten => $extunwritten] [, imgfile =>
7658       $imgfile] [, v2log => $v2log] [, projid32bit => $projid32bit] [,
7659       lazycounter => $lazycounter] [, label => $label] [, uuid => $uuid]);
7660           Change the parameters of the XFS filesystem on "device".
7661
7662           Devices that are mounted cannot be modified.  Administrators must
7663           unmount filesystems before this call can modify parameters.
7664
7665           Some of the parameters of a mounted filesystem can be examined and
7666           modified using the "$g->xfs_info" and "$g->xfs_growfs" calls.
7667
7668           Beginning with XFS version 5, it is no longer possible to modify
7669           the lazy-counters setting (ie. "lazycounter" parameter has no
7670           effect).
7671
7672           This function depends on the feature "xfs".  See also
7673           "$g->feature-available".
7674
7675       $g->xfs_growfs ($path [, datasec => $datasec] [, logsec => $logsec] [,
7676       rtsec => $rtsec] [, datasize => $datasize] [, logsize => $logsize] [,
7677       rtsize => $rtsize] [, rtextsize => $rtextsize] [, maxpct => $maxpct]);
7678           Grow the XFS filesystem mounted at "path".
7679
7680           The returned struct contains geometry information.  Missing fields
7681           are returned as -1 (for numeric fields) or empty string.
7682
7683           This function depends on the feature "xfs".  See also
7684           "$g->feature-available".
7685
7686       %info = $g->xfs_info ($pathordevice);
7687           "pathordevice" is a mounted XFS filesystem or a device containing
7688           an XFS filesystem.  This command returns the geometry of the
7689           filesystem.
7690
7691           The returned struct contains geometry information.  Missing fields
7692           are returned as -1 (for numeric fields) or empty string.
7693
7694           This function depends on the feature "xfs".  See also
7695           "$g->feature-available".
7696
7697       $status = $g->xfs_repair ($device [, forcelogzero => $forcelogzero] [,
7698       nomodify => $nomodify] [, noprefetch => $noprefetch] [, forcegeometry
7699       => $forcegeometry] [, maxmem => $maxmem] [, ihashsize => $ihashsize] [,
7700       bhashsize => $bhashsize] [, agstride => $agstride] [, logdev =>
7701       $logdev] [, rtdev => $rtdev]);
7702           Repair corrupt or damaged XFS filesystem on "device".
7703
7704           The filesystem is specified using the "device" argument which
7705           should be the device name of the disk partition or volume
7706           containing the filesystem.  If given the name of a block device,
7707           "xfs_repair" will attempt to find the raw device associated with
7708           the specified block device and will use the raw device instead.
7709
7710           Regardless, the filesystem to be repaired must be unmounted,
7711           otherwise, the resulting filesystem may be inconsistent or corrupt.
7712
7713           The returned status indicates whether filesystem corruption was
7714           detected (returns 1) or was not detected (returns 0).
7715
7716           This function depends on the feature "xfs".  See also
7717           "$g->feature-available".
7718
7719       $g->yara_destroy ();
7720           Destroy previously loaded Yara rules in order to free libguestfs
7721           resources.
7722
7723           This function depends on the feature "libyara".  See also
7724           "$g->feature-available".
7725
7726       $g->yara_load ($filename);
7727           Upload a set of Yara rules from local file filename.
7728
7729           Yara rules allow to categorize files based on textual or binary
7730           patterns within their content.  See "$g->yara_scan" to see how to
7731           scan files with the loaded rules.
7732
7733           Rules can be in binary format, as when compiled with yarac command,
7734           or in source code format. In the latter case, the rules will be
7735           first compiled and then loaded.
7736
7737           Rules in source code format cannot include external files. In such
7738           cases, it is recommended to compile them first.
7739
7740           Previously loaded rules will be destroyed.
7741
7742           This function depends on the feature "libyara".  See also
7743           "$g->feature-available".
7744
7745       @detections = $g->yara_scan ($path);
7746           Scan a file with the previously loaded Yara rules.
7747
7748           For each matching rule, a "yara_detection" structure is returned.
7749
7750           The "yara_detection" structure contains the following fields.
7751
7752           "yara_name"
7753               Path of the file matching a Yara rule.
7754
7755           "yara_rule"
7756               Identifier of the Yara rule which matched against the given
7757               file.
7758
7759           This function depends on the feature "libyara".  See also
7760           "$g->feature-available".
7761
7762       @lines = $g->zegrep ($regex, $path);
7763           This calls the external "zegrep" program and returns the matching
7764           lines.
7765
7766           Because of the message protocol, there is a transfer limit of
7767           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
7768           guestfs(3).
7769
7770           This function is deprecated.  In new code, use the "grep" call
7771           instead.
7772
7773           Deprecated functions will not be removed from the API, but the fact
7774           that they are deprecated indicates that there are problems with
7775           correct use of these functions.
7776
7777       @lines = $g->zegrepi ($regex, $path);
7778           This calls the external "zegrep -i" program and returns the
7779           matching lines.
7780
7781           Because of the message protocol, there is a transfer limit of
7782           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
7783           guestfs(3).
7784
7785           This function is deprecated.  In new code, use the "grep" call
7786           instead.
7787
7788           Deprecated functions will not be removed from the API, but the fact
7789           that they are deprecated indicates that there are problems with
7790           correct use of these functions.
7791
7792       $g->zero ($device);
7793           This command writes zeroes over the first few blocks of "device".
7794
7795           How many blocks are zeroed isn't specified (but it’s not enough to
7796           securely wipe the device).  It should be sufficient to remove any
7797           partition tables, filesystem superblocks and so on.
7798
7799           If blocks are already zero, then this command avoids writing
7800           zeroes.  This prevents the underlying device from becoming non-
7801           sparse or growing unnecessarily.
7802
7803           See also: "$g->zero_device", "$g->scrub_device",
7804           "$g->is_zero_device"
7805
7806       $g->zero_device ($device);
7807           This command writes zeroes over the entire "device".  Compare with
7808           "$g->zero" which just zeroes the first few blocks of a device.
7809
7810           If blocks are already zero, then this command avoids writing
7811           zeroes.  This prevents the underlying device from becoming non-
7812           sparse or growing unnecessarily.
7813
7814       $g->zero_free_space ($directory);
7815           Zero the free space in the filesystem mounted on directory.  The
7816           filesystem must be mounted read-write.
7817
7818           The filesystem contents are not affected, but any free space in the
7819           filesystem is freed.
7820
7821           Free space is not "trimmed".  You may want to call "$g->fstrim"
7822           either as an alternative to this, or after calling this, depending
7823           on your requirements.
7824
7825       $g->zerofree ($device);
7826           This runs the zerofree program on "device".  This program claims to
7827           zero unused inodes and disk blocks on an ext2/3 filesystem, thus
7828           making it possible to compress the filesystem more effectively.
7829
7830           You should not run this program if the filesystem is mounted.
7831
7832           It is possible that using this program can damage the filesystem or
7833           data on the filesystem.
7834
7835           This function depends on the feature "zerofree".  See also
7836           "$g->feature-available".
7837
7838       @lines = $g->zfgrep ($pattern, $path);
7839           This calls the external "zfgrep" program and returns the matching
7840           lines.
7841
7842           Because of the message protocol, there is a transfer limit of
7843           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
7844           guestfs(3).
7845
7846           This function is deprecated.  In new code, use the "grep" call
7847           instead.
7848
7849           Deprecated functions will not be removed from the API, but the fact
7850           that they are deprecated indicates that there are problems with
7851           correct use of these functions.
7852
7853       @lines = $g->zfgrepi ($pattern, $path);
7854           This calls the external "zfgrep -i" program and returns the
7855           matching lines.
7856
7857           Because of the message protocol, there is a transfer limit of
7858           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
7859           guestfs(3).
7860
7861           This function is deprecated.  In new code, use the "grep" call
7862           instead.
7863
7864           Deprecated functions will not be removed from the API, but the fact
7865           that they are deprecated indicates that there are problems with
7866           correct use of these functions.
7867
7868       $description = $g->zfile ($meth, $path);
7869           This command runs file(1) after first decompressing "path" using
7870           "meth".
7871
7872           "meth" must be one of "gzip", "compress" or "bzip2".
7873
7874           Since 1.0.63, use "$g->file" instead which can now process
7875           compressed files.
7876
7877           This function is deprecated.  In new code, use the "file" call
7878           instead.
7879
7880           Deprecated functions will not be removed from the API, but the fact
7881           that they are deprecated indicates that there are problems with
7882           correct use of these functions.
7883
7884       @lines = $g->zgrep ($regex, $path);
7885           This calls the external zgrep(1) program and returns the matching
7886           lines.
7887
7888           Because of the message protocol, there is a transfer limit of
7889           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
7890           guestfs(3).
7891
7892           This function is deprecated.  In new code, use the "grep" call
7893           instead.
7894
7895           Deprecated functions will not be removed from the API, but the fact
7896           that they are deprecated indicates that there are problems with
7897           correct use of these functions.
7898
7899       @lines = $g->zgrepi ($regex, $path);
7900           This calls the external "zgrep -i" program and returns the matching
7901           lines.
7902
7903           Because of the message protocol, there is a transfer limit of
7904           somewhere between 2MB and 4MB.  See "PROTOCOL LIMITS" in
7905           guestfs(3).
7906
7907           This function is deprecated.  In new code, use the "grep" call
7908           instead.
7909
7910           Deprecated functions will not be removed from the API, but the fact
7911           that they are deprecated indicates that there are problems with
7912           correct use of these functions.
7913

AVAILABILITY

7915       From time to time we add new libguestfs APIs.  Also some libguestfs
7916       APIs won't be available in all builds of libguestfs (the Fedora build
7917       is full-featured, but other builds may disable features).  How do you
7918       test whether the APIs that your Perl program needs are available in the
7919       version of "Sys::Guestfs" that you are using?
7920
7921       To test if a particular function is available in the "Sys::Guestfs"
7922       class, use the ordinary Perl UNIVERSAL method can(METHOD) (see
7923       perlobj(1)).  For example:
7924
7925        use Sys::Guestfs;
7926        if (defined (Sys::Guestfs->can ("set_verbose"))) {
7927          print "\$g->set_verbose is available\n";
7928        }
7929
7930       To test if particular features are supported by the current build, use
7931       the "feature_available" method like the example below.  Note that the
7932       appliance must be launched first.
7933
7934        $g->feature_available ( ["augeas"] );
7935
7936       For further discussion on this topic, refer to "AVAILABILITY" in
7937       guestfs(3).
7938

STORING DATA IN THE HANDLE

7940       The handle returned from "new" is a hash reference.  The hash normally
7941       contains some elements:
7942
7943        {
7944          _g => [private data used by libguestfs],
7945          _flags => [flags provided when creating the handle]
7946        }
7947
7948       Callers can add other elements to this hash to store data for their own
7949       purposes.  The data lasts for the lifetime of the handle.
7950
7951       Any fields whose names begin with an underscore are reserved for
7952       private use by libguestfs.  We may add more in future.
7953
7954       It is recommended that callers prefix the name of their field(s) with
7955       some unique string, to avoid conflicts with other users.
7956
7958       Copyright (C) 2009-2023 Red Hat Inc.
7959

LICENSE

7961       Please see the file COPYING.LIB for the full license.
7962

SEE ALSO

7964       guestfs(3), guestfish(1), <http://libguestfs.org>.
7965
7966
7967
7968perl v5.36.0                      2023-02-21                   Sys::Guestfs(3)
Impressum