summaryrefslogtreecommitdiffstats
path: root/man2/setsid.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/setsid.2')
-rw-r--r--man2/setsid.2100
1 files changed, 100 insertions, 0 deletions
diff --git a/man2/setsid.2 b/man2/setsid.2
new file mode 100644
index 0000000..ae04028
--- /dev/null
+++ b/man2/setsid.2
@@ -0,0 +1,100 @@
+.\" Copyright Michael Haardt (michael@cantor.informatik.rwth-aachen.de)
+.\" Sat Aug 27 20:43:50 MET DST 1994
+.\" and Copyright (C) 2014, Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.\" Modified Sun Sep 11 19:19:05 1994 <faith@cs.unc.edu>
+.\" Modified Mon Mar 25 10:19:00 1996 <aeb@cwi.nl> (merged a few
+.\" tiny changes from a man page by Charles Livingston).
+.\" Modified Sun Jul 21 14:45:46 1996 <aeb@cwi.nl>
+.\"
+.TH setsid 2 2023-03-30 "Linux man-pages 6.05.01"
+.SH NAME
+setsid \- creates a session and sets the process group ID
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <unistd.h>
+.PP
+.B pid_t setsid(void);
+.fi
+.SH DESCRIPTION
+.BR setsid ()
+creates a new session if the calling process is not a
+process group leader.
+The calling process is the leader of the new session
+(i.e., its session ID is made the same as its process ID).
+The calling process also becomes
+the process group leader of a new process group in the session
+(i.e., its process group ID is made the same as its process ID).
+.PP
+The calling process will be the only process in
+the new process group and in the new session.
+.PP
+Initially, the new session has no controlling terminal.
+For details of how a session acquires a controlling terminal, see
+.BR credentials (7).
+.SH RETURN VALUE
+On success, the (new) session ID of the calling process is returned.
+On error,
+.I "(pid_t)\ \-1"
+is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EPERM
+The process group ID of any process equals the PID of the calling process.
+Thus, in particular,
+.BR setsid ()
+fails if the calling process is already a process group leader.
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, SVr4.
+.SH NOTES
+A child created via
+.BR fork (2)
+inherits its parent's session ID.
+The session ID is preserved across an
+.BR execve (2).
+.PP
+A process group leader is a process whose process group ID equals its PID.
+Disallowing a process group leader from calling
+.BR setsid ()
+prevents the possibility that a process group leader places itself
+in a new session while other processes in the process group remain
+in the original session;
+such a scenario would break the strict
+two-level hierarchy of sessions and process groups.
+In order to be sure that
+.BR setsid ()
+will succeed, call
+.BR fork (2)
+and have the parent
+.BR _exit (2),
+while the child (which by definition can't be a process group leader) calls
+.BR setsid ().
+.PP
+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
+.B SIGHUP
+signal.
+.PP
+If a process that is a session leader terminates, then a
+.B SIGHUP
+signal is sent to each process in the foreground
+process group of the controlling terminal.
+.SH SEE ALSO
+.BR setsid (1),
+.BR getsid (2),
+.BR setpgid (2),
+.BR setpgrp (2),
+.BR tcgetsid (3),
+.BR credentials (7),
+.BR sched (7)