From: Daan De Meyer <daan.j.demeyer@gmail.com>
Date: Thu, 23 Apr 2020 19:40:52 +0000 (+0200)
Subject: sd-bus: Add sd_bus_message_get_creds docs
X-Git-Tag: v246-rc1~503
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=68b5003bc1fae2ed29b71998647b01a1a5244232;p=thirdparty%2Fsystemd.git

sd-bus: Add sd_bus_message_get_creds docs
---

diff --git a/man/rules/meson.build b/man/rules/meson.build
index a25fff09b96..55923b700a8 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -292,7 +292,8 @@ manpages = [
   ''],
  ['sd_bus_message_get_type',
   '3',
-  ['sd_bus_message_get_errno',
+  ['sd_bus_message_get_creds',
+   'sd_bus_message_get_errno',
    'sd_bus_message_get_error',
    'sd_bus_message_is_method_call',
    'sd_bus_message_is_method_error',
diff --git a/man/sd-bus.xml b/man/sd-bus.xml
index 62823d2780f..780e1834b2d 100644
--- a/man/sd-bus.xml
+++ b/man/sd-bus.xml
@@ -103,6 +103,7 @@
 <citerefentry><refentrytitle>sd_bus_message_exit_container</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_message_get_allow_interactive_authorization</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_message_get_cookie</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_message_get_errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_message_get_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
diff --git a/man/sd_bus_message_get_type.xml b/man/sd_bus_message_get_type.xml
index 7c5e0df6175..2b962413d2a 100644
--- a/man/sd_bus_message_get_type.xml
+++ b/man/sd_bus_message_get_type.xml
@@ -19,11 +19,12 @@
     <refname>sd_bus_message_get_type</refname>
     <refname>sd_bus_message_get_error</refname>
     <refname>sd_bus_message_get_errno</refname>
+    <refname>sd_bus_message_get_creds</refname>
     <refname>sd_bus_message_is_signal</refname>
     <refname>sd_bus_message_is_method_call</refname>
     <refname>sd_bus_message_is_method_error</refname>
 
-    <refpurpose>Query bus message addressing metadata</refpurpose>
+    <refpurpose>Query bus message addressing/credentials metadata</refpurpose>
   </refnamediv>
 
   <refsynopsisdiv>
@@ -46,6 +47,11 @@
         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
       </funcprototype>
 
+      <funcprototype>
+        <funcdef>sd_bus_creds* <function>sd_bus_message_get_creds</function></funcdef>
+        <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
+      </funcprototype>
+
       <funcprototype>
         <funcdef>int <function>sd_bus_message_is_signal</function></funcdef>
         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
@@ -93,6 +99,11 @@
     <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
     </para>
 
+    <para><function>sd_bus_message_get_creds()</function> returns the message credentials attached to the
+    message <parameter>m</parameter>. If no credentials are attached to the message, it returns
+    <constant>NULL</constant>. Ownership of the credentials instance is not transferred to the caller and
+    hence should not be freed.</para>
+
     <para><function>sd_bus_message_is_signal()</function> checks if message <parameter>m</parameter> is a
     signal message. If <parameter>interface</parameter> is non-null, it also checks if the message has the
     same interface set. If <parameter>member</parameter> is non-null, it also checks if the message has the
@@ -117,9 +128,10 @@
   <refsect1>
     <title>Return Value</title>
 
-    <para>On success, these functions return a non-negative integer. On failure, they return a negative
-    errno-style error code. <function>sd_bus_message_get_errno()</function> always returns a non-negative
-    integer, even on failure.</para>
+    <para>On success, these functions (except <function>sd_bus_message_get_error()</function> and
+    <function>sd_bus_message_get_creds()</function>) return a non-negative integer. On failure, they return a
+    negative errno-style error code. <function>sd_bus_message_get_errno()</function> always returns a
+    non-negative integer, even on failure.</para>
 
     <refsect2>
       <title>Errors</title>