-
Notifications
You must be signed in to change notification settings - Fork 0
/
setpgrp.html
340 lines (256 loc) · 10.7 KB
/
setpgrp.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
<!-- Creator : groff version 1.22.4 -->
<!-- CreationDate: Wed Jan 29 11:25:43 2020 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
p { margin-top: 0; margin-bottom: 0; vertical-align: top }
pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
table { margin-top: 0; margin-bottom: 0; vertical-align: top }
h1 { text-align: center }
</style>
<title>SETPGID</title>
</head>
<body>
<h1 align="center">SETPGID</h1>
<a href="#NAME">NAME</a><br>
<a href="#SYNOPSIS">SYNOPSIS</a><br>
<a href="#DESCRIPTION">DESCRIPTION</a><br>
<a href="#RETURN VALUE">RETURN VALUE</a><br>
<a href="#ERRORS">ERRORS</a><br>
<a href="#CONFORMING TO">CONFORMING TO</a><br>
<a href="#NOTES">NOTES</a><br>
<a href="#SEE ALSO">SEE ALSO</a><br>
<a href="#COLOPHON">COLOPHON</a><br>
<hr>
<h2>NAME
<a name="NAME"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">setpgid,
getpgid, setpgrp, getpgrp - set/get process group</p>
<h2>SYNOPSIS
<a name="SYNOPSIS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>#include
<sys/types.h> <br>
#include <unistd.h></b></p>
<p style="margin-left:11%; margin-top: 1em"><b>int
setpgid(pid_t</b> <i>pid</i><b>, pid_t</b> <i>pgid</i><b>);
<br>
pid_t getpgid(pid_t</b> <i>pid</i><b>);</b></p>
<p style="margin-left:11%; margin-top: 1em"><b>pid_t
getpgrp(void);</b> /* POSIX.1 version */ <b><br>
pid_t getpgrp(pid_t</b>
<i>pid</i><b>); </b>
/* BSD version */</p>
<p style="margin-left:11%; margin-top: 1em"><b>int
setpgrp(void);</b> /* System V version */ <b><br>
int setpgrp(pid_t</b> <i>pid</i><b>, pid_t</b>
<i>pgid</i><b>); </b> /* BSD version */</p>
<p style="margin-left:5%; margin-top: 1em">Feature Test
Macro Requirements for glibc (see
<b>feature_test_macros</b>(7)):</p>
<p style="margin-left:11%; margin-top: 1em"><b>getpgid</b>():</p>
<p style="margin-left:17%;">_XOPEN_SOURCE >= 500
<br>
|| /* Since glibc 2.12: */
_POSIX_C_SOURCE >= 200809L</p>
<p style="margin-left:11%; margin-top: 1em"><b>setpgrp</b>()
(POSIX.1): <br>
_XOPEN_SOURCE >= 500 <br>
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE <br>
|| /* Glibc versions <= 2.19: */ _SVID_SOURCE</p>
<p style="margin-left:11%; margin-top: 1em"><b>setpgrp</b>() (BSD),
<b>getpgrp</b>() (BSD): <br>
[These are available only before glibc 2.19] <br>
_BSD_SOURCE && <br>
! (_POSIX_SOURCE || _POSIX_C_SOURCE || _XOPEN_SOURCE ||
<br>
_GNU_SOURCE || _SVID_SOURCE)</p>
<h2>DESCRIPTION
<a name="DESCRIPTION"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">All of these
interfaces are available on Linux, and are used for getting
and setting the process group ID (PGID) of a process. The
preferred, POSIX.1-specified ways of doing this are:
<b>getpgrp</b>(void), for retrieving the calling
process’s PGID; and <b>setpgid</b>(), for setting a
process’s PGID.</p>
<p style="margin-left:11%; margin-top: 1em"><b>setpgid</b>()
sets the PGID of the process specified by <i>pid</i> to
<i>pgid</i>. If <i>pid</i> is zero, then the process ID of
the calling process is used. If <i>pgid</i> is zero, then
the PGID of the process specified by <i>pid</i> is made the
same as its process ID. If <b>setpgid</b>() is used to move
a process from one process group to another (as is done by
some shells when creating pipelines), both process groups
must be part of the same session (see <b>setsid</b>(2) and
<b>credentials</b>(7)). In this case, the <i>pgid</i>
specifies an existing process group to be joined and the
session ID of that group must match the session ID of the
joining process.</p>
<p style="margin-left:11%; margin-top: 1em">The POSIX.1
version of <b>getpgrp</b>(), which takes no arguments,
returns the PGID of the calling process.</p>
<p style="margin-left:11%; margin-top: 1em"><b>getpgid</b>()
returns the PGID of the process specified by <i>pid</i>. If
<i>pid</i> is zero, the process ID of the calling process is
used. (Retrieving the PGID of a process other than the
caller is rarely necessary, and the POSIX.1 <b>getpgrp</b>()
is preferred for that task.)</p>
<p style="margin-left:11%; margin-top: 1em">The
System V-style <b>setpgrp</b>(), which takes no
arguments, is equivalent to <i>setpgid(0, 0)</i>.</p>
<p style="margin-left:11%; margin-top: 1em">The
BSD-specific <b>setpgrp</b>() call, which takes arguments
<i>pid</i> and <i>pgid</i>, is a wrapper function that
calls</p>
<p style="margin-left:11%; margin-top: 1em">setpgid(pid,
pgid)</p>
<p style="margin-left:11%; margin-top: 1em">Since glibc
2.19, the BSD-specific <b>setpgrp</b>() function is no
longer exposed by <i><unistd.h></i>; calls should be
replaced with the <b>setpgid</b>() call shown above.</p>
<p style="margin-left:11%; margin-top: 1em">The
BSD-specific <b>getpgrp</b>() call, which takes a single
<i>pid</i> argument, is a wrapper function that calls</p>
<p style="margin-left:11%; margin-top: 1em">getpgid(pid)</p>
<p style="margin-left:11%; margin-top: 1em">Since glibc
2.19, the BSD-specific <b>getpgrp</b>() function is no
longer exposed by <i><unistd.h></i>; calls should be
replaced with calls to the POSIX.1 <b>getpgrp</b>() which
takes no arguments (if the intent is to obtain the
caller’s PGID), or with the <b>getpgid</b>() call
shown above.</p>
<h2>RETURN VALUE
<a name="RETURN VALUE"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">On success,
<b>setpgid</b>() and <b>setpgrp</b>() return zero. On error,
-1 is returned, and <i>errno</i> is set appropriately.</p>
<p style="margin-left:11%; margin-top: 1em">The POSIX.1
<b>getpgrp</b>() always returns the PGID of the caller.</p>
<p style="margin-left:11%; margin-top: 1em"><b>getpgid</b>(),
and the BSD-specific <b>getpgrp</b>() return a process group
on success. On error, -1 is returned, and <i>errno</i> is
set appropriately.</p>
<h2>ERRORS
<a name="ERRORS"></a>
</h2>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p style="margin-top: 1em"><b>EACCES</b></p></td>
<td width="2%"></td>
<td width="78%">
<p style="margin-top: 1em">An attempt was made to change
the process group ID of one of the children of the calling
process and the child had already performed an
<b>execve</b>(2) (<b>setpgid</b>(), <b>setpgrp</b>()).</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EINVAL</b></p></td>
<td width="2%"></td>
<td width="78%">
<p><i>pgid</i> is less than 0 (<b>setpgid</b>(),
<b>setpgrp</b>()).</p> </td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EPERM</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>An attempt was made to move a process into a process
group in a different session, or to change the process group
ID of one of the children of the calling process and the
child was in a different session, or to change the process
group ID of a session leader (<b>setpgid</b>(),
<b>setpgrp</b>()).</p> </td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>ESRCH</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>For <b>getpgid</b>(): <i>pid</i> does not match any
process. For <b>setpgid</b>(): <i>pid</i> is not the calling
process and not a child of the calling process.</p></td></tr>
</table>
<h2>CONFORMING TO
<a name="CONFORMING TO"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>setpgid</b>()
and the version of <b>getpgrp</b>() with no arguments
conform to POSIX.1-2001.</p>
<p style="margin-left:11%; margin-top: 1em">POSIX.1-2001
also specifies <b>getpgid</b>() and the version of
<b>setpgrp</b>() that takes no arguments. (POSIX.1-2008
marks this <b>setpgrp</b>() specification as obsolete.)</p>
<p style="margin-left:11%; margin-top: 1em">The version of
<b>getpgrp</b>() with one argument and the version of
<b>setpgrp</b>() that takes two arguments derive from
4.2BSD, and are not specified by POSIX.1.</p>
<h2>NOTES
<a name="NOTES"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">A child created
via <b>fork</b>(2) inherits its parent’s process group
ID. The PGID is preserved across an <b>execve</b>(2).</p>
<p style="margin-left:11%; margin-top: 1em">Each process
group is a member of a session and each process is a member
of the session of which its process group is a member. (See
<b>credentials</b>(7).)</p>
<p style="margin-left:11%; margin-top: 1em">A session can
have a controlling terminal. At any time, one (and only one)
of the process groups in the session can be the foreground
process group for the terminal; the remaining process groups
are in the background. If a signal is generated from the
terminal (e.g., typing the interrupt key to generate
<b>SIGINT</b>), that signal is sent to the foreground
process group. (See <b>termios</b>(3) for a description of
the characters that generate signals.) Only the foreground
process group may <b>read</b>(2) from the terminal; if a
background process group tries to <b>read</b>(2) from the
terminal, then the group is sent a <b>SIGTTIN</b> signal,
which suspends it. The <b>tcgetpgrp</b>(3) and
<b>tcsetpgrp</b>(3) functions are used to get/set the
foreground process group of the controlling terminal.</p>
<p style="margin-left:11%; margin-top: 1em">The
<b>setpgid</b>() and <b>getpgrp</b>() calls are used by
programs such as <b>bash</b>(1) to create process groups in
order to implement shell job control.</p>
<p style="margin-left:11%; margin-top: 1em">If the
termination of a process causes a process group to become
orphaned, and if any member of the newly orphaned process
group is stopped, then a <b>SIGHUP</b> signal followed by a
<b>SIGCONT</b> signal will be sent to each process in the
newly orphaned process group. An orphaned process group is
one in which the parent of every member of process group is
either itself also a member of the process group or is a
member of a process group in a different session (see also
<b>credentials</b>(7)).</p>
<h2>SEE ALSO
<a name="SEE ALSO"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>getuid</b>(2),
<b>setsid</b>(2), <b>tcgetpgrp</b>(3), <b>tcsetpgrp</b>(3),
<b>termios</b>(3), <b>credentials</b>(7)</p>
<h2>COLOPHON
<a name="COLOPHON"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">This page is
part of release 5.02 of the Linux <i>man-pages</i> project.
A description of the project, information about reporting
bugs, and the latest version of this page, can be found at
https://www.kernel.org/doc/man-pages/.</p>
<hr>
</body>
</html>