# setpgid

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           setpgid — set process group ID for job control
    


## SYNOPSIS



           #include <unistd.h>
    
           int setpgid(pid_t _pid_ , pid_t _pgid_);
    


## DESCRIPTION



           The _setpgid_() function shall either join an existing process group
           or create a new process group within the session of the calling
           process.
    
           The process group ID of a session leader shall not change.
    
           Upon successful completion, the process group ID of the process
           with a process ID that matches _pid_ shall be set to _pgid_.
    
           As a special case, if _pid_ is 0, the process ID of the calling
           process shall be used. Also, if _pgid_ is 0, the process ID of the
           indicated process shall be used.
    


## RETURN VALUE



           Upon successful completion, _setpgid_() shall return 0; otherwise,
           -1 shall be returned and _errno_ shall be set to indicate the error.
    


## ERRORS



           The _setpgid_() function shall fail if:
    
           **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 the _pgid_ argument is less than 0, or is not a
                  value supported by the implementation.
    
           **EPERM** The process indicated by the _pid_ argument is a session
                  leader.
    
           **EPERM** The value of the _pid_ argument 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 _pgid_ argument is valid but does not match
                  the process ID of the process indicated by the _pid_ argument
                  and there is no process with a process group ID that
                  matches the value of the _pgid_ argument in the same session
                  as the calling process.
    
           **ESRCH** The value of the _pid_ argument does not match the process ID
                  of the calling process or of a child process of the calling
                  process.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           The _setpgid_() function shall group processes together for the
           purpose of signaling, placement in foreground or background, and
           other job control actions.
    
           The _setpgid_() function is similar to the _setpgrp_() function of 4.2
           BSD, except that 4.2 BSD allowed the specified new process group
           to assume any value. This presents certain security problems and
           is more flexible than necessary to support job control.
    
           To provide tighter security, _setpgid_() only allows the calling
           process to join a process group already in use inside its session
           or create a new process group whose process group ID was equal to
           its process ID.
    
           When a job control shell spawns a new job, the processes in the
           job must be placed into a new process group via _setpgid_().  There
           are two timing constraints involved in this action:
    
            1. The new process must be placed in the new process group before
               the appropriate program is launched via one of the _exec_
               functions.
    
            2. The new process must be placed in the new process group before
               the shell can correctly send signals to the new process group.
    
           To address these constraints, the following actions are performed.
           The new processes call _setpgid_() to alter their own process groups
           after _fork_() but before _exec_.  This satisfies the first
           constraint. Under 4.3 BSD, the second constraint is satisfied by
           the synchronization property of _vfork_(); that is, the shell is
           suspended until the child has completed the _exec_ , thus ensuring
           that the child has completed the _setpgid_().  A new version of
           _fork_() with this same synchronization property was considered, but
           it was decided instead to merely allow the parent shell process to
           adjust the process group of its child processes via _setpgid_().
           Both timing constraints are now satisfied by having both the
           parent shell and the child attempt to adjust the process group of
           the child process; it does not matter which succeeds first.
    
           Since it would be confusing to an application to have its process
           group change after it began executing (that is, after _exec_), and
           because the child process would already have adjusted its process
           group before this, the **[EACCES]** error was added to disallow this.
    
           One non-obvious use of _setpgid_() is to allow a job control shell
           to return itself to its original process group (the one in effect
           when the job control shell was executed). A job control shell does
           this before returning control back to its parent when it is
           terminating or suspending itself as a way of restoring its job
           control ``state'' back to what its parent would expect. (Note that
           the original process group of the job control shell typically
           matches the process group of its parent, but this is not
           necessarily always the case.)
    


## FUTURE DIRECTIONS



           None.
    


* * *