1SETPGID(3P)                POSIX Programmer's Manual               SETPGID(3P)
2
3
4

PROLOG

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

NAME

12       setpgid - set process group ID for job control
13

SYNOPSIS

15       #include <unistd.h>
16
17       int setpgid(pid_t pid, pid_t pgid);
18
19

DESCRIPTION

21       The setpgid() function shall either join an existing process  group  or
22       create  a  new process group within the session of the calling process.
23       The process group ID of a session leader shall not  change.  Upon  suc‐
24       cessful  completion, the process group ID of the process with a process
25       ID that matches pid shall be set to pgid. As a special case, if pid  is
26       0,  the  process ID of the calling process shall be used. Also, if pgid
27       is 0, the process ID of the indicated process shall be used.
28

RETURN VALUE

30       Upon successful completion, setpgid() shall  return  0;  otherwise,  -1
31       shall be returned and errno shall be set to indicate the error.
32

ERRORS

34       The setpgid() function shall fail if:
35
36       EACCES The  value of the pid argument matches the process ID of a child
37              process of the calling process and the child  process  has  suc‐
38              cessfully executed one of the exec functions.
39
40       EINVAL The value of the pgid argument is less than 0, or is not a value
41              supported by the implementation.
42
43       EPERM  The process indicated by the pid argument is a session leader.
44
45       EPERM  The value of the pid argument matches the process ID of a  child
46              process  of  the calling process and the child process is not in
47              the same session as the calling process.
48
49       EPERM  The value of the pgid argument is valid but does not  match  the
50              process  ID  of  the  process  indicated by the pid argument and
51              there is no process with a process group  ID  that  matches  the
52              value  of  the  pgid argument in the same session as the calling
53              process.
54
55       ESRCH  The value of the pid argument does not match the process  ID  of
56              the  calling  process  or  of  a  child  process  of the calling
57              process.
58
59
60       The following sections are informative.
61

EXAMPLES

63       None.
64

APPLICATION USAGE

66       None.
67

RATIONALE

69       The setpgid() function shall group processes together for  the  purpose
70       of signaling, placement in foreground or background, and other job con‐
71       trol actions.
72
73       The setpgid() function is similar to the setpgrp() function of 4.2 BSD,
74       except  that  4.2 BSD allowed the specified new process group to assume
75       any value. This presents certain security problems and is more flexible
76       than necessary to support job control.
77
78       To  provide tighter security, setpgid() only allows the calling process
79       to join a process group already in use inside its session or  create  a
80       new process group whose process group ID was equal to its process ID.
81
82       When  a  job  control  shell spawns a new job, the processes in the job
83       must be placed into a new process group via setpgid().  There  are  two
84       ti