docs: permit user/group services that do not support enumeration

[thirdparty/systemd.git] / docs / USER_GROUP_API.md

diff --git a/docs/USER_GROUP_API.md b/docs/USER_GROUP_API.md
index 21d498f5fd11298309756b56f1d7bb77ed5cb3dd..55f6af7d8ea534052ec467bc5a1ef516f22195e6 100644 (file)
--- a/docs/USER_GROUP_API.md
+++ b/docs/USER_GROUP_API.md
@@ -1,6 +1,6 @@
 ---
 title: User/Group Record Lookup API via Varlink
-category: Interfaces
+category: Users, Groups and Home Directories
 layout: default
 ---
 
@@ -95,7 +95,7 @@ services are listening there, that have special relevance:
 2. `io.systemd.Multiplexer` → This service multiplexes client queries to all
    other running services. It's supposed to simplify client development: in
    order to look up or enumerate user/group records it's sufficient to talk to
-   one service instead of all of them in parallel. Note that it is not availabe
+   one service instead of all of them in parallel. Note that it is not available
    during earliest boot and final shutdown phases, hence for programs running
    in that context it is preferable to implement the parallel lookup
    themselves.
@@ -160,7 +160,7 @@ method GetUserRecord(
         service : string
 ) -> (
         record : object,
-        incomplete : boolean
+        incomplete : bool
 )
 
 method GetGroupRecord(
@@ -169,7 +169,7 @@ method GetGroupRecord(
         service : string
 ) -> (
         record : object,
-        incomplete : boolean
+        incomplete : bool
 )
 
 method GetMemberships(
@@ -185,6 +185,7 @@ error NoRecordFound()
 error BadService()
 error ServiceNotAvailable()
 error ConflictingRecordFound()
+error EnumerationNotSupported()
 ```
 
 The `GetUserRecord` method looks up or enumerates a user record. If the `uid`
@@ -264,4 +265,11 @@ services. Result of this is that it can be one service that defines a user A,
 and another service that defines a group B, and a third service that declares
 that A is a member of B.
 
+Looking up explicit users/groups by their name or UID/GID, or querying
+user/group memberships must be supported by all services implementing these
+interfaces. However, supporting enumeration (i.e. user/group lookups that may
+result in more than one reply, because neither UID/GID nor name is specified)
+is optional. Services which are asked for enumeration may return the
+`EnumerationNotSupported` error in this case.
+
 And that's really all there is to it.