samples: posix: add environment variable sample app

Add a sample application to demonstrate some basic
C and shell interfaces to manipulating environment
variables.

Signed-off-by: Christopher Friedt <cfriedt@meta.com>

samples/posix/env/CMakeLists.txt

@@ -0,0 +1,12 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(posix_env)
+
+target_sources(app PRIVATE src/main.c)
+# For setenv() and unsetenv()
+target_compile_options(app PRIVATE -U_POSIX_C_SOURCE -D_POSIX_C_SOURCE=200809L)
+# For getenv_r() visibility and testing
+target_compile_definitions(app PRIVATE _BSD_SOURCE)

samples/posix/env/README.rst

@@ -0,0 +1,82 @@
+.. _posix-env-sample:
+
+POSIX Environment Variables
+###########################
+
+Overview
+********
+
+In this sample application, the POSIX :c:func:`setenv`, function is used to populate several environment
+variables in C. Then, all environment variables are then printed.
+
+If the user sets a new value for the ``ALERT`` environment variable, it is printed to standard
+output, and then cleared via :c:func:`unsetenv`.
+
+Building and Running
+********************
+
+This project outputs to the console. It can be built and executed on QEMU as follows:
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/posix/env
+   :host-os: unix
+   :board: qemu_riscv32
+   :goals: run
+   :compact:
+
+Sample Output
+=============
+
+The program below shows sample output for a specific Zephyr build.
+
+.. code-block:: console
+
+    BOARD=qemu_riscv32
+    BUILD_VERSION=zephyr-v3.5.0-5372-g3a46f2d052c7
+    ALERT=
+
+Setting Environment Variables
+=============================
+
+The shell command below shows how to create a new environment variable or update the value
+associated with an existing environment variable.
+
+The C code that is part of this sample application displays the value associated with the
+``ALERT`` environment variable and then immediately unsets it.
+
+.. code-block:: console
+
+    uart:~$ posix env set ALERT="Happy Friday!"
+    uart:~$ ALERT="Happy Friday!"
+    uart:~$ posix env set HOME="127.0.0.1"
+    uart:~$
+
+
+Getting Environment Variables
+=============================
+
+The shell command below may be used to display the value associated with one environment variable.
+
+.. code-block:: console
+
+    uart:~$ posix env get BOARD
+    qemu_riscv32
+
+The shell command below may be used to display all environment variables and their associated
+values.
+
+.. code-block:: console
+
+    uart:~$ posix env get
+    BOARD=qemu_riscv32
+    BUILD_VERSION=zephyr-v3.5.0-5372-g3a46f2d052c7
+    ALERT=
+
+Unsetting Environment Variables
+===============================
+
+The shell command below may be used to unset environment variables.
+
+.. code-block:: console
+
+    uart:~$ posix env unset BOARD

samples/posix/env/prj.conf

@@ -0,0 +1,5 @@
+CONFIG_POSIX_API=y
+CONFIG_SHELL=y
+CONFIG_POSIX_ENV_SHELL=y
+CONFIG_DYNAMIC_THREAD=y
+CONFIG_DYNAMIC_THREAD_POOL_SIZE=1

samples/posix/env/sample.yaml

@@ -0,0 +1,19 @@
+sample:
+  description: posix env sample
+  name: posix env
+common:
+  tags: posix env
+  platform_exclude:
+    - native_posix
+    - native_posix_64
+  integration_platforms:
+    - qemu_riscv32
+  harness: console
+  harness_config:
+    type: multi_line
+    regex:
+      - "BOARD=.*"
+      - "BUILD_VERSION=.*"
+      - "ALERT=.*"
+tests:
+  sample.posix.env: {}

samples/posix/env/src/main.c

@@ -0,0 +1,65 @@
+/*
+ * Copyright (c) 2023 Meta
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "version.h"
+
+#include <pthread.h>
+#include <stdbool.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+
+#include <zephyr/sys/util.h>
+#include <zephyr/kernel.h>
+
+#ifdef BUILD_VERSION
+#define VERSION_BUILD STRINGIFY(BUILD_VERSION)
+#else
+#define VERSION_BUILD KERNEL_VERSION_STRING
+#endif
+
+static void env(void)
+{
+	extern char **environ;
+
+	if (environ != NULL) {
+		for (char **envp = environ; *envp != NULL; ++envp) {
+			printf("%s\n", *envp);
+		}
+	}
+}
+
+static void *entry(void *arg)
+{
+	static char alert_msg_buf[42];
+
+	setenv("BOARD", CONFIG_BOARD, 1);
+	setenv("BUILD_VERSION", VERSION_BUILD, 1);
+	setenv("ALERT", "", 1);
+
+	env();
+
+	while (true) {
+		sleep(1);
+		if (getenv_r("ALERT", alert_msg_buf, sizeof(alert_msg_buf) - 1) < 0 ||
+		    strlen(alert_msg_buf) == 0) {
+			continue;
+		}
+		printf("ALERT=%s\n", alert_msg_buf);
+		unsetenv("ALERT");
+	}
+
+	return NULL;
+}
+
+int main(void)
+{
+	pthread_t th;
+
+	/* create a separate thread so that the shell can start */
+	return pthread_create(&th, NULL, entry, NULL);
+}