--- name: "guestfs-erlang" section: "3" platform: "linux" package: "erlang-libguestfs" version: "1.60.1-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/guestfs-erlang" --- # guestfs-erlang(3) How to use libguestfs from Erlang ## NAME guestfs-erlang - How to use libguestfs from Erlang ## SYNOPSIS ``` {ok, G} = guestfs:create(), ok = guestfs:add_drive_opts(G, Disk, [{format, "raw"}, {readonly, true}]), ok = guestfs:launch(G), [Device] = guestfs:list_devices(G), ok = guestfs:close(G). ``` ## DESCRIPTION This manual page documents how to call libguestfs from the Erlang programming language. This page just documents the differences from the C API and gives some examples. If you are not familiar with using libguestfs, you also need to read [**guestfs**(3)](/guestfs/3.md). ### OPENING AND CLOSING THE HANDLE The Erlang bindings are implemented using an external program called `"erl-guestfs"`. This program must be on the current PATH, or else you should specify the full path to the program: ``` {ok, G} = guestfs:create(). {ok, G} = guestfs:create("/path/to/erl-guestfs"). ``` `"G"` is the libguestfs handle which you should pass to other functions. To close the handle: ``` ok = guestfs:close(G). ``` ### FUNCTIONS WITH OPTIONAL ARGUMENTS For functions that take optional arguments, the first arguments are the non-optional ones. The last argument is a list of tuples supplying the remaining optional arguments. ``` ok = guestfs:add_drive_opts(G, Disk, [{format, "raw"}, {readonly, true}]). ``` If the last argument would be an empty list, you can also omit it: ``` ok = guestfs:add_drive_opts(G, Disk). ``` ### RETURN VALUES AND ERRORS On success, most functions return a `"Result"` term (which could be a list, string, tuple etc.). If there is nothing for the function to return, then the atom `"ok"` is returned. On error, you would see one of the following tuples: - "{error, Msg, Errno}" This indicates an ordinary error from the function. `"Msg"` is the error message (string) and `"Errno"` is the Unix error (integer). `"Errno"` can be zero. See "guestfs\_last\_errno" in [**guestfs**(3)](/guestfs/3.md). - "{unknown, Function}" This indicates that the function you called is not known. Generally this means you are mixing `"erl-guestfs"` from another version of libguestfs, which you should not do. `"Function"` is the name of the unknown function. - "{unknownarg, Arg}" This indicates that you called a function with optional arguments, with an unknown argument name. `"Arg"` is the name of the unknown argument. ## EXAMPLE 1: CREATE A DISK IMAGE ``` #!/usr/bin/env escript %%! -smp enable -sname create_disk debug verbose % Example showing how to create a disk image. main(_) -> Output = "disk.img", {ok, G} = guestfs:create(), % Create a raw-format sparse disk image, 512 MB in size. {ok, File} = file:open(Output, [raw, write, binary]), {ok, _} = file:position(File, 512 * 1024 * 1024 - 1), ok = file:write(File, " "), ok = file:close(File), % Set the trace flag so that we can see each libguestfs call. ok = guestfs:set_trace(G, true), % Attach the disk image to libguestfs. ok = guestfs:add_drive_opts(G, Output, [{format, "raw"}, {readonly, false}]), % Run the libguestfs back-end. ok = guestfs:launch(G), % Get the list of devices. Because we only added one drive % above, we expect that this list should contain a single % element. [Device] = guestfs:list_devices(G), % Partition the disk as one single MBR partition. ok = guestfs:part_disk(G, Device, "mbr"), % Get the list of partitions. We expect a single element, which % is the partition we have just created. [Partition] = guestfs:list_partitions(G), % Create a filesystem on the partition. ok = guestfs:mkfs(G, "ext4", Partition), % Now mount the filesystem so that we can add files. *) ok = guestfs:mount(G, Partition, "/"), % Create some files and directories. *) ok = guestfs:touch(G, "/empty"), Message = "Hello, world\n", ok = guestfs:write(G, "/hello", Message), ok = guestfs:mkdir(G, "/foo"), % This one uploads the local file /etc/resolv.conf into % the disk image. ok = guestfs:upload(G, "/etc/resolv.conf", "/foo/resolv.conf"), % Because we wrote to the disk and we want to detect write % errors, call guestfs:shutdown. You don't need to do this: % guestfs:close will do it implicitly. ok = guestfs:shutdown(G), % Note also that handles are automatically closed if they are % reaped by the garbage collector. You only need to call close % if you want to close the handle right away. ok = guestfs:close(G). ``` ## EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE ``` #!/usr/bin/env escript %%! -smp enable -sname inspect_vm debug verbose % Example showing how to inspect a virtual machine disk. main([Disk]) -> {ok, G} = guestfs:create(), % Attach the disk image read-only to libguestfs. ok = guestfs:add_drive_opts(G, Disk, [{readonly, true}]), % Run the libguestfs back-end. ok = guestfs:launch(G), % Ask libguestfs to inspect for operating systems. case guestfs:inspect_os(G) of [] -> io:fwrite("inspect_vm: no operating systems found~n"), exit(no_operating_system); Roots -> list_os(G, Roots) end. list_os(_, []) -> ok; list_os(G, [Root|Roots]) -> io:fwrite("Root device: ~s~n", [Root]), % Print basic information about the operating system. Product_name = guestfs:inspect_get_product_name(G, Root), io:fwrite(" Product name: ~s~n", [Product_name]), Major = guestfs:inspect_get_major_version(G, Root), Minor = guestfs:inspect_get_minor_version(G, Root), io:fwrite(" Version: ~w.~w~n", [Major, Minor]), Type = guestfs:inspect_get_type(G, Root), io:fwrite(" Type: ~s~n", [Type]), Distro = guestfs:inspect_get_distro(G, Root), io:fwrite(" Distro: ~s~n", [Distro]), % Mount up the disks, like guestfish -i. Mps = sort_mps(guestfs:inspect_get_mountpoints(G, Root)), mount_mps(G, Mps), % If /etc/issue.net file exists, print up to 3 lines. *) Filename = "/etc/issue.net", Is_file = guestfs:is_file(G, Filename), if Is_file -> io:fwrite("--- ~s ---~n", [Filename]), Lines = guestfs:head_n(G, 3, Filename), write_lines(Lines); true -> ok end, % Unmount everything. ok = guestfs:umount_all(G), list_os(G, Roots). % Sort keys by length, shortest first, so that we end up % mounting the filesystems in the correct order. sort_mps(Mps) -> Cmp = fun ({A,_}, {B,_}) -> length(A) =< length(B) end, lists:sort(Cmp, Mps). mount_mps(_, []) -> ok; mount_mps(G, [{Mp, Dev}|Mps]) -> case guestfs:mount_ro(G, Dev, Mp) of ok -> ok; { error, Msg, _ } -> io:fwrite("~s (ignored)~n", [Msg]) end, mount_mps(G, Mps). write_lines([]) -> ok; write_lines([Line|Lines]) -> io:fwrite("~s~n", [Line]), write_lines(Lines). ``` ## SEE ALSO [**guestfs**(3)](/guestfs/3.md), [**guestfs-examples**(3)](/guestfs-examples/3.md), [**guestfs-golang**(3)](/guestfs-golang/3.md), [**guestfs-java**(3)](/guestfs-java/3.md), [**guestfs-lua**(3)](/guestfs-lua/3.md), [**guestfs-ocaml**(3)](/guestfs-ocaml/3.md), [**guestfs-perl**(3)](/guestfs-perl/3.md), [**guestfs-python**(3)](/guestfs-python/3.md), [**guestfs-recipes**(1)](/guestfs-recipes/1.md), [**guestfs-ruby**(3)](/guestfs-ruby/3.md), http://www.erlang.org/. http://libguestfs.org/. ## AUTHORS Richard W.M. Jones (`"rjones at redhat dot com"`) ## COPYRIGHT Copyright (C) 2011-2025 Red Hat Inc. ## LICENSE This manual page contains examples which we hope you will use in your programs. The examples may be freely copied, modified and distributed for any purpose without any restrictions. ## BUGS To get a list of bugs against libguestfs, use this link: https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools To report a new bug against libguestfs, use this link: https://bugzilla.redhat.com/enter\_bug.cgi?component=libguestfs&product=Virtualization+Tools When reporting a bug, please supply: - • The version of libguestfs. - • Where you got libguestfs (eg. which Linux distro, compiled from source, etc) - • Describe the bug accurately and give a way to reproduce it. - • Run [**libguestfs-test-tool**(1)](/libguestfs-test-tool/1.md) and paste the **complete, unedited** output into the bug report.