drivers/serial: add job-control TTY ioctls and libc wrappers

NuttX has no real session/process-group abstraction, so the TTY layer
collapses the foreground process group onto the single dev->pid field
(pgrp == pid, one member per group).  Extend the controlling-terminal
support so portable software (e.g. dropbear, socat) that relies on
job-control primitives works without losing the existing NuttX-specific
behaviour.

Driver (serial.c, pty.c):
- TIOCSCTTY now accepts a flag: arg > 0 keeps the historical "target
  PID in arg" semantics (NSH registers the foreground command it just
  spawned), while arg == 0 selects the calling task via
  nxsched_getpid(), matching the POSIX flag convention used by
  dropbear/socat/apue.  This preserves all existing callers and makes
  the previously-dead arg==0 path deliver SIGINT correctly.
- Add TIOCGPGRP/TIOCGSID (return dev->pid) and TIOCSPGRP (set it).
- pty.c gains the same handlers against pd_pid and includes
  nuttx/sched.h for nxsched_getpid().

ioctl numbers (tioctl.h): TIOCGPGRP/TIOCSPGRP/TIOCGSID at 0x37-0x39.

libc wrappers:
- termios: tcgetpgrp(), tcsetpgrp(), tcgetsid() over the new ioctls.
- unistd: setsid()/getsid()/setpgid() stubs consistent with the
  existing getpgrp()/getpgid() single-session model (sid == pgid ==
  pid; setpgid only succeeds for pgid == pid).

Declare the new prototypes in unistd.h (tcgetsid was already in
termios.h) and register all sources in the Make.defs/CMakeLists.

Group-broadcast signalling (kill(-pgrp)) remains unsupported, so
tty signals still target the single dev->pid; a real session/process
group model is left as a follow-up.

Signed-off-by: Xiang Xiao <xiaoxiang@xiaomi.com>

Author: xiaoxiang781216

Documentation/components/drivers/character/serial.rst

@@ -35,6 +35,34 @@ Serial Device Drivers
    Also, you can customize:
    ``TTY_LAUNCH_ARGS`` ``TTY_LAUNCH_PRIORITY`` ``TTY_LAUNCH_STACKSIZE``
 
+-  **Job control / controlling terminal**. When ``CONFIG_TTY_SIGINT``
+   or ``CONFIG_TTY_SIGTSTP`` is enabled, the TTY layer can generate
+   ``SIGINT`` (Ctrl-C) and ``SIGTSTP`` (Ctrl-Z) for a foreground task.
+   NuttX does not implement POSIX sessions or process groups, so the
+   foreground process group is collapsed onto a single PID stored in
+   the driver (``pgrp == pid``, one member per group); the signal is
+   delivered with ``nxsig_kill(pid, signo)``.
+
+   The following terminal ``ioctl`` commands manage this PID:
+
+   -  ``TIOCSCTTY`` makes the terminal the controlling terminal.  The
+      ``arg`` is treated as a flag: a value of ``0`` selects the
+      calling task (the POSIX convention used by, e.g., dropbear and
+      socat), while a positive value is honored as the target PID (the
+      NuttX convention used by NSH to register a foreground command it
+      has just spawned).
+   -  ``TIOCNOTTY`` gives up the controlling terminal.
+   -  ``TIOCGPGRP`` / ``TIOCGSID`` return the foreground process group /
+      session leader PID.
+   -  ``TIOCSPGRP`` sets the foreground process group PID (a value of
+      ``0`` selects the calling task).
+
+   The C library exposes these through ``tcgetpgrp()``, ``tcsetpgrp()``,
+   ``tcgetsid()``, ``setsid()``, ``getsid()`` and ``setpgid()``.  Because
+   sending a signal to a process group (``kill(-pgrp, signo)``) is not
+   supported, TTY signals always target the single foreground PID rather
+   than an entire group.
+
 -  **User Access**. Serial drivers are, ultimately, normal
    `character drivers <#chardrivers>`__ and are accessed as other
    character drivers.

drivers/serial/pty.c

@@ -43,6 +43,7 @@
 #include <nuttx/ascii.h>
 #include <nuttx/kmalloc.h>
 #include <nuttx/mutex.h>
+#include <nuttx/sched.h>
 #include <nuttx/semaphore.h>
 #include <nuttx/fs/fs.h>
 #include <nuttx/serial/pty.h>
@@ -838,16 +839,21 @@ static int pty_ioctl(FAR struct file *filep, int cmd, unsigned long arg)
       /* Make the controlling terminal of the calling process */
 
       case TIOCSCTTY:
+      case TIOCSPGRP:
         {
-          /* Save the PID of the recipient of the SIGINT signal. */
+          /* Save the PID of the foreground process group that is to receive
+           * tty-generated signals.  A zero 'arg' selects the calling task
+           * (POSIX flag semantics); a positive 'arg' is honored as the
+           * target PID (NuttX historical semantics).
+           */
 
-          if ((int)arg < 0 || dev->pd_pid >= 0)
+          if ((int)arg < 0)
             {
               ret = -EINVAL;
             }
           else
             {
-              dev->pd_pid = (pid_t)arg;
+              dev->pd_pid = arg > 0 ? (pid_t)arg : nxsched_getpid();
               ret = 0;
             }
         }
@@ -859,6 +865,23 @@ static int pty_ioctl(FAR struct file *filep, int cmd, unsigned long arg)
           ret = 0;
         }
         break;
+
+      /* Get the foreground process group / session leader.  pgrp == pid. */
+
+      case TIOCGPGRP:
+      case TIOCGSID:
+        {
+          if (dev->pd_pid < 0)
+            {
+              ret = -ENOTTY;
+            }
+          else
+            {
+              *(FAR pid_t *)((uintptr_t)arg) = dev->pd_pid;
+              ret = 0;
+            }
+        }
+        break;
 #endif
 
       /* Any unrecognized IOCTL commands will be passed to the contained

drivers/serial/serial.c

@@ -1749,16 +1749,25 @@ static int uart_ioctl(FAR struct file *filep, int cmd, unsigned long arg)
           /* Make the controlling terminal of the calling process */
 
           case TIOCSCTTY:
+          case TIOCSPGRP:
             {
-              /* Save the PID of the recipient of the SIGINT signal. */
+              /* Save the PID of the foreground process group that is to
+               * receive tty-generated signals (SIGINT/SIGTSTP).
+               *
+               * POSIX passes a flag in 'arg' and uses the caller's PID, so
+               * a zero 'arg' selects the calling task.  NuttX historically
+               * passes the target PID directly in 'arg' (e.g. NSH registers
+               * the foreground command it just spawned), so a positive
+               * 'arg' is honored as the target PID.
+               */
 
-              if ((int)arg < 0 || dev->pid >= 0)
+              if ((int)arg < 0)
                 {
                   ret = -EINVAL;
                 }
               else
                 {
-                  dev->pid = (pid_t)arg;
+                  dev->pid = arg > 0 ? (pid_t)arg : nxsched_getpid();
                   ret = 0;
                 }
             }
@@ -1770,6 +1779,26 @@ static int uart_ioctl(FAR struct file *filep, int cmd, unsigned long arg)
               ret = 0;
             }
             break;
+
+          /* Get the foreground process group.  Since NuttX has no real
+           * process-group abstraction, the controlling task's PID doubles
+           * as the (single-member) foreground process group.
+           */
+
+          case TIOCGPGRP:
+          case TIOCGSID:
+            {
+              if (dev->pid < 0)
+                {
+                  ret = -ENOTTY;
+                }
+              else
+                {
+                  *(FAR pid_t *)((uintptr_t)arg) = dev->pid;
+                  ret = 0;
+                }
+            }
+            break;
 #endif
         }
     }

include/nuttx/serial/serial.h

@@ -335,7 +335,10 @@ struct uart_dev_s
 
 #if defined(CONFIG_TTY_SIGINT) || defined(CONFIG_TTY_SIGTSTP) || \
     defined(CONFIG_TTY_FORCE_PANIC) || defined(CONFIG_TTY_LAUNCH)
-  pid_t                pid;          /* Thread PID to receive signals (-1 if none) */
+  pid_t                pid;          /* Foreground process group / controlling-tty
+                                      * owner that receives tty signals. With no
+                                      * process-group support, pgrp == pid.
+                                      * (-1 if none) */
 #endif
 
 #ifdef CONFIG_TTY_FORCE_PANIC

include/nuttx/serial/tioctl.h

@@ -87,7 +87,7 @@
 
 /* Controlling TTY */
 
-#define TIOCSCTTY       _TIOC(0x0018)  /* Make controlling TTY: int */
+#define TIOCSCTTY       _TIOC(0x0018)  /* Make controlling TTY: int (0 == caller) */
 #define TIOCNOTTY       _TIOC(0x0019)  /* Give up controllinog TTY: void */
 
 /* Exclusive mode */
@@ -200,6 +200,12 @@
 
 #define SER_SWAP_ENABLED   (1 << 0) /* Enable/disable RX/TX swap */
 
+/* Process group / session (job control) */
+
+#define TIOCGPGRP       _TIOC(0x0037) /* Get foreground process group: FAR pid_t* */
+#define TIOCSPGRP       _TIOC(0x0038) /* Set foreground process group: FAR const pid_t* */
+#define TIOCGSID        _TIOC(0x0039) /* Get session leader: FAR pid_t* */
+
 /****************************************************************************
  * Public Type Definitions
  ****************************************************************************/

include/unistd.h

@@ -354,6 +354,11 @@ pid_t   getpgid(pid_t pid);
 pid_t   getpgrp(void);
 pid_t   gettid(void);
 pid_t   getppid(void);
+pid_t   getsid(pid_t pid);
+int     setpgid(pid_t pid, pid_t pgid);
+pid_t   setsid(void);
+pid_t   tcgetpgrp(int fd);
+int     tcsetpgrp(int fd, pid_t pgrp);
 void    _exit(int status) noreturn_function;
 unsigned int sleep(unsigned int seconds);
 int     usleep(useconds_t usec);

libs/libc/termios/CMakeLists.txt

@@ -32,4 +32,7 @@ target_sources(
           lib_tcsetattr.c
           lib_tcsendbreak.c
           lib_ttyname.c
-          lib_ttynamer.c)
+          lib_ttynamer.c
+          lib_tcgetpgrp.c
+          lib_tcsetpgrp.c
+          lib_tcgetsid.c)

libs/libc/termios/Make.defs

@@ -25,6 +25,7 @@
 CSRCS += lib_cfspeed.c lib_cfmakeraw.c lib_isatty.c lib_tcflush.c
 CSRCS += lib_tcdrain.c lib_tcflow.c lib_tcgetattr.c lib_tcsetattr.c
 CSRCS += lib_tcsendbreak.c lib_ttyname.c lib_ttynamer.c
+CSRCS += lib_tcgetpgrp.c lib_tcsetpgrp.c lib_tcgetsid.c
 
 # Add the termios directory to the build
 

libs/libc/termios/lib_tcgetpgrp.c

@@ -0,0 +1,67 @@
+/****************************************************************************
+ * libs/libc/termios/lib_tcgetpgrp.c
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.  The
+ * ASF licenses this file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the
+ * License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ ****************************************************************************/
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+#include <sys/ioctl.h>
+
+#include <unistd.h>
+
+#include <nuttx/serial/tioctl.h>
+
+/****************************************************************************
+ * Public Functions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: tcgetpgrp
+ *
+ * Description:
+ *   Return the value of the process group ID of the foreground process
+ *   group associated with the terminal.
+ *
+ * Input Parameters:
+ *   fd - The 'fd' argument is an open file descriptor associated with a
+ *        terminal.
+ *
+ * Returned Value:
+ *   Upon successful completion, the process group ID of the foreground
+ *   process group is returned.  Otherwise, (pid_t)-1 is returned and errno
+ *   is set to indicate the error.
+ *
+ ****************************************************************************/
+
+pid_t tcgetpgrp(int fd)
+{
+  pid_t pgrp;
+
+  if (ioctl(fd, TIOCGPGRP, &pgrp) < 0)
+    {
+      return (pid_t)-1;
+    }
+
+  return pgrp;
+}

libs/libc/termios/lib_tcgetsid.c

@@ -0,0 +1,67 @@
+/****************************************************************************
+ * libs/libc/termios/lib_tcgetsid.c
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.  The
+ * ASF licenses this file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the
+ * License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ ****************************************************************************/
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+#include <sys/ioctl.h>
+
+#include <termios.h>
+
+#include <nuttx/serial/tioctl.h>
+
+/****************************************************************************
+ * Public Functions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: tcgetsid
+ *
+ * Description:
+ *   Obtain the process group ID of the session for which the terminal is
+ *   the controlling terminal.
+ *
+ * Input Parameters:
+ *   fd - The 'fd' argument is an open file descriptor associated with a
+ *        terminal.
+ *
+ * Returned Value:
+ *   Upon successful completion, the session leader's process group ID is
+ *   returned.  Otherwise, (pid_t)-1 is returned and errno is set to
+ *   indicate the error.
+ *
+ ****************************************************************************/
+
+pid_t tcgetsid(int fd)
+{
+  pid_t sid;
+
+  if (ioctl(fd, TIOCGSID, &sid) < 0)
+    {
+      return (pid_t)-1;
+    }
+
+  return sid;
+}