1guestfs-erlang(3)           Virtualization Support           guestfs-erlang(3)
2
3
4

NAME

6       guestfs-erlang - How to use libguestfs from Erlang
7

SYNOPSIS

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).
15

DESCRIPTION

17       This manual page documents how to call libguestfs from the Erlang
18       programming language.  This page just documents the differences from
19       the C API and gives some examples.  If you are not familiar with using
20       libguestfs, you also need to read guestfs(3).
21
22   OPENING AND CLOSING THE HANDLE
23       The Erlang bindings are implemented using an external program called
24       "erl-guestfs".  This program must be on the current PATH, or else you
25       should specify the full path to the program:
26
27        {ok, G} = guestfs:create().
28
29        {ok, G} = guestfs:create("/path/to/erl-guestfs").
30
31       "G" is the libguestfs handle which you should pass to other functions.
32
33       To close the handle:
34
35        ok = guestfs:close(G).
36
37   FUNCTIONS WITH OPTIONAL ARGUMENTS
38       For functions that take optional arguments, the first arguments are the
39       non-optional ones.  The last argument is a list of tuples supplying the
40       remaining optional arguments.
41
42        ok = guestfs:add_drive_opts(G, Disk,
43                                    [{format, "raw"}, {readonly, true}]).
44
45       If the last argument would be an empty list, you can also omit it:
46
47        ok = guestfs:add_drive_opts(G, Disk).
48
49   RETURN VALUES AND ERRORS
50       On success, most functions return a "Result" term (which could be a
51       list, string, tuple etc.).  If there is nothing for the function to
52       return, then the atom "ok" is returned.
53
54       On error, you would see one of the following tuples:
55
56       "{error, Msg, Errno}"
57           This indicates an ordinary error from the function.
58
59           "Msg" is the error message (string) and "Errno" is the Unix error
60           (integer).
61
62           "Errno" can be zero.  See "guestfs_last_errno" in guestfs(3).
63
64       "{unknown, Function}"
65           This indicates that the function you called is not known.
66           Generally this means you are mixing "erl-guestfs" from another
67           version of libguestfs, which you should not do.
68
69           "Function" is the name of the unknown function.
70
71       "{unknownarg, Arg}"
72           This indicates that you called a function with optional arguments,
73           with an unknown argument name.
74
75           "Arg" is the name of the unknown argument.
76

EXAMPLE 1: CREATE A DISK IMAGE

78        #!/usr/bin/env escript
79        %%! -smp enable -sname create_disk debug verbose
80        % Example showing how to create a disk image.
81
82        main(_) ->
83            Output = "disk.img",
84
85            {ok, G} = guestfs:create(),
86
87            % Create a raw-format sparse disk image, 512 MB in size.
88            {ok, File} = file:open(Output, [raw, write, binary]),
89            {ok, _} = file:position(File, 512 * 1024 * 1024 - 1),
90            ok = file:write(File, " "),
91            ok = file:close(File),
92
93            % Set the trace flag so that we can see each libguestfs call.
94            ok = guestfs:set_trace(G, true),
95
96            % Attach the disk image to libguestfs.
97            ok = guestfs:add_drive_opts(G, Output,
98                                        [{format, "raw"}, {readonly, false}]),
99
100            % Run the libguestfs back-end.
101            ok = guestfs:launch(G),
102
103            % Get the list of devices.  Because we only added one drive
104            % above, we expect that this list should contain a single
105            % element.
106            [Device] = guestfs:list_devices(G),
107
108            % Partition the disk as one single MBR partition.
109            ok = guestfs:part_disk(G, Device, "mbr"),
110
111            % Get the list of partitions.  We expect a single element, which
112            % is the partition we have just created.
113            [Partition] = guestfs:list_partitions(G),
114
115            % Create a filesystem on the partition.
116            ok = guestfs:mkfs(G, "ext4", Partition),
117
118            % Now mount the filesystem so that we can add files. *)
119            ok = guestfs:mount(G, Partition, "/"),
120
121            % Create some files and directories. *)
122            ok = guestfs:touch(G, "/empty"),
123            Message = "Hello, world\n",
124            ok = guestfs:write(G, "/hello", Message),
125            ok = guestfs:mkdir(G, "/foo"),
126
127            % This one uploads the local file /etc/resolv.conf into
128            % the disk image.
129            ok = guestfs:upload(G, "/etc/resolv.conf", "/foo/resolv.conf"),
130
131            % Because we wrote to the disk and we want to detect write
132            % errors, call guestfs:shutdown.  You don't need to do this:
133            % guestfs:close will do it implicitly.
134            ok = guestfs:shutdown(G),
135
136            % Note also that handles are automatically closed if they are
137            % reaped by the garbage collector.  You only need to call close
138            % if you want to close the handle right away.
139            ok = guestfs:close(G).
140

EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE

142        #!/usr/bin/env escript
143        %%! -smp enable -sname inspect_vm debug verbose
144        % Example showing how to inspect a virtual machine disk.
145
146        main([Disk]) ->
147            {ok, G} = guestfs:create(),
148
149            % Attach the disk image read-only to libguestfs.
150            ok = guestfs:add_drive_opts(G, Disk, [{readonly, true}]),
151
152            % Run the libguestfs back-end.
153            ok = guestfs:launch(G),
154
155            % Ask libguestfs to inspect for operating systems.
156            case guestfs:inspect_os(G) of
157                [] ->
158                    io:fwrite("inspect_vm: no operating systems found~n"),
159                    exit(no_operating_system);
160                Roots ->
161                    list_os(G, Roots)
162            end.
163
164        list_os(_, []) ->
165            ok;
166        list_os(G, [Root|Roots]) ->
167            io:fwrite("Root device: ~s~n", [Root]),
168
169            % Print basic information about the operating system.
170            Product_name = guestfs:inspect_get_product_name(G, Root),
171            io:fwrite("  Product name: ~s~n", [Product_name]),
172            Major = guestfs:inspect_get_major_version(G, Root),
173            Minor = guestfs:inspect_get_minor_version(G, Root),
174            io:fwrite("  Version:      ~w.~w~n", [Major, Minor]),
175            Type = guestfs:inspect_get_type(G, Root),
176            io:fwrite("  Type:         ~s~n", [Type]),
177            Distro = guestfs:inspect_get_distro(G, Root),
178            io:fwrite("  Distro:       ~s~n", [Distro]),
179
180            % Mount up the disks, like guestfish -i.
181            Mps = sort_mps(guestfs:inspect_get_mountpoints(G, Root)),
182            mount_mps(G, Mps),
183
184            % If /etc/issue.net file exists, print up to 3 lines. *)
185            Filename = "/etc/issue.net",
186            Is_file = guestfs:is_file(G, Filename),
187            if Is_file ->
188                    io:fwrite("--- ~s ---~n", [Filename]),
189                    Lines = guestfs:head_n(G, 3, Filename),
190                    write_lines(Lines);
191               true -> ok
192            end,
193
194            % Unmount everything.
195            ok = guestfs:umount_all(G),
196
197            list_os(G, Roots).
198
199        % Sort keys by length, shortest first, so that we end up
200        % mounting the filesystems in the correct order.
201        sort_mps(Mps) ->
202            Cmp = fun ({A,_}, {B,_}) ->
203                          length(A) =< length(B) end,
204            lists:sort(Cmp, Mps).
205
206        mount_mps(_, []) ->
207            ok;
208        mount_mps(G, [{Mp, Dev}|Mps]) ->
209            case guestfs:mount_ro(G, Dev, Mp) of
210                ok -> ok;
211                { error, Msg, _ } ->
212                    io:fwrite("~s (ignored)~n", [Msg])
213            end,
214            mount_mps(G, Mps).
215
216        write_lines([]) ->
217            ok;
218        write_lines([Line|Lines]) ->
219            io:fwrite("~s~n", [Line]),
220            write_lines(Lines).
221

SEE ALSO

223       guestfs(3), guestfs-examples(3), guestfs-gobject(3), guestfs-golang(3),
224       guestfs-java(3), guestfs-lua(3), guestfs-ocaml(3), guestfs-perl(3),
225       guestfs-python(3), guestfs-recipes(1), guestfs-ruby(3),
226       http://www.erlang.org/.  http://libguestfs.org/.
227

AUTHORS

229       Richard W.M. Jones ("rjones at redhat dot com")
230
232       Copyright (C) 2011-2012 Red Hat Inc.
233

LICENSE

235       This manual page contains examples which we hope you will use in your
236       programs.  The examples may be freely copied, modified and distributed
237       for any purpose without any restrictions.
238

BUGS

240       To get a list of bugs against libguestfs, use this link:
241       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
242
243       To report a new bug against libguestfs, use this link:
244       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
245
246       When reporting a bug, please supply:
247
248       ·   The version of libguestfs.
249
250       ·   Where you got libguestfs (eg. which Linux distro, compiled from
251           source, etc)
252
253       ·   Describe the bug accurately and give a way to reproduce it.
254
255       ·   Run libguestfs-test-tool(1) and paste the complete, unedited output
256           into the bug report.
257
258
259
260libguestfs-1.40.2                 2019-02-07                 guestfs-erlang(3)
Impressum