summaryrefslogtreecommitdiffstats
path: root/Doc/library/pwd.rst
blob: 03ebb02e4e5136ffda973dae3d651af513c65927 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
:mod:`pwd` --- The password database
====================================

.. module:: pwd
   :platform: Unix
   :synopsis: The password database (getpwnam() and friends).

--------------

This module provides access to the Unix user account and password database.  It
is available on all Unix versions.

Password database entries are reported as a tuple-like object, whose attributes
correspond to the members of the ``passwd`` structure (Attribute field below,
see ``<pwd.h>``):

+-------+---------------+-----------------------------+
| Index | Attribute     | Meaning                     |
+=======+===============+=============================+
| 0     | ``pw_name``   | Login name                  |
+-------+---------------+-----------------------------+
| 1     | ``pw_passwd`` | Optional encrypted password |
+-------+---------------+-----------------------------+
| 2     | ``pw_uid``    | Numerical user ID           |
+-------+---------------+-----------------------------+
| 3     | ``pw_gid``    | Numerical group ID          |
+-------+---------------+-----------------------------+
| 4     | ``pw_gecos``  | User name or comment field  |
+-------+---------------+-----------------------------+
| 5     | ``pw_dir``    | User home directory         |
+-------+---------------+-----------------------------+
| 6     | ``pw_shell``  | User command interpreter    |
+-------+---------------+-----------------------------+

The uid and gid items are integers, all others are strings. :exc:`KeyError` is
raised if the entry asked for cannot be found.

.. note::

   .. index:: module: crypt

   In traditional Unix the field ``pw_passwd`` usually contains a password
   encrypted with a DES derived algorithm (see module :mod:`crypt`).  However most
   modern unices  use a so-called *shadow password* system.  On those unices the
   *pw_passwd* field only contains an asterisk (``'*'``) or the  letter ``'x'``
   where the encrypted password is stored in a file :file:`/etc/shadow` which is
   not world readable.  Whether the *pw_passwd* field contains anything useful is
   system-dependent.  If available, the :mod:`spwd` module should be used where
   access to the encrypted password is required.

It defines the following items:


.. function:: getpwuid(uid)

   Return the password database entry for the given numeric user ID.


.. function:: getpwnam(name)

   Return the password database entry for the given user name.


.. function:: getpwall()

   Return a list of all available password database entries, in arbitrary order.


.. seealso::

   Module :mod:`grp`
      An interface to the group database, similar to this.

   Module :mod:`spwd`
      An interface to the shadow password database, similar to this.