Technical Reference: Base Operating System and Extensions, Volume 2

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>

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

int 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:

int setpgrp (ProcessID, ProcessGroup)
int ProcessID, ProcessGroup;

Parameters

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:

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.

Related Information

The getpid subroutine.