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