Doc/lib/libpwd.tex

   1 \section{\module{pwd} ---
   2          The password database}
   3
   4 \declaremodule{builtin}{pwd}
   5   \platform{Unix}
   6 \modulesynopsis{The password database (\function{getpwnam()} and friends).}
   7
   8 This module provides access to the \UNIX{} user account and password
   9 database.  It is available on all \UNIX{} versions.
  10
  11 Password database entries are reported as a tuple-like object, whose
  12 attributes correspond to the members of the \code{passwd} structure
  13 (Attribute field below, see \code{<pwd.h>}):
  14
  15 \begin{tableiii}{r|l|l}{textrm}{Index}{Attribute}{Meaning}
  16   \lineiii{0}{\code{pw_name}}{Login name}
  17   \lineiii{1}{\code{pw_passwd}}{Optional encrypted password}
  18   \lineiii{2}{\code{pw_uid}}{Numerical user ID}
  19   \lineiii{3}{\code{pw_gid}}{Numerical group ID}
  20   \lineiii{4}{\code{pw_gecos}}{User name or comment field}
  21   \lineiii{5}{\code{pw_dir}}{User home directory}
  22   \lineiii{6}{\code{pw_shell}}{User command interpreter}
  23 \end{tableiii}
  24
  25 The uid and gid items are integers, all others are strings.
  26 \exception{KeyError} is raised if the entry asked for cannot be found.
  27
  28 \note{In traditional \UNIX{} the field \code{pw_passwd} usually
  29 contains a password encrypted with a DES derived algorithm (see module
  30 \refmodule{crypt}\refbimodindex{crypt}).  However most modern unices
  31 use a so-called \emph{shadow password} system.  On those unices the
  32 \var{pw_passwd} field only contains an asterisk (\code{'*'}) or the
  33 letter \character{x} where the encrypted password is stored in a file
  34 \file{/etc/shadow} which is not world readable.  Whether the \var{pw_passwd}
  35 field contains anything useful is system-dependent.  If available, the
  36 \module{spwd} module should be used where access to the encrypted password
  37 is required.}
  38
  39 It defines the following items:
  40
  41 \begin{funcdesc}{getpwuid}{uid}
  42 Return the password database entry for the given numeric user ID.
  43 \end{funcdesc}
  44
  45 \begin{funcdesc}{getpwnam}{name}
  46 Return the password database entry for the given user name.
  47 \end{funcdesc}
  48
  49 \begin{funcdesc}{getpwall}{}
  50 Return a list of all available password database entries, in arbitrary order.
  51 \end{funcdesc}
  52
  53
  54 \begin{seealso}
  55   \seemodule{grp}{An interface to the group database, similar to this.}
  56   \seemodule{spwd}{An interface to the shadow password database, similar to this.}
  57 \end{seealso}