]>
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. | |
116 | ||
117 | .SH "RETURN VALUE" | |
118 | On success, | |
ae050d9a MK |
119 | .BR setpgid () |
120 | and | |
121 | .BR setpgrp () | |
fea681da MK |
122 | return zero. On error, \-1 is returned, and |
123 | .I errno | |
124 | is set appropriately. | |
125 | ||
e511ffb6 | 126 | .BR getpgid () |
fea681da MK |
127 | returns a process group on success. |
128 | On error, \-1 is returned, and | |
129 | .I errno | |
130 | is set appropriately. | |
131 | ||
e511ffb6 | 132 | .BR getpgrp () |
fea681da MK |
133 | always returns the current process group. |
134 | .SH ERRORS | |
135 | .TP | |
136 | .B EACCES | |
137 | An attempt was made to change the process group ID | |
138 | of one of the children of the calling process and the child had | |
3382bd94 MK |
139 | already performed an \fBexecve\fP() |
140 | (\fBsetpgid\fP(), \fBsetpgrp\fP()). | |
fea681da MK |
141 | .TP |
142 | .B EINVAL | |
143 | .I pgid | |
144 | is less than 0 | |
3382bd94 | 145 | (\fBsetpgid\fP(), \fBsetpgrp\fP()). |
fea681da MK |
146 | .TP |
147 | .B EPERM | |
148 | An attempt was made to move a process into a process group in a | |
149 | different session, or to change the process | |
150 | group ID of one of the children of the calling process and the | |
151 | child was in a different session, or to change the process group ID of | |
152 | a session leader | |
3382bd94 | 153 | (\fBsetpgid\fP(), \fBsetpgrp\fP()). |
fea681da MK |
154 | .TP |
155 | .B ESRCH | |
156 | For | |
e511ffb6 | 157 | .BR getpgid (): |
fea681da MK |
158 | .I pid |
159 | does not match any process. | |
160 | For | |
e511ffb6 | 161 | .BR setpgid (): |
fea681da MK |
162 | .I pid |
163 | is not the current process and not a child of the current process. | |
164 | .SH "CONFORMING TO" | |
165 | The functions | |
e511ffb6 | 166 | .BR setpgid () |
fea681da | 167 | and |
e511ffb6 | 168 | .BR getpgrp () |
fea681da MK |
169 | conform to POSIX.1. |
170 | The function | |
e511ffb6 | 171 | .BR setpgrp () |
b14d4aa5 | 172 | is from 4.2BSD. |
fea681da | 173 | The function |
e511ffb6 | 174 | .BR getpgid () |
fea681da MK |
175 | conforms to SVr4. |
176 | .SH NOTES | |
177 | POSIX took | |
e511ffb6 | 178 | .BR setpgid () |
fea681da | 179 | from the BSD function |
e511ffb6 | 180 | .BR setpgrp (). |
aa651b39 | 181 | Also System V has a function with the same name, but it is identical to |
fea681da MK |
182 | .BR setsid (2). |
183 | .LP | |
184 | To get the prototypes under glibc, define both _XOPEN_SOURCE and | |
185 | _XOPEN_SOURCE_EXTENDED, or use "#define _XOPEN_SOURCE \fIn\fP" | |
186 | for some integer \fIn\fP larger than or equal to 500. | |
187 | .SH "SEE ALSO" | |
188 | .BR getuid (2), | |
189 | .BR setsid (2), | |
190 | .BR tcgetpgrp (3), | |
191 | .BR tcsetpgrp (3), | |
50e5322c | 192 | .BR termios (3), |
a8e7c990 | 193 | .BR feature_test_macros (7) |