Chapter Contents

Previous

Next
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

Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.