tcsetpgrp

tcsetpgrp

Set Foreground Process Group Identification

Portability: POSIX.1 conforming

SYNOPSIS
DESCRIPTION
RETURN VALUE
EXAMPLE
RELATED FUNCTIONS

SYNOPSIS

#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 SIGTTIN 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 .)

Note: If tcsetpgrp is called from a background process, the signal SIGTTOU is generated, unless the signal is ignored or blocked. If the signal is defaulted, this will cause the calling process to stop. If the signal is handled, tcsetpgrp will set errno to EINTR and fail. For this reason, you should ignore or block SIGTTOU if you call tcsetpgrp from a background process. [cautionend]

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. [cautionend]

RELATED FUNCTIONS

tcgetpgrp

Chapter Contents
Previous
Next
Top of Page