blob: 03ebb02e4e5136ffda973dae3d651af513c65927 [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001:mod:`pwd` --- The password database
2====================================
3
4.. module:: pwd
5 :platform: Unix
6 :synopsis: The password database (getpwnam() and friends).
7
Terry Jan Reedyfa089b92016-06-11 15:02:54 -04008--------------
Georg Brandl116aa622007-08-15 14:28:22 +00009
10This module provides access to the Unix user account and password database. It
11is available on all Unix versions.
12
13Password database entries are reported as a tuple-like object, whose attributes
14correspond to the members of the ``passwd`` structure (Attribute field below,
15see ``<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
35The uid and gid items are integers, all others are strings. :exc:`KeyError` is
36raised 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
51It 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