1guestfs-erlang(3) Virtualization Support guestfs-erlang(3)
2
3
4
6 guestfs-erlang - How to use libguestfs from Erlang
7
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
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
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
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
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
229 Richard W.M. Jones ("rjones at redhat dot com")
230
232 Copyright (C) 2011-2012 Red Hat Inc.
233
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
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)