unix-2.7.1.0: POSIX functionality

Copyright | (c) The University of Glasgow 2002
License | BSD-style (see the file libraries/base/LICENSE)
Maintainer | libraries@haskell.org
Stability | provisional
Portability | non-portable (requires POSIX)
Safe Haskell | Trustworthy
Language | Haskell2010

System.Posix.User

Contents

- User environment
  - Querying the user environment
    - The group database
    - The user database
  - Modifying the user environment

Description

POSIX user/group support

Synopsis

- getRealUserID :: IO UserID
- getRealGroupID :: IO GroupID
- getEffectiveUserID :: IO UserID
- getEffectiveGroupID :: IO GroupID
- getGroups :: IO [GroupID]
- getLoginName :: IO String
- getEffectiveUserName :: IO String
- data GroupEntry = GroupEntry {
  - groupName :: String
  - groupPassword :: String
  - groupID :: GroupID
  - groupMembers :: [String]
  }
- getGroupEntryForID :: GroupID -> IO GroupEntry
- getGroupEntryForName :: String -> IO GroupEntry
- getAllGroupEntries :: IO [GroupEntry]
- data UserEntry = UserEntry {
  - userName :: String
  - userPassword :: String
  - userID :: UserID
  - userGroupID :: GroupID
  - userGecos :: String
  - homeDirectory :: String
  - userShell :: String
  }
- getUserEntryForID :: UserID -> IO UserEntry
- getUserEntryForName :: String -> IO UserEntry
- getAllUserEntries :: IO [UserEntry]
- setUserID :: UserID -> IO ()
- setGroupID :: GroupID -> IO ()
- setEffectiveUserID :: UserID -> IO ()
- setEffectiveGroupID :: GroupID -> IO ()
- setGroups :: [GroupID] -> IO ()

# User environment

## Querying the user environment

getRealUserID :: IO UserID

`getRealUserID` calls `getuid` to obtain the real `UserID` associated with the current process.

getRealGroupID :: IO GroupID

`getRealGroupID` calls `getgid` to obtain the real `GroupID` associated with the current process.

getEffectiveUserID :: IO UserID

`getEffectiveUserID` calls `geteuid` to obtain the effective `UserID` associated with the current process.

getEffectiveGroupID :: IO GroupID

`getEffectiveGroupID` calls `getegid` to obtain the effective `GroupID` associated with the current process.

getGroups :: IO [GroupID]

`getGroups` calls `getgroups` to obtain the list of supplementary `GroupID`s associated with the current process.

getLoginName :: IO String

`getLoginName` calls `getlogin` to obtain the login name associated with the current process.

getEffectiveUserName :: IO String

`getEffectiveUserName` gets the name associated with the effective `UserID` of the process.

### The group database

data GroupEntry

Constructors

GroupEntry |

Fields

groupName :: String

  The name of this group (gr_name)

groupPassword :: String

  The password for this group (gr_passwd)

groupID :: GroupID

  The unique numeric ID for this group (gr_gid)

groupMembers :: [String]

  A list of zero or more usernames that are members (gr_mem)

Instances

Eq GroupEntry |
Read GroupEntry |
Show GroupEntry |

getGroupEntryForID :: GroupID -> IO GroupEntry

`getGroupEntryForID gid` calls `getgrgid_r` to obtain the `GroupEntry` information associated with `GroupID` `gid`. This operation may fail with `isDoesNotExistError` if no such group exists.

getGroupEntryForName :: String -> IO GroupEntry

`getGroupEntryForName name` calls `getgrnam_r` to obtain the `GroupEntry` information associated with the group called `name`. This operation may fail with `isDoesNotExistError` if no such group exists.

getAllGroupEntries :: IO [GroupEntry]

`getAllGroupEntries` returns all group entries on the system by repeatedly calling `getgrent`

### The user database

data UserEntry

Constructors

UserEntry |

Fields

userName :: String

  Textual name of this user (pw_name)

userPassword :: String

  Password -- may be empty or fake if shadow is in use (pw_passwd)

userID :: UserID

  Numeric ID for this user (pw_uid)

userGroupID :: GroupID

  Primary group ID (pw_gid)

userGecos :: String

  Usually the real name for the user (pw_gecos)

homeDirectory :: String

  Home directory (pw_dir)

userShell :: String

  Default shell (pw_shell)

Instances

Eq UserEntry |
Read UserEntry |
Show UserEntry |

getUserEntryForID :: UserID -> IO UserEntry

`getUserEntryForID gid` calls `getpwuid_r` to obtain the `UserEntry` information associated with `UserID` `uid`. This operation may fail with `isDoesNotExistError` if no such user exists.

getUserEntryForName :: String -> IO UserEntry

`getUserEntryForName name` calls `getpwnam_r` to obtain the `UserEntry` information associated with the user login `name`. This operation may fail with `isDoesNotExistError` if no such user exists.

getAllUserEntries :: IO [UserEntry]

`getAllUserEntries` returns all user entries on the system by repeatedly calling `getpwent`

## Modifying the user environment

setUserID :: UserID -> IO ()

`setUserID uid` calls `setuid` to set the real, effective, and saved set-user-id associated with the current process to `uid`.

setGroupID :: GroupID -> IO ()

`setGroupID gid` calls `setgid` to set the real, effective, and saved set-group-id associated with the current process to `gid`.

setEffectiveUserID :: UserID -> IO ()

`setEffectiveUserID uid` calls `seteuid` to set the effective user-id associated with the current process to `uid`. This does not update the real user-id or set-user-id.

setEffectiveGroupID :: GroupID -> IO ()

`setEffectiveGroupID uid` calls `setegid` to set the effective group-id associated with the current process to `gid`. This does not update the real group-id or set-group-id.

setGroups :: [GroupID] -> IO ()

`setGroups` calls `setgroups` to set the list of supplementary `GroupID`s associated with the current process.