setpgrp(2)

1SETPGID(2)                 Linux Programmer's Manual                SETPGID(2)
2
3
4

NAME

6       setpgid, getpgid, setpgrp, getpgrp - set/get process group
7

SYNOPSIS

9       #include <unistd.h>
10
11       int setpgid(pid_t pid, pid_t pgid);
12       pid_t getpgid(pid_t pid);
13       int setpgrp(void);
14       pid_t getpgrp(void);
15

DESCRIPTION

17       setpgid()  sets the process group ID of the process specified by pid to
18       pgid.  If pid is zero, the process ID of the current process  is  used.
19       If  pgid  is  zero,  the  process ID of the process specified by pid is
20       used.  If setpgid() is used to move a process from one process group to
21       another  (as  is  done  by  some  shells when creating pipelines), both
22       process groups must be part of the same session.   In  this  case,  the
23       pgid  specifies  an existing process group to be joined and the session
24       ID of that group must match the session ID of the joining process.
25
26       getpgid() returns the process group ID of the process specified by pid.
27       If pid is zero, the process ID of the current process is used.
28
29       The call setpgrp() is equivalent to setpgid(0,0).
30
31       Similarly,  getpgrp()  is equivalent to getpgid(0).  Each process group
32       is a member of a session and each process is a member of the session of
33       which its process group is a member.
34
35       Process  groups  are used for distribution of signals, and by terminals
36       to arbitrate requests for their input: Processes  that  have  the  same
37       process group as the terminal are foreground and may read, while others
38       will block with a signal if they attempt to read.  These calls are thus
39       used  by programs such as csh(1) to create process groups in implement‐
40       ing job control.   The  TIOCGPGRP  and  TIOCSPGRP  calls  described  in
41       termios(3)  are used to get/set the process group of the control termi‐
42       nal.
43
44       If a session has a controlling terminal, CLOCAL is not set and a hangup
45       occurs,  then  the  session  leader  is  sent a SIGHUP.  If the session
46       leader exits, the SIGHUP signal will be sent to  each  process  in  the
47       foreground process group of the controlling terminal.
48
49       If  the  exit of the process causes a process group to become orphaned,
50       and if any member of the newly-orphaned process group is stopped,  then
51       a  SIGHUP  signal  followed  by  a  SIGCONT signal will be sent to each
52       process in the newly-orphaned process group.
53
54

RETURN VALUE

56       On success, setpgid() and setpgrp()  return  zero.   On  error,  -1  is
57       returned, and errno is set appropriately.
58
59       getpgid()  returns  a  process  group  on  success.   On  error,  -1 is
60       returned, and errno is set appropriately.
61
62       getpgrp() always returns the current process group.
63

ERRORS

65       EACCES An attempt was made to change the process group ID of one of the
66              children  of  the calling process and the child had already per‐
67              formed an execve() (setpgid(), setpgrp()).
68
69       EINVAL pgid is less than 0 (setpgid(), setpgrp()).
70
71       EPERM  An attempt was made to move a process into a process group in  a
72              different  session,  or to change the process group ID of one of
73              the children of the calling process and the child was in a  dif‐
74              ferent  session,  or to change the process group ID of a session
75              leader (setpgid(), setpgrp()).
76
77       ESRCH  For getpgid(): pid does not match any process.   For  setpgid():
78              pid  is  not  the current process and not a child of the current
79              process.
80

CONFORMING TO

82       The functions setpgid() and getpgrp()  conform  to  POSIX.1-2001.   The
83       function  setpgrp() is from 4.2BSD.  The function getpgid() conforms to
84       SVr4.
85

NOTES

87       A child created via fork(2) inherits its  parent's  process  group  ID.
88       The process group ID is preserved across an execve(2).
89
90       POSIX  took  setpgid()  from the BSD function setpgrp().  Also System V
91       has a function with the same name, but it is identical to setsid(2).
92
93       To get the  prototypes  under  glibc,  define  both  _XOPEN_SOURCE  and
94       _XOPEN_SOURCE_EXTENDED, or use "#define _XOPEN_SOURCE n" for some inte‐
95       ger n larger than or equal to 500.
96