]> git.ipfire.org Git - thirdparty/man-pages.git/blobdiff - man2/setsid.2
fuse.4: ffix
[thirdparty/man-pages.git] / man2 / setsid.2
index 0a98b4d446caf9455851e9d3f4d42cf3e1b2fc25..d2f4cc3b2b1331385b1062647fa9d2421dfcdfab 100644 (file)
@@ -1,5 +1,8 @@
-.\" 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" "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
@@ -39,48 +44,74 @@ setsid \- creates a session and sets the process group ID
 .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
-.BR 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 credentials (7)
+.BR credentials (7),
+.BR sched (7)