setpgid()

Join or create a process group

Synopsis:

#include <process.h>

int setpgid( pid_t pid,
             pid_t pgid );

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>
#include <process.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

See also:

errno, getpgid(), getsid(), setsid()