README.rst
1.. zephyr:code-sample:: posix-env
2 :name: Environment Variables
3
4 Manipulate environment variables from a Zephyr application.
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
