Debian Codegraph @

upstream/debian-unstable/man2/setpgid.2

raw
1 .\" Copyright 1983-1991, Regents of the University of California.
2 .\" Copyright 2007, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: BSD-4-Clause-UC
6 .\"
7 .TH setpgid 2 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 setpgid, getpgid, setpgrp, getpgrp \- set/get process group
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <unistd.h>
16 .P
17 .BI "int setpgid(pid_t " pid ", pid_t " pgid );
18 .BI "pid_t getpgid(pid_t " pid );
19 .P
20 .BR "pid_t getpgrp(void);" " /* POSIX.1 version */"
21 .BI "[[deprecated]] pid_t getpgrp(pid_t " pid ");\f[R] /* BSD version */\f[]"
22 .P
23 .BR "int setpgrp(void);" " /* System V version */"
24 .BI "[[deprecated]] int setpgrp(pid_t " pid ", pid_t " pgid ");\f[R] /* BSD version */\f[]"
25 .fi
26 .P
27 .RS -4
28 Feature Test Macro Requirements for glibc (see
29 .BR feature_test_macros (7)):
30 .RE
31 .P
32 .BR getpgid ():
33 .nf
34 _XOPEN_SOURCE >= 500
35 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
36 || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
37 .fi
38 .P
39 .BR setpgrp "() (POSIX.1):"
40 .nf
41 _XOPEN_SOURCE >= 500
42 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
43 || /* Since glibc 2.19: */ _DEFAULT_SOURCE
44 || /* glibc <= 2.19: */ _SVID_SOURCE
45 .fi
46 .P
47 .BR setpgrp "() (BSD),"
48 .BR getpgrp "() (BSD):"
49 .nf
50 [These are available only before glibc 2.19]
51 _BSD_SOURCE &&
52 ! (_POSIX_SOURCE || _POSIX_C_SOURCE || _XOPEN_SOURCE
53 || _GNU_SOURCE || _SVID_SOURCE)
54 .fi
55 .SH DESCRIPTION
56 All of these interfaces are available on Linux,
57 and are used for getting and setting the
58 process group ID (PGID) of a process.
59 The preferred, POSIX.1-specified ways of doing this are:
60 .BR getpgrp (void),
61 for retrieving the calling process's PGID;
62 and
63 .BR setpgid (),
64 for setting a process's PGID.
65 .P
66 .BR setpgid ()
67 sets the PGID of the process specified by
68 .I pid
69 to
70 .IR pgid .
71 If
72 .I pid
73 is zero, then the process ID of the calling process is used.
74 If
75 .I pgid
76 is zero, then the PGID of the process specified by
77 .I pid
78 is made the same as its process ID.
79 If
80 .BR setpgid ()
81 is used to move a process from one process
82 group to another (as is done by some shells when creating pipelines),
83 both process groups must be part of the same session (see
84 .BR setsid (2)
85 and
86 .BR credentials (7)).
87 In this case,
88 the
89 .I pgid
90 specifies an existing process group to be joined and the
91 session ID of that group must match the session ID of the joining process.
92 .P
93 The POSIX.1 version of
94 .BR getpgrp (),
95 which takes no arguments,
96 returns the PGID of the calling process.
97 .P
98 .BR getpgid ()
99 returns the PGID of the process specified by
100 .IR pid .
101 If
102 .I pid
103 is zero, the process ID of the calling process is used.
104 (Retrieving the PGID of a process other than the caller is rarely
105 necessary, and the POSIX.1
106 .BR getpgrp ()
107 is preferred for that task.)
108 .P
109 The System\ V-style
110 .BR setpgrp (),
111 which takes no arguments, is equivalent to
112 .IR "setpgid(0,\ 0)" .
113 .P
114 The BSD-specific
115 .BR setpgrp ()
116 call, which takes arguments
117 .I pid
118 and
119 .IR pgid ,
120 is a wrapper function that calls
121 .P
122 .in +4n
123 .EX
124 setpgid(pid, pgid)
125 .EE
126 .in
127 .P
128 .\" The true BSD setpgrp() system call differs in allowing the PGID
129 .\" to be set to arbitrary values, rather than being restricted to
130 .\" PGIDs in the same session.
131 Since glibc 2.19, the BSD-specific
132 .BR setpgrp ()
133 function is no longer exposed by
134 .IR <unistd.h> ;
135 calls should be replaced with the
136 .BR setpgid ()
137 call shown above.
138 .P
139 The BSD-specific
140 .BR getpgrp ()
141 call, which takes a single
142 .I pid
143 argument, is a wrapper function that calls
144 .P
145 .in +4n
146 .EX
147 getpgid(pid)
148 .EE
149 .in
150 .P
151 Since glibc 2.19, the BSD-specific
152 .BR getpgrp ()
153 function is no longer exposed by
154 .IR <unistd.h> ;
155 calls should be replaced with calls to the POSIX.1
156 .BR getpgrp ()
157 which takes no arguments (if the intent is to obtain the caller's PGID),
158 or with the
159 .BR getpgid ()
160 call shown above.
161 .SH RETURN VALUE
162 On success,
163 .BR setpgid ()
164 and
165 .BR setpgrp ()
166 return zero.
167 On error, \-1 is returned, and
168 .I errno
169 is set to indicate the error.
170 .P
171 The POSIX.1
172 .BR getpgrp ()
173 always returns the PGID of the caller.
174 .P
175 .BR getpgid (),
176 and the BSD-specific
177 .BR getpgrp ()
178 return a process group on success.
179 On error, \-1 is returned, and
180 .I errno
181 is set to indicate the error.
182 .SH ERRORS
183 .TP
184 .B EACCES
185 An attempt was made to change the process group ID
186 of one of the children of the calling process and the child had
187 already performed an
188 .BR execve (2)
189 .RB ( setpgid (),
190 .BR setpgrp ()).
191 .TP
192 .B EINVAL
193 .I pgid
194 is less than 0
195 .RB ( setpgid (),
196 .BR setpgrp ()).
197 .TP
198 .B EPERM
199 An attempt was made to move a process into a process group in a
200 different session, or to change the process
201 group ID of one of the children of the calling process and the
202 child was in a different session, or to change the process group ID of
203 a session leader
204 .RB ( setpgid (),
205 .BR setpgrp ()).
206 .TP
207 .B EPERM
208 The target process group does not exist.
209 .RB ( setpgid (),
210 .BR setpgrp ()).
211 .TP
212 .B ESRCH
213 For
214 .BR getpgid ():
215 .I pid
216 does not match any process.
217 For
218 .BR setpgid ():
219 .I pid
220 is not the calling process and not a child of the calling process.
221 .SH STANDARDS
222 .TP
223 .BR getpgid ()
224 .TQ
225 .BR setpgid ()
226 .TQ
227 .BR getpgrp "() (no args)"
228 POSIX.1-2024.
229 .TP
230 .BR setpgrp ()
231 .TQ
232 .BR getpgrp "() (1 arg)"
233 None.
234 .SH HISTORY
235 .TP
236 .BR getpgid ()
237 .TQ
238 .BR setpgid ()
239 .TQ
240 .BR getpgrp "() (no args)"
241 POSIX.1-2001.
242 .TP
243 .BR setpgrp "() (no args)"
244 POSIX.1-2001.
245 Obsoleted in POSIX.1-2008.
246 Removed in POSIX.1-2024.
247 .TP
248 .BR setpgrp "() (2 args)"
249 .TQ
250 .BR getpgrp "() (1 arg)"
251 4.2BSD.
252 .SH NOTES
253 A child created via
254 .BR fork (2)
255 inherits its parent's process group ID.
256 The PGID is preserved across an
257 .BR execve (2).
258 .P
259 Each process group is a member of a session and each process is a
260 member of the session of which its process group is a member.
261 (See
262 .BR credentials (7).)
263 .P
264 A session can have a controlling terminal.
265 At any time, one (and only one) of the process groups
266 in the session can be the foreground process group
267 for the terminal;
268 the remaining process groups are in the background.
269 If a signal is generated from the terminal (e.g., typing the
270 interrupt key to generate
271 .BR SIGINT ),
272 that signal is sent to the foreground process group.
273 (See
274 .BR termios (3)
275 for a description of the characters that generate signals.)
276 Only the foreground process group may
277 .BR read (2)
278 from the terminal;
279 if a background process group tries to
280 .BR read (2)
281 from the terminal, then the group is sent a
282 .B SIGTTIN
283 signal, which suspends it.
284 The
285 .BR tcgetpgrp (3)
286 and
287 .BR tcsetpgrp (3)
288 functions are used to get/set the foreground
289 process group of the controlling terminal.
290 .P
291 The
292 .BR setpgid ()
293 and
294 .BR getpgrp ()
295 calls are used by programs such as
296 .BR bash (1)
297 to create process groups in order to implement shell job control.
298 .P
299 If the termination of a process causes a process group to become orphaned,
300 and if any member of the newly orphaned process group is stopped, then a
301 .B SIGHUP
302 signal followed by a
303 .B SIGCONT
304 signal will be sent to each process
305 in the newly orphaned process group.
306 .\" exit.3 refers to the following text:
307 An orphaned process group is one in which the parent of
308 every member of process group is either itself also a member
309 of the process group or is a member of a process group
310 in a different session (see also
311 .BR credentials (7)).
312 .SH SEE ALSO
313 .BR getuid (2),
314 .BR setsid (2),
315 .BR tcgetpgrp (3),
316 .BR tcsetpgrp (3),
317 .BR termios (3),
318 .BR credentials (7)