mirror of https://github.com/mkerrisk/man-pages
301 lines
8.5 KiB
Groff
301 lines
8.5 KiB
Groff
.\" Copyright (c) 1983, 1991 Regents of the University of California.
|
|
.\" and Copyright (C) 2007, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the University of
|
|
.\" California, Berkeley and its contributors.
|
|
.\" 4. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)getpgrp.2 6.4 (Berkeley) 3/10/91
|
|
.\"
|
|
.\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
|
|
.\" Modified 1995-04-15 by Michael Chastain <mec@shell.portal.com>:
|
|
.\" Added 'getpgid'.
|
|
.\" Modified 1996-07-21 by Andries Brouwer <aeb@cwi.nl>
|
|
.\" Modified 1996-11-06 by Eric S. Raymond <esr@thyrsus.com>
|
|
.\" Modified 1999-09-02 by Michael Haardt <michael@moria.de>
|
|
.\" Modified 2002-01-18 by Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\" Modified 2003-01-20 by Andries Brouwer <aeb@cwi.nl>
|
|
.\" 2007-07-25, mtk, fairly substantial rewrites and rearrangements
|
|
.\" of text.
|
|
.\"
|
|
.TH SETPGID 2 2007-07-26 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
setpgid, getpgid, setpgrp, getpgrp \- set/get process group
|
|
.SH SYNOPSIS
|
|
.B #include <unistd.h>
|
|
.sp
|
|
.BI "int setpgid(pid_t " pid ", pid_t " pgid );
|
|
.br
|
|
.BI "pid_t getpgid(pid_t " pid );
|
|
.sp
|
|
.BR "pid_t getpgrp(void);" " /* POSIX.1 version */"
|
|
.br
|
|
.BI "pid_t getpgrp(psid_t " pid ");\ \ \ \ \ \ \ \ \ "
|
|
/* BSD version */
|
|
.sp
|
|
.BR "int setpgrp(void);" " /* System V version */"
|
|
.br
|
|
.BI "int setpgrp(pid_t " pid ", pid_t " pgid );
|
|
/* BSD version */
|
|
.sp
|
|
.in -4n
|
|
Feature Test Macro Requirements for glibc (see
|
|
.BR feature_test_macros (7)):
|
|
.in
|
|
.sp
|
|
.ad l
|
|
.BR getpgid ():
|
|
_XOPEN_SOURCE\ >=\ 500
|
|
.br
|
|
.BR setpgrp ()
|
|
(POSIX.1): _SVID_SOURCE || _XOPEN_SOURCE >= 500
|
|
.sp
|
|
.BR setpgrp "()\ (BSD),"
|
|
.BR getpgrp "()\ (BSD):"
|
|
_BSD_SOURCE && !\ (_POSIX_SOURCE || _POSIX_C_SOURCE ||
|
|
_XOPEN_SOURCE || _XOPEN_SOURCE_EXTENDED || _GNU_SOURCE || _SVID_SOURCE)
|
|
.ad b
|
|
.SH DESCRIPTION
|
|
All of these interfaces are available on Linux,
|
|
and are used for getting and setting the
|
|
process group ID (PGID) of a process.
|
|
The preferred, POSIX.1-specified ways of doing this are:
|
|
.BR getpgrp (void),
|
|
for retrieving the calling process's PGID; and
|
|
.BR setpgid (),
|
|
for setting a process's PGID.
|
|
|
|
.BR setpgid ()
|
|
sets the PGID of the process specified by
|
|
.I pid
|
|
to
|
|
.IR pgid .
|
|
If
|
|
.I pid
|
|
is zero, the process ID of the calling process is used.
|
|
If
|
|
.I pgid
|
|
is zero, the process ID of the process specified by
|
|
.I pid
|
|
is used.
|
|
If
|
|
.BR setpgid ()
|
|
is used to move a process from one process
|
|
group to another (as is done by some shells when creating pipelines),
|
|
both process groups must be part of the same session (see
|
|
.BR setsid (2)
|
|
and
|
|
.BR credentials (7)).
|
|
In this case,
|
|
the \fIpgid\fP specifies an existing process group to be joined and the
|
|
session ID of that group must match the session ID of the joining process.
|
|
|
|
The POSIX.1 version of
|
|
.BR getpgrp (),
|
|
which takes no arguments,
|
|
returns the PGID of the calling process.
|
|
|
|
.BR getpgid ()
|
|
returns the PGID of the process specified by
|
|
.IR pid .
|
|
If
|
|
.I pid
|
|
is zero, the process ID of the calling process is used.
|
|
(Retrieving the PGID of a process other than the caller is rarely
|
|
necessary, and the POSIX.1
|
|
.BR getpgrp ()
|
|
is preferred for that task.)
|
|
|
|
The System V-style
|
|
.BR setpgrp (),
|
|
which takes no arguments, is equivalent to
|
|
.IR "setpgid(0,\ 0)" .
|
|
|
|
The BSD-specific
|
|
.BR setpgrp ()
|
|
call, which takes arguments
|
|
.I pid
|
|
and
|
|
.IR pgid ,
|
|
is equivalent to
|
|
.IR "setpgid(pid, pgid)" .
|
|
.\" The true BSD setpgrp() system call differs in allowing the PGID
|
|
.\" to be set to arbitrary values, rather than being restricted to
|
|
.\" PGIDs in the same session.
|
|
|
|
The BSD-specific
|
|
.BR getpgrp ()
|
|
call, which takes a single
|
|
.I pid
|
|
argument, is equivalent to
|
|
.IR "getpgid(pid)" .
|
|
.SH "RETURN VALUE"
|
|
On success,
|
|
.BR setpgid ()
|
|
and
|
|
.BR setpgrp ()
|
|
return zero.
|
|
On error, \-1 is returned, and
|
|
.I errno
|
|
is set appropriately.
|
|
|
|
The POSIX.1
|
|
.BR getpgrp ()
|
|
always returns the PGID of the caller.
|
|
|
|
.BR getpgid (),
|
|
and the BSD-specific
|
|
.BR getpgrp ()
|
|
return a process group on success.
|
|
On error, \-1 is returned, and
|
|
.I errno
|
|
is set appropriately.
|
|
.SH ERRORS
|
|
.TP
|
|
.B EACCES
|
|
An attempt was made to change the process group ID
|
|
of one of the children of the calling process and the child had
|
|
already performed an
|
|
.BR execve (2)
|
|
.RB ( setpgid (),
|
|
.BR setpgrp ()).
|
|
.TP
|
|
.B EINVAL
|
|
.I pgid
|
|
is less than 0
|
|
.RB ( setpgid (),
|
|
.BR setpgrp ()).
|
|
.TP
|
|
.B EPERM
|
|
An attempt was made to move a process into a process group in a
|
|
different session, or to change the process
|
|
group ID of one of the children of the calling process and the
|
|
child was in a different session, or to change the process group ID of
|
|
a session leader
|
|
.RB ( setpgid (),
|
|
.BR setpgrp ()).
|
|
.TP
|
|
.B ESRCH
|
|
For
|
|
.BR getpgid ():
|
|
.I pid
|
|
does not match any process.
|
|
For
|
|
.BR setpgid ():
|
|
.I pid
|
|
is not the calling process and not a child of the calling process.
|
|
.SH "CONFORMING TO"
|
|
.BR setpgid ()
|
|
and the version of
|
|
.BR getpgrp ()
|
|
with no arguments
|
|
conform to POSIX.1-2001.
|
|
|
|
POSIX.1-2001 also specifies
|
|
.BR getpgid ()
|
|
and the version of
|
|
.BR setpgrp ()
|
|
that takes no arguments.
|
|
.\" FIXME . Mar 08: The next POSIX.1 revisions marks setpgrp() obsolete.
|
|
|
|
The version of
|
|
.BR getpgrp ()
|
|
with one argument and the version of
|
|
.BR setpgrp ()
|
|
that takes two arguments derive from 4.2BSD,
|
|
and are not specified by POSIX.1.
|
|
.SH NOTES
|
|
A child created via
|
|
.BR fork (2)
|
|
inherits its parent's process group ID.
|
|
The PGID is preserved across an
|
|
.BR execve (2).
|
|
|
|
Each process group is a member of a session and each process is a
|
|
member of the session of which its process group is a member.
|
|
|
|
A session can have a controlling terminal.
|
|
At any time, one (and only one) of the process groups
|
|
in the session can be the foreground process group
|
|
for the terminal;
|
|
the remaining process groups are in the background.
|
|
If a signal is generated from the terminal (e.g., typing the
|
|
interrupt key to generate
|
|
.BR SIGINT ),
|
|
that signal is sent to the foreground process group.
|
|
(See
|
|
.BR termios (3)
|
|
for a description of the characters that generate signals.)
|
|
Only the foreground process group may
|
|
.BR read (2)
|
|
from the terminal;
|
|
if a background process group tries to
|
|
.BR read (2)
|
|
from the terminal, then the group is send a
|
|
.B SIGTSTP
|
|
signal, which suspends it.
|
|
The
|
|
.BR tcgetpgrp (3)
|
|
and
|
|
.BR tcsetpgrp (3)
|
|
functions are used to get/set the foreground
|
|
process group of the controlling terminal.
|
|
|
|
The
|
|
.BR setpgid ()
|
|
and
|
|
.BR getpgrp ()
|
|
calls are used by programs such as
|
|
.BR bash (1)
|
|
to create process groups in order to implement shell job control.
|
|
|
|
If a session has a controlling terminal, and the
|
|
.B CLOCAL
|
|
flag for that terminal is not set,
|
|
and a terminal hangup occurs, then the session leader is sent a
|
|
.BR SIGHUP .
|
|
If the session leader exits, then a
|
|
.B SIGHUP
|
|
signal will also be sent to each process in the foreground
|
|
process group of the controlling terminal.
|
|
|
|
If the exit of the process causes a process group to become orphaned,
|
|
and if any member of the newly orphaned process group is stopped, then a
|
|
.B SIGHUP
|
|
signal followed by a
|
|
.B SIGCONT
|
|
signal will be sent to each process
|
|
in the newly orphaned process group.
|
|
.SH "SEE ALSO"
|
|
.BR getuid (2),
|
|
.BR setsid (2),
|
|
.BR tcgetpgrp (3),
|
|
.BR tcsetpgrp (3),
|
|
.BR termios (3),
|
|
.BR credentials (7)
|