1<?xml version='1.0'?> <!--*-nxml-*--> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 5 6<refentry id="sd_bus_query_sender_creds" xmlns:xi="http://www.w3.org/2001/XInclude"> 7 8 <refentryinfo> 9 <title>sd_bus_query_sender_creds</title> 10 <productname>systemd</productname> 11 </refentryinfo> 12 13 <refmeta> 14 <refentrytitle>sd_bus_query_sender_creds</refentrytitle> 15 <manvolnum>3</manvolnum> 16 </refmeta> 17 18 <refnamediv> 19 <refname>sd_bus_query_sender_creds</refname> 20 <refname>sd_bus_query_sender_privilege</refname> 21 22 <refpurpose>Query bus message sender credentials/privileges</refpurpose> 23 </refnamediv> 24 25 <refsynopsisdiv> 26 <funcsynopsis> 27 <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> 28 29 <funcprototype> 30 <funcdef>int <function>sd_bus_query_sender_creds</function></funcdef> 31 <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> 32 <paramdef>uint64_t <parameter>mask</parameter></paramdef> 33 <paramdef>sd_bus_creds **<parameter>creds</parameter></paramdef> 34 </funcprototype> 35 36 <funcprototype> 37 <funcdef>sd_bus_error* <function>sd_bus_query_sender_privilege</function></funcdef> 38 <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> 39 <paramdef>int <parameter>capability</parameter></paramdef> 40 </funcprototype> 41 </funcsynopsis> 42 </refsynopsisdiv> 43 44 <refsect1> 45 <title>Description</title> 46 47 <para><function>sd_bus_query_sender_creds()</function> returns the credentials of the message 48 <parameter>m</parameter>. The <parameter>mask</parameter> parameter is a combo of 49 <constant index='false'>SD_BUS_CREDS_*</constant> flags that indicate which credential info the caller is 50 interested in. See 51 <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry> 52 for a list of possible flags. First, this message checks if the requested credentials are attached to the 53 message itself. If not, but the message contains the pid of the sender and the caller specified the 54 <constant index='false'>SD_BUS_CREDS_AUGMENT</constant> flag, this function tries to figure out 55 the missing credentials via other means (starting from the pid). If the pid isn't available but the 56 message has a sender, this function calls 57 <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry> 58 to get the requested credentials. If the message has no sender (when a direct connection is used), this 59 function calls 60 <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry> 61 to get the requested credentials. On success, the requested credentials are stored in 62 <parameter>creds</parameter>. Ownership of the credentials object in <parameter>creds</parameter> is 63 transferred to the caller and should be freed by calling 64 <citerefentry><refentrytitle>sd_bus_creds_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>. 65 </para> 66 67 <para><function>sd_bus_query_sender_privilege()</function> checks if the message <parameter>m</parameter> 68 has the requested privileges. If <parameter>capability</parameter> is a non-negative integer, this 69 function checks if the message has the capability with the same value. See 70 <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> 71 for a list of capabilities. If <parameter>capability</parameter> is a negative integer, this function 72 returns whether the sender of the message runs as the same user as the receiver of the message, or if the 73 sender of the message runs as root and the receiver of the message does not run as root. On success and 74 if the message has the requested privileges, this function returns a positive integer. If the message 75 does not have the requested privileges, this function returns zero.</para> 76 </refsect1> 77 78 <refsect1> 79 <title>Return Value</title> 80 81 <para>On success, these functions return a non-negative integer. On failure, they return a negative 82 errno-style error code.</para> 83 84 <refsect2> 85 <title>Errors</title> 86 87 <para>Returned errors may indicate the following problems:</para> 88 89 <variablelist> 90 <varlistentry> 91 <term><constant>-EINVAL</constant></term> 92 93 <listitem><para>The message <parameter>m</parameter> or an output parameter is 94 <constant>NULL</constant>.</para></listitem> 95 </varlistentry> 96 97 <varlistentry> 98 <term><constant>-ENOTCONN</constant></term> 99 100 <listitem><para>The bus of <parameter>m</parameter> is not connected.</para></listitem> 101 </varlistentry> 102 103 <varlistentry> 104 <term><constant>-ECHILD</constant></term> 105 106 <listitem><para>The bus of <parameter>m</parameter> was created in a different process. 107 </para></listitem> 108 </varlistentry> 109 110 <varlistentry> 111 <term><constant>-EPERM</constant></term> 112 113 <listitem><para>The message <parameter>m</parameter> is not sealed.</para></listitem> 114 </varlistentry> 115 </variablelist> 116 </refsect2> 117 </refsect1> 118 119 <xi:include href="libsystemd-pkgconfig.xml" /> 120 121 <refsect1> 122 <title>See Also</title> 123 124 <para> 125 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 126 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 127 <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 128 <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 129 <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 130 <citerefentry><refentrytitle>sd_bus_creds_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 131 <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> 132 </para> 133 </refsect1> 134</refentry> 135