]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1983, 1991 Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
4 | .\" Redistribution and use in source and binary forms, with or without | |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
12 | .\" 3. All advertising materials mentioning features or use of this software | |
13 | .\" must display the following acknowledgement: | |
14 | .\" This product includes software developed by the University of | |
15 | .\" California, Berkeley and its contributors. | |
16 | .\" 4. Neither the name of the University nor the names of its contributors | |
17 | .\" may be used to endorse or promote products derived from this software | |
18 | .\" without specific prior written permission. | |
19 | .\" | |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
30 | .\" SUCH DAMAGE. | |
31 | .\" | |
32 | .\" @(#)getpgrp.2 6.4 (Berkeley) 3/10/91 | |
33 | .\" | |
34 | .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu> | |
35 | .\" Modified 1995-04-15 by Michael Chastain <mec@shell.portal.com>: | |
36 | .\" Added 'getpgid'. | |
37 | .\" Modified 1996-07-21 by Andries Brouwer <aeb@cwi.nl> | |
38 | .\" Modified 1996-11-06 by Eric S. Raymond <esr@thyrsus.com> | |
39 | .\" Modified 1999-09-02 by Michael Haardt <michael@moria.de> | |
305a0578 | 40 | .\" Modified 2002-01-18 by Michael Kerrisk <mtk-manpages@gmx.net> |
fea681da MK |
41 | .\" Modified 2003-01-20 by Andries Brouwer <aeb@cwi.nl> |
42 | .\" | |
43 | .TH SETPGID 2 2003-01-20 "Linux" "Linux Programmer's Manual" | |
44 | .SH NAME | |
45 | setpgid, getpgid, setpgrp, getpgrp \- set/get process group | |
46 | .SH SYNOPSIS | |
47 | .B #include <unistd.h> | |
48 | .sp | |
49 | .BI "int setpgid(pid_t " pid ", pid_t " pgid ); | |
50 | .br | |
51 | .BI "pid_t getpgid(pid_t " pid ); | |
52 | .br | |
53 | .B int setpgrp(void); | |
54 | .br | |
55 | .B pid_t getpgrp(void); | |
56 | .SH DESCRIPTION | |
e511ffb6 | 57 | .BR setpgid () |
fea681da MK |
58 | sets the process group ID of the process specified by |
59 | .I pid | |
60 | to | |
61 | .IR pgid . | |
62 | If | |
63 | .I pid | |
64 | is zero, the process ID of the current process is used. If | |
65 | .I pgid | |
66 | is zero, the process ID of the process specified by | |
67 | .I pid | |
e511ffb6 | 68 | is used. If \fBsetpgid\fP() is used to move a process from one process |
fea681da MK |
69 | group to another (as is done by some shells when creating pipelines), |
70 | both process groups must be part of the same session. In this case, | |
71 | the \fIpgid\fP specifies an existing process group to be joined and the | |
72 | session ID of that group must match the session ID of the joining process. | |
73 | ||
e511ffb6 | 74 | .BR getpgid () |
fea681da MK |
75 | returns the process group ID of the process specified by |
76 | .IR pid . | |
77 | If | |
78 | .I pid | |
79 | is zero, the process ID of the current process is used. | |
80 | ||
81 | The call | |
63aa9df0 | 82 | .BR setpgrp () |
fea681da MK |
83 | is equivalent to |
84 | .BR setpgid(0,0) . | |
85 | ||
86 | Similarly, | |
63aa9df0 | 87 | .BR getpgrp () |
fea681da MK |
88 | is equivalent to |
89 | .BR getpgid(0) . | |
90 | Each process group is a member of a session and each process is a | |
91 | member of the session of which its process group is a member. | |
92 | ||
93 | Process groups are used for distribution of signals, and by terminals to | |
94 | arbitrate requests for their input: Processes that have the same process | |
95 | group as the terminal are foreground and may read, while others will | |
96 | block with a signal if they attempt to read. | |
97 | These calls are thus used by programs such as | |
98 | .BR csh (1) | |
99 | to create process groups in implementing job control. The | |
100 | .B TIOCGPGRP | |
101 | and | |
102 | .B TIOCSPGRP | |
103 | calls described in | |
104 | .BR termios (3) | |
105 | are used to get/set the process group of the control terminal. | |
106 | ||
107 | If a session has a controlling terminal, CLOCAL is not set and a hangup | |
108 | occurs, then the session leader is sent a SIGHUP. If the session leader | |
109 | exits, the SIGHUP signal will be sent to each process in the foreground | |
110 | process group of the controlling terminal. | |
111 | ||
112 | If the exit of the process causes a process group to become orphaned, | |
113 | and if any member of the newly-orphaned process group is stopped, then a | |
114 | SIGHUP signal followed by a SIGCONT signal will be sent to each process | |
115 | in the newly-orphaned process group. | |
fea681da MK |
116 | .SH "RETURN VALUE" |
117 | On success, | |
ae050d9a MK |
118 | .BR setpgid () |
119 | and | |
120 | .BR setpgrp () | |
fea681da MK |
121 | return zero. On error, \-1 is returned, and |
122 | .I errno | |
123 | is set appropriately. | |
124 | ||
e511ffb6 | 125 | .BR getpgid () |
fea681da MK |
126 | returns a process group on success. |
127 | On error, \-1 is returned, and | |
128 | .I errno | |
129 | is set appropriately. | |
130 | ||
e511ffb6 | 131 | .BR getpgrp () |
fea681da MK |
132 | always returns the current process group. |
133 | .SH ERRORS | |
134 | .TP | |
135 | .B EACCES | |
136 | An attempt was made to change the process group ID | |
137 | of one of the children of the calling process and the child had | |
3382bd94 MK |
138 | already performed an \fBexecve\fP() |
139 | (\fBsetpgid\fP(), \fBsetpgrp\fP()). | |
fea681da MK |
140 | .TP |
141 | .B EINVAL | |
142 | .I pgid | |
143 | is less than 0 | |
3382bd94 | 144 | (\fBsetpgid\fP(), \fBsetpgrp\fP()). |
fea681da MK |
145 | .TP |
146 | .B EPERM | |
147 | An attempt was made to move a process into a process group in a | |
148 | different session, or to change the process | |
149 | group ID of one of the children of the calling process and the | |
150 | child was in a different session, or to change the process group ID of | |
151 | a session leader | |
3382bd94 | 152 | (\fBsetpgid\fP(), \fBsetpgrp\fP()). |
fea681da MK |
153 | .TP |
154 | .B ESRCH | |
155 | For | |
e511ffb6 | 156 | .BR getpgid (): |
fea681da MK |
157 | .I pid |
158 | does not match any process. | |
159 | For | |
e511ffb6 | 160 | .BR setpgid (): |
fea681da MK |
161 | .I pid |
162 | is not the current process and not a child of the current process. | |
163 | .SH "CONFORMING TO" | |
164 | The functions | |
e511ffb6 | 165 | .BR setpgid () |
fea681da | 166 | and |
e511ffb6 | 167 | .BR getpgrp () |
97c1eac8 | 168 | conform to POSIX.1-2001. |
fea681da | 169 | The function |
e511ffb6 | 170 | .BR setpgrp () |
b14d4aa5 | 171 | is from 4.2BSD. |
fea681da | 172 | The function |
e511ffb6 | 173 | .BR getpgid () |
fea681da MK |
174 | conforms to SVr4. |
175 | .SH NOTES | |
73ac0666 MK |
176 | A child created via |
177 | .BR fork (2) | |
178 | inherits its parent's process group ID. | |
179 | The process group ID is preserved across an | |
180 | .BR execve (2). | |
181 | ||
fea681da | 182 | POSIX took |
e511ffb6 | 183 | .BR setpgid () |
fea681da | 184 | from the BSD function |
e511ffb6 | 185 | .BR setpgrp (). |
aa651b39 | 186 | Also System V has a function with the same name, but it is identical to |
fea681da MK |
187 | .BR setsid (2). |
188 | .LP | |
189 | To get the prototypes under glibc, define both _XOPEN_SOURCE and | |
190 | _XOPEN_SOURCE_EXTENDED, or use "#define _XOPEN_SOURCE \fIn\fP" | |
191 | for some integer \fIn\fP larger than or equal to 500. | |
192 | .SH "SEE ALSO" | |
193 | .BR getuid (2), | |
194 | .BR setsid (2), | |
195 | .BR tcgetpgrp (3), | |
196 | .BR tcsetpgrp (3), | |
50e5322c | 197 | .BR termios (3), |
a8e7c990 | 198 | .BR feature_test_macros (7) |