Doc/library/pwd.rst

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