tcsetpgrp -- Set Foreground Process Group Identification

SYNOPSIS

 #include <sys/types.h>
 #include <unistd.h>

 int tcsetpgrp(int fileDescriptor, pid_t processID);

DESCRIPTION

tcsetpgrp sets the process group identification (PGID) for the foreground process group associated with a controlling terminal. The arguments to tcsetpgrp are:

fileDescriptor: is a file discriptor that refers to a terminal device. The file descriptor must be for the controlling terminal associated with the process calling tcsetpgrp.
processID: is a foreground process group identification number (PGID) from the same session as the process calling tcsetpgrp.

The tcgetpgrp function can be called from a background process to obtain the PGID of a foreground process group. The process can then change from the background group to the foreground process group by making a call to tcsetpgrp and specifying the PGID of the new foreground group as one of the arguments passed to tcsetpgrp.

After the PGID for a terminal has been changed, reads by the process group that was associated with the terminal prior to the call to tcsetpgrp either fail or cause the generation of a SIGTTIN signal. A SITTIN signal causes the process group to stop. Depending upon the setting of the TOSTOP bit in the termios structure, writes may also cause the process group to stop due to the generation of a SIGTTOU signal. (Refer to the tcsetattr function for a description of termios.)

RETURN VALUE

If successful, tcsetpgrp returns a 0, and a -1 is returned if unsuccessful.

EXAMPLE

The following example illustrates the use of tcsetpgrp to set the PGID for stdin:

  #include <sys/types.h>
  #include <termios.h>
  #include <unistd.h>
  #include <stdio.h>
  #include <stdlib.h>

  main()
  {
     pid_t stdin_PGID;

        /* Get the PGIDs for stdin. */
     stdin_PGID = tcgetpgrp(STDIN_FILENO);
     if (stdin_PGID == -1) {
        printf("Could not get PGID for stdin.n");
        return(EXIT_FAILURE);
     }
     else if (tcsetpgrp(STDIN_FILENO, stdin_PGID) == -1) {
        printf("Could not set PGID.n");
        return(EXIT_FAILURE);
     }

     printf("The PGID has been changed to %d.n", stdin_PGID);
     return(EXIT_SUCCESS);
  }

Note: Also see the setpgid example.

RELATED FUNCTIONS

tcgetpgrp