5 guestfs-erlang - How to use libguestfs from Erlang
9 {ok, G} = guestfs:create(),
10 ok = guestfs:add_drive_opts(G, Disk,
11 [{format, "raw"}, {readonly, true}]),
12 ok = guestfs:launch(G),
13 [Device] = guestfs:list_devices(G),
14 ok = guestfs:close(G).
18 This manual page documents how to call libguestfs from the Erlang
19 programming language. This page just documents the differences from
20 the C API and gives some examples. If you are not familiar with using
21 libguestfs, you also need to read L<guestfs(3)>.
23 =head2 OPENING AND CLOSING THE HANDLE
25 The Erlang bindings are implemented using an external program called
26 C<erl-guestfs>. This program must be on the current PATH, or else you
27 should specify the full path to the program:
29 {ok, G} = guestfs:create().
31 {ok, G} = guestfs:create("/path/to/erl-guestfs").
33 C<G> is the libguestfs handle which you should pass to other
38 ok = guestfs:close(G).
40 =head2 FUNCTIONS WITH OPTIONAL ARGUMENTS
42 For functions that take optional arguments, the first arguments are
43 the non-optional ones. The last argument is a list of tuples
44 supplying the remaining optional arguments.
46 ok = guestfs:add_drive_opts(G, Disk,
47 [{format, "raw"}, {readonly, true}]).
49 If the last argument would be an empty list, you can also omit it:
51 ok = guestfs:add_drive_opts(G, Disk).
53 =head2 RETURN VALUES AND ERRORS
55 On success, most functions return a C<Result> term (which could be a
56 list, string, tuple etc.). If there is nothing for the function to
57 return, then the atom C<ok> is returned.
59 On error, you would see one of the following tuples:
63 =item C<{error, Msg, Errno}>
65 This indicates an ordinary error from the function.
67 C<Msg> is the error message (string) and C<Errno> is the Unix error
70 C<Errno> can be zero. See L<guestfs(3)/guestfs_last_errno>.
72 =item C<{unknown, Function}>
74 This indicates that the function you called is not known. Generally
75 this means you are mixing C<erl-guestfs> from another version of
76 libguestfs, which you should not do.
78 C<Function> is the name of the unknown function.
80 =item C<{unknownarg, Arg}>
82 This indicates that you called a function with optional arguments,
83 with an unknown argument name.
85 C<Arg> is the name of the unknown argument.
89 =head1 EXAMPLE 1: CREATE A DISK IMAGE
93 =head1 EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE
100 L<guestfs-examples(3)>,
104 L<guestfs-python(3)>,
105 L<guestfs-recipes(1)>,
107 L<http://www.erlang.org/>.
108 L<http://libguestfs.org/>.
112 Richard W.M. Jones (C<rjones at redhat dot com>)
116 Copyright (C) 2011 Red Hat Inc. L<http://libguestfs.org/>
118 The examples in this manual page may be freely copied, modified and
119 distributed without any restrictions.
121 This library is free software; you can redistribute it and/or
122 modify it under the terms of the GNU Lesser General Public
123 License as published by the Free Software Foundation; either
124 version 2 of the License, or (at your option) any later version.
126 This library is distributed in the hope that it will be useful,
127 but WITHOUT ANY WARRANTY; without even the implied warranty of
128 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
129 Lesser General Public License for more details.
131 You should have received a copy of the GNU Lesser General Public
132 License along with this library; if not, write to the Free Software
133 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA