% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\section{library(uid): User and group management on Unix systems}

\label{sec:uid}

\begin{tags}
    \tag{See also}
Please check the documentation of your OS for details on the
semantics of this predicates.
\end{tags}

This module provides and interface to user and group information on
Posix systems. In addition, it allows for changing user and group ids.
When changing user and group settings for the calling process, bear in
mind that:

\begin{itemize}
    \item Changing user and groups of the calling process requires permission.
    \item The functions \verb$setgroups()$ and \verb$initgroups()$ are not part of the
POSIX standard and therefore the derived predicates may not be
present.
\end{itemize}

\vspace{0.7cm}

\begin{description}
    \predicate[det]{getuid}{1}{-UID}
\arg{UID} is the real user ID of the calling process.

    \predicate[det]{getgid}{1}{-GID}
\arg{GID} is the real group ID of the calling process.

    \predicate[det]{geteuid}{1}{-UID}
\arg{UID} is the effective user ID of the calling process.

    \predicate[det]{getegid}{1}{-GID}
\arg{GID} is the effective group ID of the calling process.

    \predicate[det]{getgroups}{1}{-GroupsIDs:list(integer)}
\arg{GroupsIDs} is the set of supplementary group IDs of the calling
process. Note that these are numeric identifiers. Use
\predref{group_info}{2} to obtain details on the returned group
identifiers.

    \predicate[det]{user_info}{2}{+User, -UserData}
\arg{UserData} represent the passwd information for \arg{User}. \arg{User} is
either a numeric UID or a user name. The predicate \predref{user_data}{3}
can be used to extract information from \arg{UserData}.

    \predicate{user_data}{3}{?Field, ?UserData, ?Value}
\arg{Value} is the value for \arg{Field} in \arg{UserData}. Defined fields are:

\begin{description}
    \termitem{name}{}
Name of the user
    \termitem{password}{}
Password hash of the user (or \const{x} if this is not accessible)
    \termitem{uid}{}
Numeric user id of the user
    \termitem{gid}{}
Numeric primary group id of the user
    \termitem{comment}{}
The \textit{gecos} field
    \termitem{home}{}
Home directory of the user
    \termitem{shell}{}
Default (login) shell of the user.
\end{description}

    \predicate[det]{group_info}{2}{+Group, -GroupData}
\arg{GroupData} represent the group information for \arg{Group}. \arg{Group} is
either a numeric GID or a group name. The predicate \predref{group_data}{3}
can be used to extract information from \arg{GroupData}.

    \predicate{group_data}{3}{?Field, ?GroupData, ?Value}
\arg{Value} is the value for \arg{Field} \arg{GroupData}. Defined fields are:

\begin{description}
    \termitem{name}{}
Name of the user
    \termitem{password}{}
Password hash of the user (or \const{x} if this is not accessible)
    \termitem{gid}{}
Numeric group id of the group
    \termitem{members}{}
List of user-names that are member of this group.
\end{description}

    \predicate{setuid}{1}{+UID}
Set the user id of the calling process.

    \predicate{seteuid}{1}{+UID}
Set the effective user id of the calling process.

    \predicate{setgid}{1}{+GID}
Set the group id of the calling process.

    \predicate{setegid}{1}{+GID}
Set the effective group id of the calling process.

    \predicate[det]{initgroups}{2}{+User, +Group}
Initialise the group access list of the calling process to the
registered groups for \arg{User} and the group \arg{Group}. This predicate
is only available if the underlying OS provides it.

    \predicate[det]{setgroups}{1}{+Groups:list(integer)}
Set the group access list of the caling process to the indicated
groups. This predicate is only available if the underlying OS
provides it.

    \predicate[det]{set_user_and_group}{1}{+User}
\nodescription
    \predicate[det]{set_user_and_group}{2}{+User, +Group}
Set the UID and GID to the \arg{User}. \arg{User} is either a UID or a user
name. If \arg{Group} is not specified, the primary group of \arg{User} is
used. If \predref{initgroups}{2} is available, the resulting group access
list of the calling process consists of the registered groups
for \arg{User} and the specified \arg{Group}.
\end{description}