1guestfs-erlang(3) Virtualization Support guestfs-erlang(3)
2
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 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 {ok, G} = guestfs:create().
28 {ok, G} = guestfs:create("/path/to/erl-guestfs").
30 "G" is the libguestfs handle which you should pass to other functions.
32 To close the handle:
34 ok = guestfs:close(G).
36 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 ok = guestfs:add_drive_opts(G, Disk,
43 [{format, "raw"}, {readonly, true}]).
44 If the last argument would be an empty list, you can also omit it:
46 ok = guestfs:add_drive_opts(G, Disk).
48 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 On error, you would see one of the following tuples:
55 "{error, Msg, Errno}"
57 This indicates an ordinary error from the function.
58 "Msg" is the error message (string) and "Errno" is the Unix error
60 (integer).
61 "Errno" can be zero. See "guestfs_last_errno" in guestfs(3).
63 "{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 "Function" is the name of the unknown function.
70 "{unknownarg, Arg}"
72 This indicates that you called a function with optional arguments,
73 with an unknown argument name.
74 "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 main(_) ->
83 Output = "disk.img",
84 {ok, G} = guestfs:create(),
86 % 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 % Set the trace flag so that we can see each libguestfs call.
94 ok = guestfs:set_trace(G, true),
95 % Attach the disk image to libguestfs.
97 ok = guestfs:add_drive_opts(G, Output,
98 [{format, "raw"}, {readonly, false}]),
99 % Run the libguestfs back-end.
101 ok = guestfs:launch(G),
102 % 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 % Partition the disk as one single MBR partition.
109 ok = guestfs:part_disk(G, Device, "mbr"),
110 % 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 % Create a filesystem on the partition.
116 ok = guestfs:mkfs(G, "ext4", Partition),
117 % Now mount the filesystem so that we can add files. *)
119 ok = guestfs:mount(G, Partition, "/"),
120 % 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 % 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 % 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 % 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 main([Disk]) ->
147 {ok, G} = guestfs:create(),
148 % Attach the disk image read-only to libguestfs.
150 ok = guestfs:add_drive_opts(G, Disk, [{readonly, true}]),
151 % Run the libguestfs back-end.
153 ok = guestfs:launch(G),
154 % 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 list_os(_, []) ->
165 ok;
166 list_os(G, [Root|Roots]) ->
167 io:fwrite("Root device: ~s~n", [Root]),
168 % 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 % Mount up the disks, like guestfish -i.
181 Mps = sort_mps(guestfs:inspect_get_mountpoints(G, Root)),
182 mount_mps(G, Mps),
183 % 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 % Unmount everything.
195 ok = guestfs:umount_all(G),
196 list_os(G, Roots).
198 % 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 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 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 To report a new bug against libguestfs, use this link:
244 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
245 When reporting a bug, please supply:
247 · The version of libguestfs.
249 · Where you got libguestfs (eg. which Linux distro, compiled from
251 source, etc)
252 · Describe the bug accurately and give a way to reproduce it.
254 · Run libguestfs-test-tool(1) and paste the complete, unedited output
256 into the bug report.
257libguestfs-1.40.2 2019-02-07 guestfs-erlang(3)