NAME

setpgid, setpgrp − Sets the process group ID

SYNOPSIS

#include <unistd.h>
#include <sys/types.h>

int setpgid (
pid_t process_id,
pid_t process_group_id );

int setpgrp (
          pid_t process_id,
          pid_t process_group_id);

System V Habitat

#include <unistd.h>

pid_t setpgrp(void);

PARAMETERS

process_idSpecifies the ID of the process whose process group ID is to be changed. 

process_group_id
Specifies the new process group ID.

DESCRIPTION

Use the setpgid() function to add a process to an existing process group or to create a new process group within a process’s session.  The setpgid() function does not change the process group ID of a session leader. 

The setpgid() function sets the process group ID of the process identified by the process_id parameter. The process group ID is set to the value specified in the process_group_id parameter. 

If the process_id parameter contains 0 (zero), the setpgid() function sets the process group ID of the calling process.  The new value of the process group ID is the one specified in the process_group_id parameter. 

If the process_group_id parameter contains 0 (zero), the setpgid() function sets the process group ID of the specified process using the process group ID of the calling process.  The specified process is the one identified by the process_id parameter. 

The setpgid() function supports job control. 

The setpgrp() function behaves similar to the setpgid() function when you use it outside of the System V habitat.  In this case, you specify a process ID and process group ID as parameters in the call to the setpgrp() function. The setpgrp() function does not change the process group ID of a session leader.  This interface to the setpgrp() function is supported only for binary compatibility

The setpgrp() function with a void parameter is for use in the System V habitat.  When you use this version of the function, it sets the process group ID of the calling process to be equal to the process ID of the calling process.  If the function creates a new session, the new session has no controlling terminal.  This function does not change the process group-ID of a session leader.  (For information about programming in the System V habitat, see the Programmer’s Guide .) 

NOTES

AES Support Level:
Full use (setpgid())

RETURN VALUES

Upon successful completion, the setpgid() function returns a value of 0 (zero). Otherwise, the function returns a value of -1 and sets errno to indicate the error. 

If you use the setpgrp() function outside of the System V habitat, it returns a value of 0 (zero) on successful completion.  Otherwise, the function returns a value of -1 and sets errno to indicate the error. 

If you use the setpgrp() function in the System V habitat, it returns the new process group ID on successful completion. 

ERRORS

If the setpgid() function or the setpgrp() outside of the System V habitat fails, errno might be set to one of the following values:

[EACCES]The value of the process_id parameter 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 the process_group_id parameter is less than or equal to 0 (zero), or is not a valid process ID. 

[EPERM]The value of the process_group_id parameter is a valid process ID, but that process is not in the same session as the calling process. 

[EPERM]The process indicated by the process_id parameter is a session leader. 

[EPERM]The value of the process_id 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 process_group_id parameter is valid but does not match the process ID of the process indicated by the process_id parameter, and there is no process with a process group ID that matches the value of the process_group_id parameter in the same session as the calling process. 

[ESRCH]The value of the process_id parameter does not match the process ID of the calling process or of a child process of the calling process. 

RELATED INFORMATION

Functions: exec(2), fork(2), getpid(2), getsid(2), kill(2)

Programmer’s Guide