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