ask-password: add comment with well-known errors from ask_password_auto()

diff --git a/src/shared/ask-password-api.c b/src/shared/ask-password-api.c
index 502b22ee89efa806deb24ff1ce597c87cd3d411b..df8915082b38f37c67dcc56d13e6cdae4538b92f 100644 (file)
--- a/src/shared/ask-password-api.c
+++ b/src/shared/ask-password-api.c
@@ -1165,6 +1165,17 @@ int ask_password_auto(
 
         assert(ret);
 
+        /* Returns the following well-known errors:
+         *
+         *      -ETIME → a timeout was specified and hit
+         *    -EUNATCH → couldn't ask interactively and no cached password available either
+         *     -ENOENT → the specified flag file disappeared
+         *  -ECANCELED → the user explicitly cancelled the request
+         *      -EINTR → SIGINT/SIGTERM where received during the query
+         *    -ENOEXEC → headless mode was requested but no password could be acquired non-interactively
+         * -ECONNRESET → a POLLHUP has been seen on the specified hup_fd
+         */
+
         if (!FLAGS_SET(flags, ASK_PASSWORD_NO_CREDENTIAL) && req && req->credential) {
                 r = ask_password_credential(req, flags, ret);
                 if (r != -ENOKEY)