Update guidance on situations where there is no polkit authority

Now that GDBusProxy does something reasonable for a masked systemd
service, see

 https://bugzilla.gnome.org/show_bug.cgi?id=677718

construction of the PolkitAuthority object does not fail anymore. That
doesn't mean the authority is available, though, so mention that users
should check the result of the CheckAuthorization() call as well. Or
in the case of PolkitAuthority, that the error is not a POLKIT_ERROR.

This is actually a nice feature, it means that if you unmask
polkit.service then mechanisms using PolkitAuthority will start using
it without a restart.

Signed-off-by: David Zeuthen <zeuthen@gmail.com>

diff --git a/docs/polkit/overview.xml b/docs/polkit/overview.xml
index 0639d30..45cdba0 100644 (file)
--- a/docs/polkit/overview.xml
+++ b/docs/polkit/overview.xml
@@ -118,7 +118,12 @@
             <link linkend="polkit-authority-get-sync">polkit_authority_get_sync()</link>
             or
             <link linkend="polkit-authority-get-finish">polkit_authority_get_finish()</link>
-            returning <constant>NULL</constant>.
+            returning <constant>NULL</constant> or
+            <link linkend="polkit-authority-check-authorization">polkit_authority_check_authorization()</link> /
+            <link linkend="polkit-authority-check-authorization-sync">polkit_authority_check_authorization_sync()</link>
+            failing with an error not in the
+            <link linkend="POLKIT-ERROR:CAPS">POLKIT_ERROR</link>
+            domain.
             An appropriate way of dealing with the polkit authority
             not being available, could be to allow only uid 0 to
             perform operations, forbid all operations or something