1.. _posix-env-sample:
2
3POSIX Environment Variables
4###########################
5
6Overview
7********
8
9In this sample application, the POSIX :c:func:`setenv`, function is used to populate several environment
10variables in C. Then, all environment variables are then printed.
11
12If the user sets a new value for the ``ALERT`` environment variable, it is printed to standard
13output, and then cleared via :c:func:`unsetenv`.
14
15Building and Running
16********************
17
18This project outputs to the console. It can be built and executed on QEMU as follows:
19
20.. zephyr-app-commands::
21   :zephyr-app: samples/posix/env
22   :host-os: unix
23   :board: qemu_riscv32
24   :goals: run
25   :compact:
26
27Sample Output
28=============
29
30The program below shows sample output for a specific Zephyr build.
31
32.. code-block:: console
33
34    BOARD=qemu_riscv32
35    BUILD_VERSION=zephyr-v3.5.0-5372-g3a46f2d052c7
36    ALERT=
37
38Setting Environment Variables
39=============================
40
41The shell command below shows how to create a new environment variable or update the value
42associated with an existing environment variable.
43
44The C code that is part of this sample application displays the value associated with the
45``ALERT`` environment variable and then immediately unsets it.
46
47.. code-block:: console
48
49    uart:~$ posix env set ALERT="Happy Friday!"
50    uart:~$ ALERT="Happy Friday!"
51    uart:~$ posix env set HOME="127.0.0.1"
52    uart:~$
53
54
55Getting Environment Variables
56=============================
57
58The shell command below may be used to display the value associated with one environment variable.
59
60.. code-block:: console
61
62    uart:~$ posix env get BOARD
63    qemu_riscv32
64
65The shell command below may be used to display all environment variables and their associated
66values.
67
68.. code-block:: console
69
70    uart:~$ posix env get
71    BOARD=qemu_riscv32
72    BUILD_VERSION=zephyr-v3.5.0-5372-g3a46f2d052c7
73    ALERT=
74
75Unsetting Environment Variables
76===============================
77
78The shell command below may be used to unset environment variables.
79
80.. code-block:: console
81
82    uart:~$ posix env unset BOARD
83