[rtems-docs commit] user: Add shell environment migration aid

[Sebastian Huber]

Module:    rtems-docs
Branch:    5
Commit:    cb4358c9b16289d938f41d04a71dfaddb9716b0e
Changeset: http://git.rtems.org/rtems-docs/commit/?id=cb4358c9b16289d938f41d04a71dfaddb9716b0e

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Thu Aug  6 13:30:25 2020 +0200

user: Add shell environment migration aid

Update #3859.

---

 user/migration/v4_11-to-v5.rst | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/user/migration/v4_11-to-v5.rst b/user/migration/v4_11-to-v5.rst
index a0cab02..0e0fb46 100644
--- a/user/migration/v4_11-to-v5.rst
+++ b/user/migration/v4_11-to-v5.rst
@@ -126,3 +126,30 @@ interface name.
         exit(1);
       }
     }
+
+Shell Environment
+-----------------
+
+To address resource leaks in the RTEMS shell, the management of shell
+environments changed.  This change may break existing code.  Here is an example
+how a broken Telnet shell can be fixed:
+
+. code-block:: c
+
+    static void
+    telnet_shell( char *name, void *arg )
+    {
+        rtems_shell_env_t env;
+
+        /* Previous WRONG approach: memset( &env, 0, sizeof( env) ); */
+
+        /* Correct way to initialize the shell environment */
+        rtems_shell_dup_current_env( &env );
+
+        env.devname = name;
+        env.taskname = "TLNT";
+        env.login_check = NULL;
+        env.forever = false;
+
+        rtems_shell_main_loop( &env );
+    }