man2/setpgid.2

   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>
  40 .\" Modified 2002-01-18 by Michael Kerrisk <mtk-manpages@gmx.net>
  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
  57 .BR setpgid ()
  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
  68 is used.  If \fBsetpgid\fP() is used to move a process from one process
  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
  74 .BR getpgid ()
  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
  82 .BR setpgrp ()
  83 is equivalent to
  84 .BR setpgid(0,0) .
  85
  86 Similarly,
  87 .BR getpgrp ()
  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,
 119 .BR setpgid ()
 120 and
 121 .BR setpgrp ()
 122 return zero.  On error, \-1 is returned, and
 123 .I errno
 124 is set appropriately.
 125
 126 .BR getpgid ()
 127 returns a process group on success.
 128 On error, \-1 is returned, and
 129 .I errno
 130 is set appropriately.
 131
 132 .BR getpgrp ()
 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
 139 already performed an \fBexecve\fP()
 140 (\fBsetpgid\fP(), \fBsetpgrp\fP()).
 141 .TP
 142 .B EINVAL
 143 .I pgid
 144 is less than 0
 145 (\fBsetpgid\fP(), \fBsetpgrp\fP()).
 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
 153 (\fBsetpgid\fP(), \fBsetpgrp\fP()).
 154 .TP
 155 .B ESRCH
 156 For
 157 .BR getpgid ():
 158 .I pid
 159 does not match any process.
 160 For
 161 .BR setpgid ():
 162 .I pid
 163 is not the current process and not a child of the current process.
 164 .SH "CONFORMING TO"
 165 The functions
 166 .BR setpgid ()
 167 and
 168 .BR getpgrp ()
 169 conform to POSIX.1.
 170 The function
 171 .BR setpgrp ()
 172 is from 4.2BSD.
 173 The function
 174 .BR getpgid ()
 175 conforms to SVr4.
 176 .SH NOTES
 177 POSIX took
 178 .BR setpgid ()
 179 from the BSD function
 180 .BR setpgrp ().
 181 Also System V has a function with the same name, but it is identical to
 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),
 192 .BR termios (3),
 193 .BR feature_test_macros (7)