Debian Codegraph @

upstream/debian-unstable/man2/setsid.2

raw
1 .\" Copyright 2014, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .\"
6 .TH setsid 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 setsid \- creates a session and sets the process group ID
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <unistd.h>
15 .P
16 .B pid_t setsid(void);
17 .fi
18 .SH DESCRIPTION
19 .BR setsid ()
20 creates a new session if the calling process is not a
21 process group leader.
22 The calling process is the leader of the new session
23 (i.e., its session ID is made the same as its process ID).
24 The calling process also becomes
25 the process group leader of a new process group in the session
26 (i.e., its process group ID is made the same as its process ID).
27 .P
28 The calling process will be the only process in
29 the new process group and in the new session.
30 .P
31 Initially, the new session has no controlling terminal.
32 For details of how a session acquires a controlling terminal, see
33 .BR credentials (7).
34 .SH RETURN VALUE
35 On success, the (new) session ID of the calling process is returned.
36 On error,
37 .I "(pid_t)\ \-1"
38 is returned, and
39 .I errno
40 is set to indicate the error.
41 .SH ERRORS
42 .TP
43 .B EPERM
44 The process group ID of any process equals the PID of the calling process.
45 Thus, in particular,
46 .BR setsid ()
47 fails if the calling process is already a process group leader.
48 .SH STANDARDS
49 POSIX.1-2024.
50 .SH HISTORY
51 POSIX.1-2001, SVr4.
52 .SH NOTES
53 A child created via
54 .BR fork (2)
55 inherits its parent's session ID.
56 The session ID is preserved across an
57 .BR execve (2).
58 .P
59 A process group leader is a process whose process group ID equals its PID.
60 Disallowing a process group leader from calling
61 .BR setsid ()
62 prevents the possibility that a process group leader places itself
63 in a new session while other processes in the process group remain
64 in the original session;
65 such a scenario would break the strict
66 two-level hierarchy of sessions and process groups.
67 In order to be sure that
68 .BR setsid ()
69 will succeed, call
70 .BR fork (2)
71 and have the parent
72 .BR _exit (2),
73 while the child (which by definition can't be a process group leader) calls
74 .BR setsid ().
75 .P
76 If a session has a controlling terminal, and the
77 .B CLOCAL
78 flag for that terminal is not set,
79 and a terminal hangup occurs, then the session leader is sent a
80 .B SIGHUP
81 signal.
82 .P
83 If a process that is a session leader terminates, then a
84 .B SIGHUP
85 signal is sent to each process in the foreground
86 process group of the controlling terminal.
87 .SH SEE ALSO
88 .BR setsid (1),
89 .BR getsid (2),
90 .BR setpgid (2),
91 .BR setpgrp (2),
92 .BR tcgetsid (3),
93 .BR credentials (7),
94 .BR sched (7)