1.. zephyr:code-sample:: virtiofs
2   :name: virtiofs filesystem
3   :relevant-api: file_system_api
4
5   Use file system API over virtiofs.
6
7Overview
8********
9
10This sample app demonstrates the use of Zephyr's :ref:`file system API
11<file_system_api>` over `virtiofs <https://virtio-fs.gitlab.io/>`_ by reading, creating and listing files and directories.
12In the case of virtiofs the mounted filesystem is a directory on the host.
13
14Requirements
15************
16This sample requires `virtiofsd <https://gitlab.com/virtio-fs/virtiofsd>`_ to run.
17
18Building
19********
20.. zephyr-app-commands::
21   :zephyr-app: samples/subsys/fs/virtiofs
22   :board: qemu_x86_64
23   :goals: build
24   :compact:
25
26
27Running
28*******
29Before launching QEMU ``virtiofsd`` has to be running. QEMU's arguments are embedded using :code:`CONFIG_QEMU_EXTRA_FLAGS` and socket path is set to :code:`/tmp/vhostqemu`, so ``virtiofsd`` has to be launched using
30
31.. code-block::
32
33   virtiofsd --socket-path=/tmp/vhostqemu -o source=shared_dir_path
34
35where :code:`shared_dir_path` is a directory that will be mounted on Zephyr side.
36Then you can launch QEMU using:
37
38.. code-block::
39
40   west build -t run
41
42This sample will list the files and directories in the mounted filesystem and print the contents of the file :code:`file` in the mounted directory.
43This sample will also create some files and directories.
44You can create the sample directory using :code:`prepare_sample_directory.sh`.
45
46Example output:
47
48.. code-block::
49
50   *** Booting Zephyr OS build v4.1.0-rc1-28-gc6816316fc50 ***
51   /virtiofs directory tree:
52   - dir2 (type=dir)
53     - b (type=file, size=3)
54     - a (type=file, size=2)
55     - c (type=file, size=4)
56   - dir (type=dir)
57     - some_file (type=file, size=0)
58     - nested_dir (type=dir)
59        - some_other_file (type=file, size=0)
60   - file (type=file, size=27)
61
62   /virtiofs/file content:
63   this is a file on the host
64
65
66After running the sample you can check the created files:
67
68.. code-block:: console
69
70   shared_dir_path$ cat file_created_by_zephyr
71   hello world
72   shared_dir_path$ cat second_file_created_by_zephyr
73   lorem ipsum
74