| .\" Copyright (c) 1983, 1991 Regents of the University of California. |
| .\" and Copyright (C) 2007, Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" All rights reserved. |
| .\" |
| .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
| .\" 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. |
| .\" %%%LICENSE_END |
| .\" |
| .\" @(#)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 2017-09-15 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| setpgid, getpgid, setpgrp, getpgrp \- set/get process group |
| .SH SYNOPSIS |
| .B #include <sys/types.h> |
| .br |
| .B #include <unistd.h> |
| .PP |
| .BI "int setpgid(pid_t " pid ", pid_t " pgid ); |
| .br |
| .BI "pid_t getpgid(pid_t " pid ); |
| .PP |
| .BR "pid_t getpgrp(void);" " /* POSIX.1 version */" |
| .br |
| .BI "pid_t getpgrp(pid_t " pid ");\ \ \ \ \ \ \ \ \ \ \ " |
| /* BSD version */ |
| .PP |
| .BR "int setpgrp(void);" " /* System V version */" |
| .br |
| .BI "int setpgrp(pid_t " pid ", pid_t " pgid ");\ " |
| /* BSD version */ |
| .PP |
| .in -4n |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .in |
| .PP |
| .ad l |
| .BR getpgid (): |
| .RS 4 |
| _XOPEN_SOURCE\ >=\ 500 |
| .\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED |
| .br |
| || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L |
| .RE |
| .PP |
| .BR setpgrp "() (POSIX.1):" |
| .nf |
| _XOPEN_SOURCE\ >=\ 500 |
| .\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED |
| || /* Since glibc 2.19: */ _DEFAULT_SOURCE |
| || /* Glibc versions <= 2.19: */ _SVID_SOURCE |
| .fi |
| .PP |
| .BR setpgrp "()\ (BSD)," |
| .BR getpgrp "()\ (BSD):" |
| .nf |
| [These are available only before glibc 2.19] |
| _BSD_SOURCE && |
| !\ (_POSIX_SOURCE || _POSIX_C_SOURCE || _XOPEN_SOURCE || |
| _GNU_SOURCE || _SVID_SOURCE) |
| .fi |
| .ad |
| .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. |
| .PP |
| .BR setpgid () |
| sets the PGID of the process specified by |
| .I pid |
| to |
| .IR pgid . |
| If |
| .I pid |
| is zero, then the process ID of the calling process is used. |
| If |
| .I pgid |
| is zero, then the PGID of the process specified by |
| .I pid |
| is made the same as its process ID. |
| 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. |
| .PP |
| The POSIX.1 version of |
| .BR getpgrp (), |
| which takes no arguments, |
| returns the PGID of the calling process. |
| .PP |
| .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.) |
| .PP |
| The System\ V-style |
| .BR setpgrp (), |
| which takes no arguments, is equivalent to |
| .IR "setpgid(0,\ 0)" . |
| .PP |
| The BSD-specific |
| .BR setpgrp () |
| call, which takes arguments |
| .I pid |
| and |
| .IR pgid , |
| is a wrapper function that calls |
| .PP |
| setpgid(pid, pgid) |
| .PP |
| .\" 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. |
| Since glibc 2.19, the BSD-specific |
| .BR setpgrp () |
| function is no longer exposed by |
| .IR <unistd.h> ; |
| calls should be replaced with the |
| .BR setpgid () |
| call shown above. |
| .PP |
| The BSD-specific |
| .BR getpgrp () |
| call, which takes a single |
| .I pid |
| argument, is a wrapper function that calls |
| .PP |
| getpgid(pid) |
| .PP |
| Since glibc 2.19, the BSD-specific |
| .BR getpgrp () |
| function is no longer exposed by |
| .IR <unistd.h> ; |
| calls should be replaced with calls to the POSIX.1 |
| .BR getpgrp () |
| which takes no arguments (if the intent is to obtain the caller's PGID), |
| or with the |
| .BR getpgid () |
| call shown above. |
| .SH RETURN VALUE |
| On success, |
| .BR setpgid () |
| and |
| .BR setpgrp () |
| return zero. |
| On error, \-1 is returned, and |
| .I errno |
| is set appropriately. |
| .PP |
| The POSIX.1 |
| .BR getpgrp () |
| always returns the PGID of the caller. |
| .PP |
| .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. |
| .PP |
| POSIX.1-2001 also specifies |
| .BR getpgid () |
| and the version of |
| .BR setpgrp () |
| that takes no arguments. |
| (POSIX.1-2008 marks this |
| .BR setpgrp () |
| specification as obsolete.) |
| .PP |
| 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). |
| .PP |
| 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. |
| (See |
| .BR credentials (7).) |
| .PP |
| 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 sent a |
| .B SIGTTIN |
| 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. |
| .PP |
| 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. |
| .PP |
| If the termination of a 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. |
| .\" exit.3 refers to the following text: |
| An orphaned process group is one in which the parent of |
| every member of process group is either itself also a member |
| of the process group or is a member of a process group |
| in a different session (see also |
| .BR credentials (7)). |
| .SH SEE ALSO |
| .BR getuid (2), |
| .BR setsid (2), |
| .BR tcgetpgrp (3), |
| .BR tcsetpgrp (3), |
| .BR termios (3), |
| .BR credentials (7) |