tcsetpgrp() — Set the foreground process group ID

Standards

Standards / Extensions	C or C++	Dependencies
POSIX.1 XPG4 XPG4.2 Single UNIX Specification, Version 3	both

Format

#define _POSIX_SOURCE
#include <unistd.h>

int tcsetpgrp(int fildes, pid_t newid);

General description

Sets the process group ID (PGID) of the foreground process group associated with the terminal referred to by fildes. This terminal must be the controlling terminal of the process calling tcsetpgrp() and must be currently associated with the session of the calling process. newid must match a PGID of a process in the same session as the calling process.

After the PGID associated with the terminal is set, reads by the process group formerly associated with the terminal fail or cause the process group to stop from a SIGTTIN signal. Writes may also cause the process to stop (from a SIGTTOU signal), or they may succeed, depending on how tcsetattr() sets TOSTOP and the signal options for SIGTTOU.

fildes can be any of the descriptors representing the controlling terminal (such as standard input, standard output, and standard error), and the function affects future access from any file descriptor in use for the terminal. Consider using redirection when specifying the file descriptor.

If tcsetpgrp() is called from a background process group against the caller's controlling terminal, a SIGTTOU signal may be generated depending how the process is handling SIGTTOUs:

Processing for SIGTTOU	System Behavior
Default or signal handler	The SIGTTOU signal is generated, and the function is not performed. tcsetpgrp() returns -1 and sets errno to EINTR.
Ignored or blocked	The SIGTTOU signal is not sent, and the function continues normally.

Returned value

If successful, tcsetpgrp() returns 0.

If unsuccessful, tcsetpgrp() returns -1 and sets errno to one of the following values:

Error Code: Description
EBADF: fildes is not a valid open file descriptor.
EINTR: A signal interrupted the tcsetpgrp() function.
EINVAL: The newid value is not supported by this implementation.
ENOTTY: The process calling tcsetpgrp() does not have a controlling terminal, or fildes is not associated with the controlling terminal, or the controlling terminal is no longer associated with the session of the calling process.
EPERM: The newid value is supported by the implementation but does not match the process group ID of any process in the same session as the process calling tcsetpgrp().

Example

CELEBT10

⁄* CELEBT10

   This example changes the PGID.

 *⁄
#define _POSIX_SOURCE
#include <termios.h>
#include <unistd.h>
#include <sys⁄wait.h>
#include <stdio.h>
#include <signal.h>

main() {
  pid_t pid;
  int status;

  if (fork() == 0)
    if ((pid = tcgetpgrp(STDOUT_FILENO)) < 0)
      perror("tcgetpgrp() error");
    else {
      printf("original foreground process group id of stdout was %d\n",
             (int) pid);
      if (setpgid(getpid(), 0) != 0)
        perror("setpgid() error");
      else {
        printf("now setting to %d\n", (int) getpid());
        if (tcsetpgrp(STDOUT_FILENO, getpid()) != 0)
          perror("tcsetpgrp() error");
        else if ((pid = tcgetpgrp(STDOUT_FILENO)) < 0)
          perror("tcgetpgrp() error");
        else
          printf("new foreground process group id of stdout was %d\n",
                 (int) pid);
      }
    }

  else wait(&status);
}

Output

original foreground process group id of stdout was 2228230
now setting to 2949128
new foreground process group id of stdout was 2949128