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

AVAILABILITY

7861       From time to time we add new libguestfs APIs.  Also some libguestfs
7862       APIs won't be available in all builds of libguestfs (the Fedora build
7863       is full-featured, but other builds may disable features).  How do you
7864       test whether the APIs that your Perl program needs are available in the
7865       version of "Sys::Guestfs" that you are using?
7866
7867       To test if a particular function is available in the "Sys::Guestfs"
7868       class, use the ordinary Perl UNIVERSAL method "can(METHOD)" (see
7869       perlobj(1)).  For example:
7870
7871        use Sys::Guestfs;
7872        if (defined (Sys::Guestfs->can ("set_verbose"))) {
7873          print "\$g->set_verbose is available\n";
7874        }
7875
7876       To test if particular features are supported by the current build, use
7877       the "feature_available" method like the example below.  Note that the
7878       appliance must be launched first.
7879
7880        $g->feature_available ( ["augeas"] );
7881
7882       For further discussion on this topic, refer to "AVAILABILITY" in
7883       guestfs(3).
7884

STORING DATA IN THE HANDLE

7886       The handle returned from "new" is a hash reference.  The hash normally
7887       contains some elements:
7888
7889        {
7890          _g => [private data used by libguestfs],
7891          _flags => [flags provided when creating the handle]
7892        }
7893
7894       Callers can add other elements to this hash to store data for their own
7895       purposes.  The data lasts for the lifetime of the handle.
7896
7897       Any fields whose names begin with an underscore are reserved for
7898       private use by libguestfs.  We may add more in future.
7899
7900       It is recommended that callers prefix the name of their field(s) with
7901       some unique string, to avoid conflicts with other users.
7902
7904       Copyright (C) 2009-2020 Red Hat Inc.
7905

LICENSE

7907       Please see the file COPYING.LIB for the full license.
7908

SEE ALSO

7910       guestfs(3), guestfish(1), <http://libguestfs.org>.
7911
7912
7913
7914perl v5.32.1                      2021-04-03                   Sys::Guestfs(3)
Impressum