Aksal/nuttx
3
1
Fork 1
mirror of https://github.com/apache/nuttx.git synced 2026-08-01 20:28:58 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

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

Browse source 
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>
This commit is contained in:
Xiang Xiao 2026-06-21 10:38:30 +08:00 • committed by Alan C. Assis
parent 970f2f226a
commit 95063bde15
16 changed files with 523 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

28
Documentation/components/drivers/character/serial.rst
View file

@ -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.

29
drivers/serial/pty.c
View file

@ -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

35
drivers/serial/serial.c
View file

@ -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
}
}

5
include/nuttx/serial/serial.h
View file

@ -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

8
include/nuttx/serial/tioctl.h
View file

@ -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
****************************************************************************/

5
include/unistd.h
View file

@ -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);

5
libs/libc/termios/CMakeLists.txt
View file

@ -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)

1
libs/libc/termios/Make.defs
View file

@ -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

67
libs/libc/termios/lib_tcgetpgrp.c Normal file
View file

@ -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;
}

67
libs/libc/termios/lib_tcgetsid.c Normal file
View file

@ -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;
}

59
libs/libc/termios/lib_tcsetpgrp.c Normal file
View file

@ -0,0 +1,59 @@
/****************************************************************************
* libs/libc/termios/lib_tcsetpgrp.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: tcsetpgrp
*
* Description:
* Set the foreground process group ID associated with the terminal.
*
* Input Parameters:
* fd - The 'fd' argument is an open file descriptor associated with a
* terminal.
* pgrp - The process group ID to be made the foreground process group.
*
* Returned Value:
* Upon successful completion, 0 is returned. Otherwise, -1 is returned
* and errno is set to indicate the error.
*
****************************************************************************/
int tcsetpgrp(int fd, pid_t pgrp)
{
return ioctl(fd, TIOCSPGRP, &pgrp);
}

3
libs/libc/unistd/CMakeLists.txt
View file

@ -64,6 +64,9 @@ set(SRCS
lib_usleep.c
lib_getpgrp.c
lib_getpgid.c
lib_getsid.c
lib_setpgid.c
lib_setsid.c
lib_lockf.c
lib_flock.c
lib_getpass.c

1
libs/libc/unistd/Make.defs
View file

@ -32,6 +32,7 @@ CSRCS += lib_setrlimit.c lib_getrlimit.c lib_setpriority.c lib_getpriority.c
CSRCS += lib_futimes.c lib_lutimes.c lib_gethostname.c lib_sethostname.c
CSRCS += lib_fchownat.c lib_linkat.c lib_readlinkat.c lib_symlinkat.c
CSRCS += lib_unlinkat.c lib_usleep.c lib_getpgrp.c lib_getpgid.c
CSRCS += lib_getsid.c lib_setpgid.c lib_setsid.c
CSRCS += lib_lockf.c lib_flock.c lib_getpass.c
CSRCS += lib_chdir.c lib_fchdir.c lib_confstr.c lib_ulimit.c

75
libs/libc/unistd/lib_getsid.c Normal file
View file

@ -0,0 +1,75 @@
/****************************************************************************
* libs/libc/unistd/lib_getsid.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 <unistd.h>
#include <errno.h>
#include <nuttx/sched.h>
#include <nuttx/signal.h>
/****************************************************************************
* Public Functions
****************************************************************************/
/****************************************************************************
* Name: getsid
*
* Description:
* Get the session ID of the process whose process ID is pid. NuttX does
* not implement sessions, so the session ID is the same as the process
* ID, mirroring getpgid().
*
* Input Parameters:
* pid - The process ID whose session ID is requested. A value of zero
* refers to the calling process.
*
* Returned Value:
* The session ID is returned on success. Otherwise, (pid_t)-1 is
* returned and errno is set: EINVAL if pid is negative, ESRCH if pid
* does not refer to an existing process.
*
****************************************************************************/
pid_t getsid(pid_t pid)
{
if (pid < 0)
{
set_errno(EINVAL);
return (pid_t)-1;
}
if (pid == 0)
{
return _SCHED_GETPID();
}
if (_SIG_KILL(pid, 0) < 0)
{
return (pid_t)-1;
}
return pid;
}

87
libs/libc/unistd/lib_setpgid.c Normal file
View file

@ -0,0 +1,87 @@
/****************************************************************************
* libs/libc/unistd/lib_setpgid.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 <unistd.h>
#include <errno.h>
#include <nuttx/sched.h>
#include <nuttx/signal.h>
/****************************************************************************
* Public Functions
****************************************************************************/
/****************************************************************************
* Name: setpgid
*
* Description:
* Set the process group ID of the process whose process ID is pid to
* pgid. NuttX does not implement process groups, so a process group
* always contains a single member and its ID equals the process ID.
* Consequently this stub only succeeds when the requested pgid matches
* the target pid (or is zero, which selects the target pid itself).
*
* Input Parameters:
* pid - The process whose process group ID is to be changed. A value of
* zero refers to the calling process.
* pgid - The new process group ID. A value of zero uses the target pid.
*
* Returned Value:
* Zero is returned on success. Otherwise, -1 is returned and errno is
* set: EINVAL if pgid is negative, ESRCH if pid does not exist, EPERM if
* the requested pgid cannot be honored by this single-member-group model.
*
****************************************************************************/
int setpgid(pid_t pid, pid_t pgid)
{
if (pgid < 0)
{
set_errno(EINVAL);
return -1;
}
if (pid == 0)
{
pid = _SCHED_GETPID();
}
else if (_SIG_KILL(pid, 0) < 0)
{
return -1;
}
/* A process group can only contain the single member 'pid', so the only
* legal group ID is 'pid' itself (a zero pgid selects it implicitly).
*/
if (pgid != 0 && pgid != pid)
{
set_errno(EPERM);
return -1;
}
return 0;
}

57
libs/libc/unistd/lib_setsid.c Normal file
View file

@ -0,0 +1,57 @@
/****************************************************************************
* libs/libc/unistd/lib_setsid.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 <unistd.h>
#include <nuttx/sched.h>
/****************************************************************************
* Public Functions
****************************************************************************/
/****************************************************************************
* Name: setsid
*
* Description:
* Create a new session, if the calling process is not already a process
* group leader. NuttX does not implement sessions or process groups, so
* each task is treated as its own session and process group. This stub
* therefore returns the caller's PID, which acts as the session ID.
*
* Input Parameters:
* None
*
* Returned Value:
* The session ID (the caller's PID) is returned. A failure return of
* (pid_t)-1 with errno set to EPERM is not possible here because there is
* no process-group leadership to conflict with.
*
****************************************************************************/
pid_t setsid(void)
{
return _SCHED_GETPID();
}