readutmp: Add comment about multithread-safety

[Bruno Haible]

read_utmp() is not MT-safe.


2023-08-08  Bruno Haible  <bruno@clisp.org>

        readutmp: Add comment about multithread-safety.
        * lib/readutmp.h (read_utmp): Add comment.

diff --git a/lib/readutmp.h b/lib/readutmp.h
index 1ddb617b28..9377a1b57f 100644
--- a/lib/readutmp.h
+++ b/lib/readutmp.h
@@ -255,7 +255,13 @@ char *extract_trimmed_name (const STRUCT_UTMP *ut)
    If OPTIONS & READ_UTMP_CHECK_PIDS is nonzero, omit entries whose
    process-IDs do not currently exist.
    If OPTIONS & READ_UTMP_USER_PROCESS is nonzero, omit entries which
-   do not correspond to a user process.  */
+   do not correspond to a user process.
+
+   This function is not multithread-safe, since on many platforms it
+   invokes the functions setutxent, getutxent, endutxent.  These
+   functions are needed because they may lock FILE (so that we don't
+   read garbage when a concurrent process writes to FILE), but their
+   drawback is that they have a common global state.  */
 int read_utmp (char const *file, idx_t *n_entries, STRUCT_UTMP **utmp_buf,
                int options);