tcsetpgrp()

Updated: April 19, 2023

Set the process group ID for a device

Synopsis:

#include <unistd.h>

int tcsetpgrp( int filedes,
               pid_t pgrp_id );

Arguments:

filedes
A file descriptor that's associated with the device whose process group ID you want to set.
pgrp_id
The process group ID that you want to assign to the device.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

If the process has a controlling terminal, tcsetpgrp() sets the process group ID associated with the device indicated by filedes to be pgrp_id.

It's up to the application to ensure that the file associated with filedes is the controlling terminal of the calling process and that the controlling terminal is currently associated with the session of the calling process. The application must ensure that the value of pgrp_id matches a process group ID of a process in the same session as the calling process.

Attempts to use tcsetpgrp() from a process that's a member of a background process group on a filedes associated with its controlling terminal cause the process group to be sent a SIGTTOU signal. If the calling thread is blocking SIGTTOU signals or the process is ignoring SIGTTOU signals, the process is allowed to perform the operation, and no signal is sent.

Note: In order to set the process group ID, your process must have the PROCMGR_AID_SESSION ability enabled. For more information, see procmgr_ability().

If successful, the tcsetpgrp() function causes subsequent breaks on the indicated terminal device to generate a SIGINT on all process in the given process group.

Returns:

0
Success.
-1
An error occurred (errno is set).

Errors:

EBADF
The argument filedes is invalid.
EINVAL
The argument pgrp_id is invalid.
ENOSYS
The resource manager associated with filedes doesn't support this call.
ENOTTY
The argument filedes isn't associated with a terminal device.
EPERM
The argument pgrp_id isn't part of the same session as the calling process.

Examples:

#include <unistd.h>
#include <stdlib.h>

int main( void )
  {
    /*
     * Direct breaks on stdin to me
     */
    tcsetpgrp( 0, getpid() );
    return EXIT_SUCCESS;
  }

Classification:

POSIX 1003.1

Safety:  
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes