-.\" Copyright Michael Haardt (michael@cantor.informatik.rwth-aachen.de) Sat Aug 27 20:43:50 MET DST 1994
+.\" 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>
.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
-.\" License along with this manual; if not, write to the Free
-.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
-.\" USA.
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
+.\" %%%LICENSE_END
.\"
.\" 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 1994-08-27 "Linux 1.0.0" "Linux Programmer's Manual"
+.TH SETSID 2 2017-09-15 "Linux" "Linux Programmer's Manual"
.SH NAME
setsid \- creates a session and sets the process group ID
.SH SYNOPSIS
.ad l
+.B #include <sys/types.h>
+.br
.B #include <unistd.h>
-.sp
+.PP
.B pid_t setsid(void);
.br
.ad b
.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, the process group leader of the new process group, and has no
-controlling tty.
-The process group ID and session ID of the calling
-process are set to the PID of the calling process.
+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
-this new process group and in this new session.
-.SH "RETURN VALUE"
-The session ID of the calling process.
-.SH ERRORS
-On error, \-1 is returned, and
+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.
-The only error which can happen is
-EPERM.
-It is returned when the process group ID of any process
-equals the PID of the calling process.
+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 "CONFORMING TO"
-SVr4, POSIX.1-2001.
+.SH CONFORMING TO
+POSIX.1-2001, POSIX.1-2008, 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).
-
-A process group leader is a process with process group ID equal
-to its PID.
+.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,
+will succeed, call
.BR fork (2)
-and
+and have the parent
.BR _exit (2),
-and have the child do
+while the child (which by definition can't be a process group leader) calls
.BR setsid ().
-.SH "SEE ALSO"
+.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
+.BR 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 tcgetsid (3),
+.BR credentials (7),
+.BR sched (7)