.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Sys::Guestfs::Lib 3pm"
.TH Sys::Guestfs::Lib 3pm "2012-06-01" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Sys::Guestfs::Lib \- Useful functions for using libguestfs from Perl
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Sys::Guestfs::Lib qw(open_guest ...);
\&
\& $g = open_guest ($name);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Sys::Guestfs::Lib\*(C'\fR is an extra library of useful functions for using
the libguestfs \s-1API\s0 from Perl. It also provides tighter integration
with libvirt.
.PP
The basic libguestfs \s-1API\s0 is not covered by this manpage. Please refer
instead to \fISys::Guestfs\fR\|(3) and \fIguestfs\fR\|(3). The libvirt \s-1API\s0 is
also not covered. For that, see \fISys::Virt\fR\|(3).
.SH "DEPRECATION OF SOME FUNCTIONS"
.IX Header "DEPRECATION OF SOME FUNCTIONS"
This module contains functions and code to perform inspection of guest
images. Since libguestfs 1.5.3 this ability has moved into the core
\&\s-1API\s0 (see \*(L"\s-1INSPECTION\s0\*(R" in \fIguestfs\fR\|(3)). The inspection functions in this
module are deprecated and will not be updated. Each deprecated
function is marked in the documentation below.
.SH "BASIC FUNCTIONS"
.IX Header "BASIC FUNCTIONS"
.SS "open_guest"
.IX Subsection "open_guest"
.Vb 1
\& $g = open_guest ($name);
\&
\& $g = open_guest ($name, rw => 1, ...);
\&
\& $g = open_guest ($name, address => $uri, ...);
\&
\& $g = open_guest ([$img1, $img2, ...], address => $uri, format => $format, ...);
\&
\& ($g, $conn, $dom, @images) = open_guest ($name);
.Ve
.PP
This function opens a libguestfs handle for either the libvirt domain
called \f(CW$name\fR, or the disk image called \f(CW$name\fR. Any disk images
found through libvirt or specified explicitly are attached to the
libguestfs handle.
.PP
The \f(CW\*(C`Sys::Guestfs\*(C'\fR handle \f(CW$g\fR is returned, or if there was an error
it throws an exception. To catch errors, wrap the call in an eval
block.
.PP
The first parameter is either a string referring to a libvirt domain
or a disk image, or (if a guest has several disk images) an arrayref
\&\f(CW\*(C`[$img1, $img2, ...]\*(C'\fR. For disk images, if the \f(CW\*(C`format\*(C'\fR parameter
is specified then that format is forced.
.PP
The handle is \fIread-only\fR by default. Use the optional parameter
\&\f(CW\*(C`rw => 1\*(C'\fR to open a read-write handle. However if you open a
read-write handle, this function will refuse to use active libvirt
domains.
.PP
The handle is still in the config state when it is returned, so you
have to call \f(CW\*(C`$g\->launch ()\*(C'\fR.
.PP
The optional \f(CW\*(C`address\*(C'\fR parameter can be added to specify the libvirt
\&\s-1URI\s0.
.PP
The implicit libvirt handle is closed after this function, \fIunless\fR
you call the function in \f(CW\*(C`wantarray\*(C'\fR context, in which case the
function returns a tuple of: the open libguestfs handle, the open
libvirt handle, and the open libvirt domain handle, and a list of
[image,format] pairs. (This is useful if you want to do other things
like pulling the \s-1XML\s0 description of the guest). Note that if this is
a straight disk image, then \f(CW$conn\fR and \f(CW$dom\fR will be \f(CW\*(C`undef\*(C'\fR.
.PP
If the \f(CW\*(C`Sys::Virt\*(C'\fR module is not available, then libvirt is bypassed,
and this function can only open disk images.
.PP
The optional \f(CW\*(C`interface\*(C'\fR parameter can be used to open devices with a
specified qemu interface. See \*(L"guestfs_add_drive_opts\*(R" in Sys::Guestfs
for more details.
.SS "feature_available"
.IX Subsection "feature_available"
.Vb 1
\& $bool = feature_available ($g, $feature [, $feature ...]);
.Ve
.PP
This function is a useful wrapper around the basic
\&\f(CW\*(C`$g\->available\*(C'\fR call.
.PP
\&\f(CW\*(C`$g\->available\*(C'\fR tests for availability of a list of features and
dies with an error if any is not available.
.PP
This call tests for the list of features and returns true if all are
available, or false otherwise.
.PP
For a list of features you can test for, see \*(L"\s-1AVAILABILITY\s0\*(R" in \fIguestfs\fR\|(3).
.SS "get_partitions"
.IX Subsection "get_partitions"
This function is deprecated. It will not be updated in future
versions of libguestfs. New code should not use this function. Use
the core \s-1API\s0 function \*(L"list_filesystems\*(R" in \fISys::Guestfs\fR\|(3) instead.
.SS "resolve_windows_path"
.IX Subsection "resolve_windows_path"
.Vb 1
\& $path = resolve_windows_path ($g, $path);
\&
\& $path = resolve_windows_path ($g, "/windows/system");
\& ==> "/WINDOWS/System"
\& or undef if no path exists
.Ve
.PP
This function, which is specific to \s-1FAT/NTFS\s0 filesystems (ie. Windows
guests), lets you look up a case insensitive \f(CW$path\fR in the
filesystem and returns the true, case sensitive path as required by
the underlying kernel or NTFS\-3g driver.
.PP
If \f(CW$path\fR does not exist then this function returns \f(CW\*(C`undef\*(C'\fR.
.PP
The \f(CW$path\fR parameter must begin with \f(CW\*(C`/\*(C'\fR character and be separated
by \f(CW\*(C`/\*(C'\fR characters. Do not use \f(CW\*(C`\e\*(C'\fR, drive names, etc.
.SS "file_architecture"
.IX Subsection "file_architecture"
Deprecated function. Replace any calls to this function with:
.PP
.Vb 1
\& $g\->file_architecture ($path);
.Ve
.SH "OPERATING SYSTEM INSPECTION FUNCTIONS"
.IX Header "OPERATING SYSTEM INSPECTION FUNCTIONS"
.SS "inspect_all_partitions"
.IX Subsection "inspect_all_partitions"
This function is deprecated. It will not be updated in future
versions of libguestfs. New code should not use this function. Use
the core \s-1API\s0 functions instead, see \*(L"\s-1INSPECTION\s0\*(R" in \fIguestfs\fR\|(3).
.SS "inspect_partition"
.IX Subsection "inspect_partition"
This function is deprecated. It will not be updated in future
versions of libguestfs. New code should not use this function. Use
the core \s-1API\s0 functions instead, see \*(L"\s-1INSPECTION\s0\*(R" in \fIguestfs\fR\|(3).
.SS "inspect_operating_systems"
.IX Subsection "inspect_operating_systems"
This function is deprecated. It will not be updated in future
versions of libguestfs. New code should not use this function. Use
the core \s-1API\s0 functions instead, see \*(L"\s-1INSPECTION\s0\*(R" in \fIguestfs\fR\|(3).
.SS "mount_operating_system"
.IX Subsection "mount_operating_system"
This function is deprecated. It will not be updated in future
versions of libguestfs. New code should not use this function. Use
the core \s-1API\s0 functions instead, see \*(L"\s-1INSPECTION\s0\*(R" in \fIguestfs\fR\|(3).
.SS "inspect_in_detail"
.IX Subsection "inspect_in_detail"
This function is deprecated. It will not be updated in future
versions of libguestfs. New code should not use this function. Use
the core \s-1API\s0 functions instead, see \*(L"\s-1INSPECTION\s0\*(R" in \fIguestfs\fR\|(3).
.SS "inspect_linux_kernel"
.IX Subsection "inspect_linux_kernel"
This function is deprecated. It will not be updated in future
versions of libguestfs. New code should not use this function. Use
the core \s-1API\s0 functions instead, see \*(L"\s-1INSPECTION\s0\*(R" in \fIguestfs\fR\|(3).
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2009\-2012 Red Hat Inc.
.SH "LICENSE"
.IX Header "LICENSE"
Please see the file \s-1COPYING\s0.LIB for the full license.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIvirt\-inspector\fR\|(1),
\&\fISys::Guestfs\fR\|(3),
\&\fIguestfs\fR\|(3),
,
\&\fISys::Virt\fR\|(3),
,
\&\fIguestfish\fR\|(1).