sd_pid_get_session.xml 9.39 KB
Newer Older
1 2 3 4 5 6 7 8 9 10
<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  This file is part of systemd.

  Copyright 2010 Lennart Poettering

  systemd is free software; you can redistribute it and/or modify it
11 12
  under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or
13 14 15 16 17
  (at your option) any later version.

  systemd is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18
  Lesser General Public License for more details.
19

20
  You should have received a copy of the GNU Lesser General Public License
21 22 23
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

24
<refentry id="sd_pid_get_session" conditional='HAVE_PAM'>
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46

        <refentryinfo>
                <title>sd_pid_get_session</title>
                <productname>systemd</productname>

                <authorgroup>
                        <author>
                                <contrib>Developer</contrib>
                                <firstname>Lennart</firstname>
                                <surname>Poettering</surname>
                                <email>lennart@poettering.net</email>
                        </author>
                </authorgroup>
        </refentryinfo>

        <refmeta>
                <refentrytitle>sd_pid_get_session</refentrytitle>
                <manvolnum>3</manvolnum>
        </refmeta>

        <refnamediv>
                <refname>sd_pid_get_session</refname>
47
                <refname>sd_pid_get_unit</refname>
48
                <refname>sd_pid_get_user_unit</refname>
49
                <refname>sd_pid_get_owner_uid</refname>
50 51
                <refname>sd_pid_get_machine_name</refname>
                <refpurpose>Determine session, service, owner of a session or container/VM of a specific PID</refpurpose>
52 53 54 55 56 57 58 59 60 61 62 63
        </refnamediv>

        <refsynopsisdiv>
                <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>

                        <funcprototype>
                                <funcdef>int <function>sd_pid_get_session</function></funcdef>
                                <paramdef>pid_t <parameter>pid</parameter></paramdef>
                                <paramdef>char** <parameter>session</parameter></paramdef>
                        </funcprototype>

64
                        <funcprototype>
65
                                <funcdef>int <function>sd_pid_get_unit</function></funcdef>
66
                                <paramdef>pid_t <parameter>pid</parameter></paramdef>
67
                                <paramdef>char** <parameter>unit</parameter></paramdef>
68 69
                        </funcprototype>

70 71 72 73 74 75
                        <funcprototype>
                                <funcdef>int <function>sd_pid_get_user_unit</function></funcdef>
                                <paramdef>pid_t <parameter>pid</parameter></paramdef>
                                <paramdef>char** <parameter>unit</parameter></paramdef>
                        </funcprototype>

76 77 78 79 80
                        <funcprototype>
                                <funcdef>int <function>sd_pid_get_owner_uid</function></funcdef>
                                <paramdef>pid_t <parameter>pid</parameter></paramdef>
                                <paramdef>uid_t* <parameter>uid</parameter></paramdef>
                        </funcprototype>
81 82 83 84 85 86

                        <funcprototype>
                                <funcdef>int <function>sd_pid_get_machine_name</function></funcdef>
                                <paramdef>pid_t <parameter>pid</parameter></paramdef>
                                <paramdef>char** <parameter>name</parameter></paramdef>
                        </funcprototype>
87 88 89 90 91 92 93 94
                </funcsynopsis>
        </refsynopsisdiv>

        <refsect1>
                <title>Description</title>

                <para><function>sd_pid_get_session()</function> may be
                used to determine the login session identifier of a
Lennart Poettering's avatar
Lennart Poettering committed
95 96 97 98
                process identified by the specified process
                identifier. The session identifier is a short string,
                suitable for usage in file system paths. Note that not
                all processes are part of a login session (e.g. system
99 100 101 102 103 104 105 106
                service processes, user processes that are shared
                between multiple sessions of the same user, or kernel
                threads). For processes not being part of a login
                session this function will fail. The returned string
                needs to be freed with the libc
                <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                call after use.</para>

107
                <para><function>sd_pid_get_unit()</function> may be
108
                used to determine the systemd system unit (i.e. system
109
                service) identifier of a process identified by the
110 111 112
                specified PID. The unit name is a short string,
                suitable for usage in file system paths. Note that not
                all processes are part of a system unit/service
113
                (e.g. user processes, or kernel threads). For
114 115 116 117
                processes not being part of a systemd system unit this
                function will fail. (More specifically: this call will
                not work for processes that are part of user units,
                use <function>sd_pid_get_user_unit()</function> for
118
                that.) The returned string needs to be freed with the
119
                libc
120 121 122
                <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                call after use.</para>

123 124 125 126 127 128 129
                <para><function>sd_pid_get_user_unit()</function> may
                be used to determine the systemd user unit (i.e. user
                service) identifier of a process identified by the
                specified PID. This is similar to
                <function>sd_pid_get_unit()</function> but applies to
                user units instead of system units.</para>

130 131 132 133 134 135 136 137 138 139
                <para><function>sd_pid_get_owner_uid()</function> may
                be used to determine the Unix user identifier of the
                owner of the session of a process identified the
                specified PID. Note that this function will succeed
                for user processes which are shared between multiple
                login sessions of the same user, where
                <function>sd_pid_get_session()</function> will
                fail. For processes not being part of a login session
                and not being a shared process of a user this function
                will fail.</para>
140

141 142 143 144 145 146 147 148
                <para><function>sd_pid_machine_name()</function> may
                be used to determine the name of the VM or container
                is a member of. The machine name is a short string,
                suitable for usage in file system paths. The returned
                string needs to be freed with the libc
                <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                call after use.</para>

149
                <para>If the <literal>pid</literal> parameter of any
150 151
                of these functions is passed as 0 the operation is
                executed for the calling process.</para>
152 153 154 155 156 157 158 159 160 161 162 163 164
        </refsect1>

        <refsect1>
                <title>Return Value</title>

                <para>On success these calls return 0 or a positive
                integer. On failure, these calls return a negative
                errno-style error code.</para>
        </refsect1>

        <refsect1>
                <title>Notes</title>

165
                <para>The <function>sd_pid_get_session()</function>,
166
                <function>sd_pid_get_unit()</function>,
167 168 169 170 171
                <function>sd_pid_get_user_unit()</function>,
                <function>sd_pid_get_owner_uid()</function> and
                <function>sd_pid_get_machine_name()</function>
                interfaces are available as shared library, which can
                be compiled and linked to with the
172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187
                <literal>libsystemd-login</literal>
                <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                file.</para>

                <para>Note that the login session identifier as
                returned by <function>sd_pid_get_session()</function>
                is completely unrelated to the process session
                identifier as returned by
                <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para>
        </refsect1>

        <refsect1>
                <title>See Also</title>

                <para>
                        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
188
                        <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
189 190 191 192 193 194
                        <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
                </para>
        </refsect1>

</refentry>