summaryrefslogtreecommitdiffstats
path: root/man2/setpgid.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/setpgid.2')
-rw-r--r--man2/setpgid.2329
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)