setpgid or setpgrp Subroutine

Purpose

Sets the process group ID.

Libraries

setpgid: Standard C Library (libc.a)

setpgrp: Standard C Library (libc.a);

Berkeley Compatibility Library (libbsd.a)

Syntax

#include <unistd.h>

pid_t setpgid ( ProcessID,  ProcessGroupID)
pid_t ProcessID, ProcessGroupID;

pid_t setpgrp ( )

Description

The setpgid subroutine 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 does not change. Upon return, the process group ID of the process having a process ID that matches the ProcessID value is set to the ProcessGroupID value. As a special case, if the ProcessID value is 0, the process ID of the calling process is used. If ProcessGroupID value is 0, the process ID of the indicated process is used.

This function is implemented to support job control.

The setpgrp subroutine in the libc.a library supports a subset of the function of the setpgid subroutine. It has no parameters. It sets the process group ID of the calling process to be the same as its process ID and returns the new value.

In BSD systems, the setpgrp subroutine is defined with two parameters, as follows:

 

pid_t setpgrp (ProcessID, ProcessGroup)
pid_t ProcessID, ProcessGroup;

Parameters

Item Description
ProcessID Specifies the process whose process group ID is to be changed.
ProcessGroupID Specifies the new value of calling process group ID.

Return Values

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

The setpgid subroutine is unsuccessful if one or more of the following is true:

Item Description
EACCES The value of the ProcessID parameter matches the process ID of a child process of the calling process and the child process has successfully executed one of the exec subroutines.
EINVAL The value of the ProcessGroupID parameter is less than 0, or is not a valid value.
ENOSYS The setpgid subroutine is not supported by this implementation.
EPERM The process indicated by the value of the ProcessID parameter is a session leader.
EPERM The value of the ProcessID parameter matches the process ID of a child process of the calling process and the child process is not in the same session as the calling process.
EPERM The value of the ProcessGroupID parameter is valid, but does not match the process ID of the process indicated by the ProcessID parameter. There is no process with a process group ID that matches the value of the ProcessGroupID parameter in the same session as the calling process.
ESRCH The value of the ProcessID parameter does not match the process ID of the calling process of a child process of the calling process.