Debian Codegraph @

upstream/debian-unstable/man7/credentials.7

raw
1 .\" Copyright 2007, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH credentials 7 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 credentials \- process identifiers
9 .SH DESCRIPTION
10 .SS Process ID (PID)
11 Each process has a unique nonnegative integer identifier
12 that is assigned when the process is created using
13 .BR fork (2).
14 A process can obtain its PID using
15 .BR getpid (2).
16 A PID is represented using the type
17 .I pid_t
18 (defined in
19 .IR <sys/types.h> ).
20 .P
21 PIDs are used in a range of system calls to identify the process
22 affected by the call, for example:
23 .BR kill (2),
24 .BR ptrace (2),
25 .BR setpriority (2),
26 .\" .BR sched_rr_get_interval (2),
27 .\" .BR sched_getaffinity (2),
28 .\" .BR sched_setaffinity (2),
29 .\" .BR sched_getparam (2),
30 .\" .BR sched_setparam (2),
31 .\" .BR sched_setscheduler (2),
32 .\" .BR sched_getscheduler (2),
33 .BR setpgid (2),
34 .\" .BR getsid (2),
35 .BR setsid (2),
36 .BR sigqueue (3),
37 and
38 .BR waitpid (2).
39 .\" .BR waitid (2),
40 .\" .BR wait4 (2),
41 .P
42 A process's PID is preserved across an
43 .BR execve (2).
44 .SS Parent process ID (PPID)
45 A process's parent process ID identifies the process that created
46 this process using
47 .BR fork (2).
48 A process can obtain its PPID using
49 .BR getppid (2).
50 A PPID is represented using the type
51 .IR pid_t .
52 .P
53 A process's PPID is preserved across an
54 .BR execve (2).
55 .SS Process group ID and session ID
56 Each process has a session ID and a process group ID,
57 both represented using the type
58 .IR pid_t .
59 A process can obtain its session ID using
60 .BR getsid (2),
61 and its process group ID using
62 .BR getpgrp (2).
63 .P
64 A child created by
65 .BR fork (2)
66 inherits its parent's session ID and process group ID.
67 A process's session ID and process group ID are preserved across an
68 .BR execve (2).
69 .P
70 Sessions and process groups are abstractions devised to support shell
71 job control.
72 A process group (sometimes called a "job") is a collection of
73 processes that share the same process group ID;
74 the shell creates a new process group for the process(es) used
75 to execute single command or pipeline (e.g., the two processes
76 created to execute the command "ls\ |\ wc" are placed in the
77 same process group).
78 A process's group membership can be set using
79 .BR setpgid (2).
80 The process whose process ID is the same as its process group ID is the
81 .I process group leader
82 for that group.
83 .P
84 A session is a collection of processes that share the same session ID.
85 All of the members of a process group also have the same session ID
86 (i.e., all of the members of a process group always belong to the
87 same session, so that sessions and process groups form a strict
88 two-level hierarchy of processes.)
89 A new session is created when a process calls
90 .BR setsid (2),
91 which creates a new session whose session ID is the same
92 as the PID of the process that called
93 .BR setsid (2).
94 The creator of the session is called the
95 .IR session\~leader .
96 .P
97 All of the processes in a session share a
98 .IR "controlling terminal" .
99 The controlling terminal is established when the session leader
100 first opens a terminal (unless the
101 .B O_NOCTTY
102 flag is specified when calling
103 .BR open (2)).
104 A terminal may be the controlling terminal of at most one session.
105 .P
106 At most one of the jobs in a session may be the
107 .IR "foreground job" ;
108 other jobs in the session are
109 .IR "background jobs" .
110 Only the foreground job may read from the terminal;
111 when a process in the background attempts to read from the terminal,
112 its process group is sent a
113 .B SIGTTIN
114 signal, which suspends the job.
115 If the
116 .B TOSTOP
117 flag has been set for the terminal (see
118 .BR termios (3)),
119 then only the foreground job may write to the terminal;
120 writes from background jobs cause a
121 .B SIGTTOU
122 signal to be generated, which suspends the job.
123 When terminal keys that generate a signal (such as the
124 .I interrupt
125 key, normally control-C)
126 are pressed, the signal is sent to the processes in the foreground job.
127 .P
128 Various system calls and library functions
129 may operate on all members of a process group,
130 including
131 .BR kill (2),
132 .BR killpg (3),
133 .BR getpriority (2),
134 .BR setpriority (2),
135 .BR ioprio_get (2),
136 .BR ioprio_set (2),
137 .BR waitid (2),
138 and
139 .BR waitpid (2).
140 See also the discussion of the
141 .BR F_GETOWN ,
142 .BR F_GETOWN_EX ,
143 .BR F_SETOWN ,
144 and
145 .B F_SETOWN_EX
146 operations in
147 .BR fcntl (2).
148 .SS User and group identifiers
149 Each process has various associated user and group IDs.
150 These IDs are integers, respectively represented using the types
151 .I uid_t
152 and
153 .I gid_t
154 (defined in
155 .IR <sys/types.h> ).
156 .P
157 On Linux, each process has the following user and group identifiers:
158 .IP \[bu] 3
159 Real user ID and real group ID.
160 These IDs determine who owns the process.
161 A process can obtain its real user (group) ID using
162 .BR getuid (2)
163 .RB ( getgid (2)).
164 .IP \[bu]
165 Effective user ID and effective group ID.
166 These IDs are used by the kernel to determine the permissions
167 that the process will have when accessing shared resources such
168 as message queues, shared memory, and semaphores.
169 On most UNIX systems, these IDs also determine the
170 permissions when accessing files.
171 However, Linux uses the filesystem IDs described below
172 for this task.
173 A process can obtain its effective user (group) ID using
174 .BR geteuid (2)
175 .RB ( getegid (2)).
176 .IP \[bu]
177 Saved set-user-ID and saved set-group-ID.
178 These IDs are used in set-user-ID and set-group-ID programs to save
179 a copy of the corresponding effective IDs that were set when
180 the program was executed (see
181 .BR execve (2)).
182 A set-user-ID program can assume and drop privileges by
183 switching its effective user ID back and forth between the values
184 in its real user ID and saved set-user-ID.
185 This switching is done via calls to
186 .BR seteuid (2),
187 .BR setreuid (2),
188 or
189 .BR setresuid (2).
190 A set-group-ID program performs the analogous tasks using
191 .BR setegid (2),
192 .BR setregid (2),
193 or
194 .BR setresgid (2).
195 A process can obtain its saved set-user-ID (set-group-ID) using
196 .BR getresuid (2)
197 .RB ( getresgid (2)).
198 .IP \[bu]
199 Filesystem user ID and filesystem group ID (Linux-specific).
200 These IDs,
201 in conjunction with the supplementary group IDs described below,
202 are used to determine permissions for accessing files;
203 see
204 .BR path_resolution (7)
205 for details.
206 Whenever a process's effective user (group) ID is changed,
207 the kernel also automatically changes the filesystem user (group) ID
208 to the same value.
209 Consequently,
210 the filesystem IDs normally have
211 the same values as the corresponding effective ID,
212 and the semantics for file-permission checks
213 are thus the same on Linux as on other UNIX systems.
214 The filesystem IDs can be made to differ from the effective IDs
215 by calling
216 .BR setfsuid (2)
217 and
218 .BR setfsgid (2).
219 .IP \[bu]
220 Supplementary group IDs.
221 This is a set of additional group IDs that are used for permission
222 checks when accessing files and other shared resources.
223 Before Linux 2.6.4,
224 a process can be a member of up to 32 supplementary groups;
225 since Linux 2.6.4,
226 a process can be a member of up to 65536 supplementary groups.
227 The call
228 .I sysconf(_SC_NGROUPS_MAX)
229 can be used to determine the number of supplementary groups
230 of which a process may be a member.
231 .\" Since Linux 2.6.4, the limit is visible via the read-only file
232 .\" /proc/sys/kernel/ngroups_max.
233 .\" As at 2.6.22-rc2, this file is still read-only.
234 A process can obtain its set of supplementary group IDs using
235 .BR getgroups (2).
236 .P
237 A child process created by
238 .BR fork (2)
239 inherits copies of its parent's user and groups IDs.
240 During an
241 .BR execve (2),
242 a process's real user and group ID and supplementary
243 group IDs are preserved;
244 the effective and saved set IDs may be changed, as described in
245 .BR execve (2).
246 .P
247 Aside from the purposes noted above,
248 a process's user IDs are also employed in a number of other contexts:
249 .IP \[bu] 3
250 when determining the permissions for sending signals (see
251 .BR kill (2));
252 .IP \[bu]
253 when determining the permissions for setting
254 process-scheduling parameters (nice value, real time
255 scheduling policy and priority, CPU affinity, I/O priority) using
256 .BR setpriority (2),
257 .BR sched_setaffinity (2),
258 .BR sched_setscheduler (2),
259 .BR sched_setparam (2),
260 .BR sched_setattr (2),
261 and
262 .BR ioprio_set (2);
263 .IP \[bu]
264 when checking resource limits (see
265 .BR getrlimit (2));
266 .IP \[bu]
267 when checking the limit on the number of inotify instances
268 that the process may create (see
269 .BR inotify (7)).
270 .\"
271 .SS Modifying process user and group IDs
272 Subject to rules described in the relevant manual pages,
273 a process can use the following APIs to modify its user and group IDs:
274 .TP
275 .BR setuid (2)\~(\c
276 .BR setgid (2))
277 Modify the process's real (and possibly effective and saved-set)
278 user (group) IDs.
279 .TP
280 .BR seteuid (2)\~(\c
281 .BR setegid (2))
282 Modify the process's effective user (group) ID.
283 .TP
284 .BR setfsuid (2)\~(\c
285 .BR setfsgid (2))
286 Modify the process's filesystem user (group) ID.
287 .TP
288 .BR setreuid (2)\~(\c
289 .BR setregid (2))
290 Modify the process's real and effective (and possibly saved-set)
291 user (group) IDs.
292 .TP
293 .BR setresuid (2)\~(\c
294 .BR setresgid (2))
295 Modify the process's real, effective, and saved-set user (group) IDs.
296 .TP
297 .BR setgroups (2)
298 Modify the process's supplementary group list.
299 .P
300 Any changes to a process's effective user (group) ID
301 are automatically carried over to the process's
302 filesystem user (group) ID.
303 Changes to a process's effective user or group ID can also affect the
304 process "dumpable" attribute, as described in
305 .BR prctl (2).
306 .P
307 Changes to process user and group IDs can affect the capabilities
308 of the process, as described in
309 .BR capabilities (7).
310 .SH STANDARDS
311 Process IDs, parent process IDs, process group IDs, and session IDs
312 are specified in POSIX.1.
313 The real, effective, and saved set user and groups IDs,
314 and the supplementary group IDs, are specified in POSIX.1.
315 .P
316 The filesystem user and group IDs are a Linux extension.
317 .SH NOTES
318 Various fields in the
319 .IR /proc/ pid /status
320 file show the process credentials described above.
321 See
322 .BR proc (5)
323 for further information.
324 .P
325 The POSIX threads specification requires that
326 credentials are shared by all of the threads in a process.
327 However, at the kernel level, Linux maintains separate user and group
328 credentials for each thread.
329 The NPTL threading implementation does some work to ensure
330 that any change to user or group credentials
331 (e.g., calls to
332 .BR setuid (2),
333 .BR setresuid (2))
334 is carried through to all of the POSIX threads in a process.
335 See
336 .BR nptl (7)
337 for further details.
338 .SH SEE ALSO
339 .BR bash (1),
340 .BR csh (1),
341 .BR groups (1),
342 .BR id (1),
343 .BR newgrp (1),
344 .BR ps (1),
345 .BR runuser (1),
346 .BR setpriv (1),
347 .BR sg (1),
348 .BR su (1),
349 .BR access (2),
350 .BR execve (2),
351 .BR faccessat (2),
352 .BR fork (2),
353 .BR getgroups (2),
354 .BR getpgrp (2),
355 .BR getpid (2),
356 .BR getppid (2),
357 .BR getsid (2),
358 .BR kill (2),
359 .BR setegid (2),
360 .BR seteuid (2),
361 .BR setfsgid (2),
362 .BR setfsuid (2),
363 .BR setgid (2),
364 .BR setgroups (2),
365 .BR setpgid (2),
366 .BR setresgid (2),
367 .BR setresuid (2),
368 .BR setsid (2),
369 .BR setuid (2),
370 .BR waitpid (2),
371 .BR euidaccess (3),
372 .BR initgroups (3),
373 .BR killpg (3),
374 .BR tcgetpgrp (3),
375 .BR tcgetsid (3),
376 .BR tcsetpgrp (3),
377 .BR group (5),
378 .BR passwd (5),
379 .BR shadow (5),
380 .BR capabilities (7),
381 .BR namespaces (7),
382 .BR path_resolution (7),
383 .BR pid_namespaces (7),
384 .BR pthreads (7),
385 .BR signal (7),
386 .BR system_data_types (7),
387 .BR unix (7),
388 .BR user_namespaces (7),
389 .BR sudo (8)