man2/setpgid.2

   1 .\" Copyright (c) 1983, 1991 Regents of the University of California.
   2 .\" and Copyright (C) 2007, Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\" All rights reserved.
   4 .\"
   5 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\" %%%LICENSE_END
  34 .\"
  35 .\"     @(#)getpgrp.2   6.4 (Berkeley) 3/10/91
  36 .\"
  37 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
  38 .\" Modified 1995-04-15 by Michael Chastain <mec@shell.portal.com>:
  39 .\"   Added 'getpgid'.
  40 .\" Modified 1996-07-21 by Andries Brouwer <aeb@cwi.nl>
  41 .\" Modified 1996-11-06 by Eric S. Raymond <esr@thyrsus.com>
  42 .\" Modified 1999-09-02 by Michael Haardt <michael@moria.de>
  43 .\" Modified 2002-01-18 by Michael Kerrisk <mtk.manpages@gmail.com>
  44 .\" Modified 2003-01-20 by Andries Brouwer <aeb@cwi.nl>
  45 .\" 2007-07-25, mtk, fairly substantial rewrites and rearrangements
  46 .\" of text.
  47 .\"
  48 .TH SETPGID 2 2014-01-07 "Linux" "Linux Programmer's Manual"
  49 .SH NAME
  50 setpgid, getpgid, setpgrp, getpgrp \- set/get process group
  51 .SH SYNOPSIS
  52 .B #include <unistd.h>
  53 .sp
  54 .BI "int setpgid(pid_t " pid ", pid_t " pgid );
  55 .br
  56 .BI "pid_t getpgid(pid_t " pid );
  57 .sp
  58 .BR "pid_t getpgrp(void);" "                 /* POSIX.1 version */"
  59 .br
  60 .BI "pid_t getpgrp(pid_t " pid ");\ \ \ \ \ \ \ \ \ \ \ "
  61 /* BSD version */
  62 .sp
  63 .BR "int setpgrp(void);" "                   /* System V version */"
  64 .br
  65 .BI "int setpgrp(pid_t " pid ", pid_t " pgid ");\ "
  66 /* BSD version */
  67 .sp
  68 .in -4n
  69 Feature Test Macro Requirements for glibc (see
  70 .BR feature_test_macros (7)):
  71 .in
  72 .sp
  73 .ad l
  74 .PD 0
  75 .BR getpgid ():
  76 .RS 4
  77 _XOPEN_SOURCE\ >=\ 500
  78 .\"    || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  79 .br
  80     || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L
  81 .RE
  82 .sp
  83 .BR setpgrp "() (POSIX.1):"
  84 .nf
  85     _XOPEN_SOURCE\ >=\ 500
  86 .\"    || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  87         || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  88         || /* Glibc versions <= 2.19: */ _SVID_SOURCE
  89 .fi
  90 .sp
  91 .BR setpgrp "()\ (BSD),"
  92 .BR getpgrp "()\ (BSD):"
  93 .nf
  94     [These are available only before glibc 2.19]
  95     _BSD_SOURCE &&
  96         !\ (_POSIX_SOURCE || _POSIX_C_SOURCE || _XOPEN_SOURCE ||
  97             _GNU_SOURCE || _SVID_SOURCE)
  98 .fi
  99 .PD
 100 .ad
 101 .SH DESCRIPTION
 102 All of these interfaces are available on Linux,
 103 and are used for getting and setting the
 104 process group ID (PGID) of a process.
 105 The preferred, POSIX.1-specified ways of doing this are:
 106 .BR getpgrp (void),
 107 for retrieving the calling process's PGID; and
 108 .BR setpgid (),
 109 for setting a process's PGID.
 110
 111 .BR setpgid ()
 112 sets the PGID of the process specified by
 113 .I pid
 114 to
 115 .IR pgid .
 116 If
 117 .I pid
 118 is zero, then the process ID of the calling process is used.
 119 If
 120 .I pgid
 121 is zero, then the PGID of the process specified by
 122 .I pid
 123 is made the same as its process ID.
 124 If
 125 .BR setpgid ()
 126 is used to move a process from one process
 127 group to another (as is done by some shells when creating pipelines),
 128 both process groups must be part of the same session (see
 129 .BR setsid (2)
 130 and
 131 .BR credentials (7)).
 132 In this case,
 133 the \fIpgid\fP specifies an existing process group to be joined and the
 134 session ID of that group must match the session ID of the joining process.
 135
 136 The POSIX.1 version of
 137 .BR getpgrp (),
 138 which takes no arguments,
 139 returns the PGID of the calling process.
 140
 141 .BR getpgid ()
 142 returns the PGID of the process specified by
 143 .IR pid .
 144 If
 145 .I pid
 146 is zero, the process ID of the calling process is used.
 147 (Retrieving the PGID of a process other than the caller is rarely
 148 necessary, and the POSIX.1
 149 .BR getpgrp ()
 150 is preferred for that task.)
 151
 152 The System\ V-style
 153 .BR setpgrp (),
 154 which takes no arguments, is equivalent to
 155 .IR "setpgid(0,\ 0)" .
 156
 157 The BSD-specific
 158 .BR setpgrp ()
 159 call, which takes arguments
 160 .I pid
 161 and
 162 .IR pgid ,
 163 is a wrapper function that calls
 164
 165     setpgid(pid, pgid)
 166
 167 .\" The true BSD setpgrp() system call differs in allowing the PGID
 168 .\" to be set to arbitrary values, rather than being restricted to
 169 .\" PGIDs in the same session.
 170 Since glibc 2.19, the BSD-specific
 171 .BR setpgrp ()
 172 function is no longer exposed by
 173 .IR <unistd.h> ;
 174 calls should be replaced with the
 175 .BR setpgid ()
 176 call shown above.
 177
 178 The BSD-specific
 179 .BR getpgrp ()
 180 call, which takes a single
 181 .I pid
 182 argument, is a wrapper function that calls
 183
 184     getpgid(pid)
 185
 186 Since glibc 2.19, the BSD-specific
 187 .BR getpgrp ()
 188 function is no longer exposed by
 189 .IR <unistd.h> ;
 190 calls should be replaced with calls to the POSIX.1
 191 .BR getpgrp ()
 192 which takes no arguments (if the intent is to obtain the caller's PGID),
 193 or with the
 194 .BR getpgid ()
 195 call shown above.
 196 .SH RETURN VALUE
 197 On success,
 198 .BR setpgid ()
 199 and
 200 .BR setpgrp ()
 201 return zero.
 202 On error, \-1 is returned, and
 203 .I errno
 204 is set appropriately.
 205
 206 The POSIX.1
 207 .BR getpgrp ()
 208 always returns the PGID of the caller.
 209
 210 .BR getpgid (),
 211 and the BSD-specific
 212 .BR getpgrp ()
 213 return a process group on success.
 214 On error, \-1 is returned, and
 215 .I errno
 216 is set appropriately.
 217 .SH ERRORS
 218 .TP
 219 .B EACCES
 220 An attempt was made to change the process group ID
 221 of one of the children of the calling process and the child had
 222 already performed an
 223 .BR execve (2)
 224 .RB ( setpgid (),
 225 .BR setpgrp ()).
 226 .TP
 227 .B EINVAL
 228 .I pgid
 229 is less than 0
 230 .RB ( setpgid (),
 231 .BR setpgrp ()).
 232 .TP
 233 .B EPERM
 234 An attempt was made to move a process into a process group in a
 235 different session, or to change the process
 236 group ID of one of the children of the calling process and the
 237 child was in a different session, or to change the process group ID of
 238 a session leader
 239 .RB ( setpgid (),
 240 .BR setpgrp ()).
 241 .TP
 242 .B ESRCH
 243 For
 244 .BR getpgid ():
 245 .I pid
 246 does not match any process.
 247 For
 248 .BR setpgid ():
 249 .I pid
 250 is not the calling process and not a child of the calling process.
 251 .SH CONFORMING TO
 252 .BR setpgid ()
 253 and the version of
 254 .BR getpgrp ()
 255 with no arguments
 256 conform to POSIX.1-2001.
 257
 258 POSIX.1-2001 also specifies
 259 .BR getpgid ()
 260 and the version of
 261 .BR setpgrp ()
 262 that takes no arguments.
 263 (POSIX.1-2008 marks this
 264 .BR setpgrp ()
 265 specification as obsolete.)
 266
 267 The version of
 268 .BR getpgrp ()
 269 with one argument and the version of
 270 .BR setpgrp ()
 271 that takes two arguments derive from 4.2BSD,
 272 and are not specified by POSIX.1.
 273 .SH NOTES
 274 A child created via
 275 .BR fork (2)
 276 inherits its parent's process group ID.
 277 The PGID is preserved across an
 278 .BR execve (2).
 279
 280 Each process group is a member of a session and each process is a
 281 member of the session of which its process group is a member.
 282
 283 A session can have a controlling terminal.
 284 At any time, one (and only one) of the process groups
 285 in the session can be the foreground process group
 286 for the terminal;
 287 the remaining process groups are in the background.
 288 If a signal is generated from the terminal (e.g., typing the
 289 interrupt key to generate
 290 .BR SIGINT ),
 291 that signal is sent to the foreground process group.
 292 (See
 293 .BR termios (3)
 294 for a description of the characters that generate signals.)
 295 Only the foreground process group may
 296 .BR read (2)
 297 from the terminal;
 298 if a background process group tries to
 299 .BR read (2)
 300 from the terminal, then the group is sent a
 301 .B SIGTTIN
 302 signal, which suspends it.
 303 The
 304 .BR tcgetpgrp (3)
 305 and
 306 .BR tcsetpgrp (3)
 307 functions are used to get/set the foreground
 308 process group of the controlling terminal.
 309
 310 The
 311 .BR setpgid ()
 312 and
 313 .BR getpgrp ()
 314 calls are used by programs such as
 315 .BR bash (1)
 316 to create process groups in order to implement shell job control.
 317
 318 If a session has a controlling terminal, and the
 319 .B CLOCAL
 320 flag for that terminal is not set,
 321 and a terminal hangup occurs, then the session leader is sent a
 322 .BR SIGHUP .
 323 If the session leader exits, then a
 324 .B SIGHUP
 325 signal will also be sent to each process in the foreground
 326 process group of the controlling terminal.
 327
 328 If the exit of the process causes a process group to become orphaned,
 329 and if any member of the newly orphaned process group is stopped, then a
 330 .B SIGHUP
 331 signal followed by a
 332 .B SIGCONT
 333 signal will be sent to each process
 334 in the newly orphaned process group.
 335 .\" exit.3 refers to the following text:
 336 An orphaned process group is one in which the parent of
 337 every member of process group is either itself also a member
 338 of the process group or is a member of a process group
 339 in a different session (see also
 340 .BR credentials (7)).
 341 .SH SEE ALSO
 342 .BR getuid (2),
 343 .BR setsid (2),
 344 .BR tcgetpgrp (3),
 345 .BR tcsetpgrp (3),
 346 .BR termios (3),
 347 .BR credentials (7)