setpgid()

Join or create a process group

Synopsis:

#include <unistd.h>

int setpgid( pid_t pid,
             pid_t pgid );

This function is declared in <process.h>, which <unistd.h> includes.

Arguments:

pid: 0, or the ID of the process whose process group you want to set.
pgid: 0, or the process group ID that you want to join or create.

Library:

libc

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

Description:

The setpgid() function is used either to join an existing process group or to create a new process group within the session of the calling process. The process group ID of a session leader doesn't change.

The following definitions are worth mentioning:

Process: An executing instance of a program, identified by a nonnegative integer called a process ID.
Process group: A collection of one or more processes, with a unique process group ID. A process group ID is a positive integer.

On successful completion, the process group ID of the process with a process ID matching pid is set to pgid. As a special case, you can specify either pid or pgid as zero, meaning that the process ID of the calling process is to be used.

Returns:

0: Success.
-1: An error occurred; errno is set.

Errors:

EACCES: The value of the pid argument matches the process ID of a child process of the calling process, and the child process has successfully executed one of the exec*() functions.
EINVAL: The value of pgid is less than zero.
ENOSYS: The setpgid() function isn't supported by this implementation (included for POSIX compatibility).
EPERM: The calling process doesn't have sufficient privilege to set the process group id pgid on process pid.
ESRCH: The process pid doesn't exist.

Examples:

/*
 * The process joins process group 0.
 */
#include <stdio.h>
#include <sys/types.h>
#include <unistd.h>
#include <stdlib.h>

int main( void )
  {
    if( setpgid( getpid(), 0 ) == -1 ) {
        perror( "setpgid" );
    }
    printf( "%d belongs to process group %d\n",
         getpid(), getpgrp() );
    return EXIT_SUCCESS;
  }

Classification:

POSIX 1003.1

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