Debian Codegraph @

upstream/debian-unstable/man3/sd_pidfd_get_inode_id.3

raw
1 '\" t
2 .TH "SD_PIDFD_GET_INODE_ID" "3" "" "systemd 261~rc3" "sd_pidfd_get_inode_id"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd_pidfd_get_inode_id \- Acquire the 64\-bit inode ID of a PID file descriptor (PIDFD)
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-daemon\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_pidfd_get_inode_id('u
32 .BI "int sd_pidfd_get_inode_id(int\ " "pidfd" ", uint64_t\ *" "ret" ");"
33 .SH "DESCRIPTION"
34 .PP
35 \fBsd_pidfd_get_inode_id()\fR
36 may be invoked to acquire the 64\-bit inode ID of a PID file descriptor (PIDFD), which can be used to reliably identify a process for the current boot\&.
37 .PP
38 As a typical example, the service manager sets
39 \fI$MAINPIDFDID\fR
40 and
41 \fI$MANAGERPIDFDID\fR
42 environment variables to the inode IDs of the service main process and the service manager itself, respectively, if such functionality is supported by the kernel\&.
43 .PP
44 On 64\-bit architectures, the inode ID can be directly obtained via a call to
45 \fBfstat\fR(2)
46 on a given pidfd\&. However, on 32\-bit architectures
47 struct stat\*(Aqs \&.st_ino field is also 32\-bit, which similar to PIDs is subject to reuse\&. Therefore, a second mechanism leveraging
48 \fBname_to_handle_at\fR(2)
49 has been added to kernel in v6\&.14\&. This helper is added to simplify downstream handling of pidfd/pidfs internals\&.
50 .SH "RETURN VALUE"
51 .PP
52 On success, the function returns 0 or a positive integer\&. On failure, a negative errno\-style error code is returned\&.
53 .SS "Errors"
54 .PP
55 Returned errors may indicate the following problems:
56 .PP
57 \fB\-EOPNOTSUPP\fR
58 .RS 4
59 The stable PIDFD inode ID is not supported by the running kernel, or the system is 32\-bit and
60 \fBname_to_handle_at()\fR
61 is unavailable\&.
62 .RE
63 .PP
64 \fB\-EBADF\fR
65 .RS 4
66 The specified file descriptor is invalid, or is not a PIDFD\&.
67 .RE
68 .SH "NOTES"
69 .PP
70 Functions described here are available as a shared library, which can be compiled against and linked to with the
71 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
72 file\&.
73 .SH "HISTORY"
74 .PP
75 \fBsd_pidfd_get_inode_id()\fR
76 was added in version 258\&.
77 .SH "SEE ALSO"
78 .PP
79 \fBsystemd\fR(1), \fBsd-daemon\fR(3), \fBsd_notify\fR(3), \fBsystemd.exec\fR(5)