diff options
Diffstat (limited to 'man2/setpgid.2')
| -rw-r--r-- | man2/setpgid.2 | 329 |
1 files changed, 329 insertions, 0 deletions
diff --git a/man2/setpgid.2 b/man2/setpgid.2 new file mode 100644 index 0000000..2d8bc96 --- /dev/null +++ b/man2/setpgid.2 @@ -0,0 +1,329 @@ +.\" Copyright (c) 1983, 1991 Regents of the University of California. +.\" and Copyright (C) 2007, Michael Kerrisk <mtk.manpages@gmail.com> +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)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 2023-03-30 "Linux man-pages 6.05.01" +.SH NAME +setpgid, getpgid, setpgrp, getpgrp \- set/get process group +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.PP +.BI "int setpgid(pid_t " pid ", pid_t " pgid ); +.BI "pid_t getpgid(pid_t " pid ); +.PP +.BR "pid_t getpgrp(void);" " /* POSIX.1 version */" +.BI "[[deprecated]] pid_t getpgrp(pid_t " pid ");\fR /* BSD version */" +.PP +.BR "int setpgrp(void);" " /* System V version */" +.BI "[[deprecated]] int setpgrp(pid_t " pid ", pid_t " pgid ");\fR /* BSD version */" +.fi +.PP +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.BR getpgid (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L +.fi +.PP +.BR setpgrp "() (POSIX.1):" +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 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 +.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 +.in +4n +.EX +setpgid(pid, pgid) +.EE +.in +.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 +.in +4n +.EX +getpgid(pid) +.EE +.in +.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 to indicate the error. +.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 to indicate the error. +.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 EPERM +The target process group does not exist. +.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 STANDARDS +.TP +.BR getpgid () +.TQ +.BR setpgid () +.TQ +.BR getpgrp "() (no args)" +.TQ +.BR setpgrp "() (no args)" +POSIX.1-2008 (but see HISTORY). +.TP +.BR setpgrp "() (2 args)" +.TQ +.BR getpgrp "() (1 arg)" +None. +.SH HISTORY +.TP +.BR getpgid () +.TQ +.BR setpgid () +.TQ +.BR getpgrp "() (no args)" +POSIX.1-2001. +.TP +.BR setpgrp "() (no args)" +POSIX.1-2001. +POSIX.1-2008 marks it as obsolete. +.TP +.BR setpgrp "() (2 args)" +.TQ +.BR getpgrp "() (1 arg)" +4.2BSD. +.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) |