Debian Codegraph @

upstream/debian-trixie/man2/setpgid.2

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