]>
Commit | Line | Data |
---|---|---|
3d54a910 MK |
1 | .\" Copyright Michael Haardt (michael@cantor.informatik.rwth-aachen.de) |
2 | .\" Sat Aug 27 20:43:50 MET DST 1994 | |
d6c9f01b | 3 | .\" and Copyright (C) 2014, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 4 | .\" |
e4a74ca8 | 5 | .\" SPDX-License-Identifier: GPL-2.0-or-later |
fea681da MK |
6 | .\" |
7 | .\" Modified Sun Sep 11 19:19:05 1994 <faith@cs.unc.edu> | |
8 | .\" Modified Mon Mar 25 10:19:00 1996 <aeb@cwi.nl> (merged a few | |
9 | .\" tiny changes from a man page by Charles Livingston). | |
10 | .\" Modified Sun Jul 21 14:45:46 1996 <aeb@cwi.nl> | |
11 | .\" | |
4c1c5274 | 12 | .TH setsid 2 (date) "Linux man-pages (unreleased)" |
fea681da MK |
13 | .SH NAME |
14 | setsid \- creates a session and sets the process group ID | |
162e339e AC |
15 | .SH LIBRARY |
16 | Standard C library | |
8fc3b2cf | 17 | .RI ( libc ", " \-lc ) |
fea681da | 18 | .SH SYNOPSIS |
c7db92b9 | 19 | .nf |
fea681da | 20 | .B #include <unistd.h> |
c6d039a3 | 21 | .P |
fea681da | 22 | .B pid_t setsid(void); |
c7db92b9 | 23 | .fi |
fea681da | 24 | .SH DESCRIPTION |
60a90ecd MK |
25 | .BR setsid () |
26 | creates a new session if the calling process is not a | |
c13182ef | 27 | process group leader. |
d6c9f01b | 28 | The calling process is the leader of the new session |
4621e4e7 | 29 | (i.e., its session ID is made the same as its process ID). |
d6c9f01b MK |
30 | The calling process also becomes |
31 | the process group leader of a new process group in the session | |
99336344 | 32 | (i.e., its process group ID is made the same as its process ID). |
c6d039a3 | 33 | .P |
c13182ef | 34 | The calling process will be the only process in |
d6c9f01b | 35 | the new process group and in the new session. |
c6d039a3 | 36 | .P |
1986f065 MK |
37 | Initially, the new session has no controlling terminal. |
38 | For details of how a session acquires a controlling terminal, see | |
39 | .BR credentials (7). | |
47297adb | 40 | .SH RETURN VALUE |
97fce6cd MK |
41 | On success, the (new) session ID of the calling process is returned. |
42 | On error, | |
43 | .I "(pid_t)\ \-1" | |
44 | is returned, and | |
cca657e2 | 45 | .I errno |
97fce6cd MK |
46 | is set to indicate the error. |
47 | .SH ERRORS | |
48 | .TP | |
84492c36 YK |
49 | .B EPERM |
50 | The process group ID of any process equals the PID of the calling process. | |
c13182ef | 51 | Thus, in particular, |
e511ffb6 | 52 | .BR setsid () |
fea681da | 53 | fails if the calling process is already a process group leader. |
3113c7f3 | 54 | .SH STANDARDS |
4131356c AC |
55 | POSIX.1-2008. |
56 | .SH HISTORY | |
57 | POSIX.1-2001, SVr4. | |
fea681da | 58 | .SH NOTES |
c13182ef | 59 | A child created via |
73ac0666 MK |
60 | .BR fork (2) |
61 | inherits its parent's session ID. | |
62 | The session ID is preserved across an | |
63 | .BR execve (2). | |
c6d039a3 | 64 | .P |
d6c9f01b MK |
65 | A process group leader is a process whose process group ID equals its PID. |
66 | Disallowing a process group leader from calling | |
12776337 | 67 | .BR setsid () |
d6c9f01b MK |
68 | prevents the possibility that a process group leader places itself |
69 | in a new session while other processes in the process group remain | |
70 | in the original session; | |
71 | such a scenario would break the strict | |
72 | two-level hierarchy of sessions and process groups. | |
c13182ef | 73 | In order to be sure that |
e511ffb6 | 74 | .BR setsid () |
33e22209 | 75 | will succeed, call |
0bfa087b | 76 | .BR fork (2) |
33e22209 | 77 | and have the parent |
0bfa087b | 78 | .BR _exit (2), |
33e22209 | 79 | while the child (which by definition can't be a process group leader) calls |
a5e0a0e4 | 80 | .BR setsid (). |
c6d039a3 | 81 | .P |
7903f95f MK |
82 | If a session has a controlling terminal, and the |
83 | .B CLOCAL | |
84 | flag for that terminal is not set, | |
85 | and a terminal hangup occurs, then the session leader is sent a | |
1ae6b2c7 | 86 | .B SIGHUP |
b40e567a | 87 | signal. |
c6d039a3 | 88 | .P |
b40e567a | 89 | If a process that is a session leader terminates, then a |
7903f95f | 90 | .B SIGHUP |
b40e567a | 91 | signal is sent to each process in the foreground |
7903f95f | 92 | process group of the controlling terminal. |
47297adb | 93 | .SH SEE ALSO |
4426468b | 94 | .BR setsid (1), |
78110b78 | 95 | .BR getsid (2), |
fea681da | 96 | .BR setpgid (2), |
93c57ed0 | 97 | .BR setpgrp (2), |
78110b78 | 98 | .BR tcgetsid (3), |
b5bde13c MK |
99 | .BR credentials (7), |
100 | .BR sched (7) |