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

AVAILABILITY

7753       From time to time we add new libguestfs APIs.  Also some libguestfs
7754       APIs won't be available in all builds of libguestfs (the Fedora build
7755       is full-featured, but other builds may disable features).  How do you
7756       test whether the APIs that your Perl program needs are available in the
7757       version of "Sys::Guestfs" that you are using?
7758
7759       To test if a particular function is available in the "Sys::Guestfs"
7760       class, use the ordinary Perl UNIVERSAL method "can(METHOD)" (see
7761       perlobj(1)).  For example:
7762
7763        use Sys::Guestfs;
7764        if (defined (Sys::Guestfs->can ("set_verbose"))) {
7765          print "\$g->set_verbose is available\n";
7766        }
7767
7768       To test if particular features are supported by the current build, use
7769       the "feature_available" method like the example below.  Note that the
7770       appliance must be launched first.
7771
7772        $g->feature_available ( ["augeas"] );
7773
7774       For further discussion on this topic, refer to "AVAILABILITY" in
7775       guestfs(3).
7776

STORING DATA IN THE HANDLE

7778       The handle returned from "new" is a hash reference.  The hash normally
7779       contains some elements:
7780
7781        {
7782          _g => [private data used by libguestfs],
7783          _flags => [flags provided when creating the handle]
7784        }
7785
7786       Callers can add other elements to this hash to store data for their own
7787       purposes.  The data lasts for the lifetime of the handle.
7788
7789       Any fields whose names begin with an underscore are reserved for
7790       private use by libguestfs.  We may add more in future.
7791
7792       It is recommended that callers prefix the name of their field(s) with
7793       some unique string, to avoid conflicts with other users.
7794
7796       Copyright (C) 2009-2019 Red Hat Inc.
7797

LICENSE

7799       Please see the file COPYING.LIB for the full license.
7800

SEE ALSO

7802       guestfs(3), guestfish(1), <http://libguestfs.org>.
7803
7804
7805
7806perl v5.28.1                      2019-01-17                   Sys::Guestfs(3)
Impressum