libghc-unix-compat-doc 0.4.3.1-1 / usr / share / doc / libghc-unix-compat-doc / html / unix-compat.txt

-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Portable POSIX-compatibility layer.
--   
--   This package provides portable implementations of parts of the unix
--   package. This package re-exports the unix package when available. When
--   it isn't available, portable implementations are used.
@package unix-compat
@version 0.4.3.1


-- | This module makes the operations exported by
--   <tt>System.Posix.User</tt> available on all platforms. On POSIX
--   systems it re-exports operations from <tt>System.Posix.User</tt>. On
--   other platforms it provides dummy implementations.
module System.PosixCompat.User

-- | <tt>getRealUserID</tt> calls <tt>getuid</tt> to obtain the real
--   <tt>UserID</tt> associated with the current process.
getRealUserID :: IO UserID

-- | <tt>getRealGroupID</tt> calls <tt>getgid</tt> to obtain the real
--   <tt>GroupID</tt> associated with the current process.
getRealGroupID :: IO GroupID

-- | <tt>getEffectiveUserID</tt> calls <tt>geteuid</tt> to obtain the
--   effective <tt>UserID</tt> associated with the current process.
getEffectiveUserID :: IO UserID

-- | <tt>getEffectiveGroupID</tt> calls <tt>getegid</tt> to obtain the
--   effective <tt>GroupID</tt> associated with the current process.
getEffectiveGroupID :: IO GroupID

-- | <tt>getGroups</tt> calls <tt>getgroups</tt> to obtain the list of
--   supplementary <tt>GroupID</tt>s associated with the current process.
getGroups :: IO [GroupID]

-- | <tt>getLoginName</tt> calls <tt>getlogin</tt> to obtain the login name
--   associated with the current process.
getLoginName :: IO String

-- | <tt>getEffectiveUserName</tt> gets the name associated with the
--   effective <tt>UserID</tt> of the process.
getEffectiveUserName :: IO String
data GroupEntry :: *
GroupEntry :: String -> String -> GroupID -> [String] -> GroupEntry

-- | The name of this group (gr_name)
[groupName] :: GroupEntry -> String

-- | The password for this group (gr_passwd)
[groupPassword] :: GroupEntry -> String

-- | The unique numeric ID for this group (gr_gid)
[groupID] :: GroupEntry -> GroupID

-- | A list of zero or more usernames that are members (gr_mem)
[groupMembers] :: GroupEntry -> [String]

-- | <tt>getGroupEntryForID gid</tt> calls <tt>getgrgid_r</tt> to obtain
--   the <tt>GroupEntry</tt> information associated with <tt>GroupID</tt>
--   <tt>gid</tt>. This operation may fail with <a>isDoesNotExistError</a>
--   if no such group exists.
getGroupEntryForID :: GroupID -> IO GroupEntry

-- | <tt>getGroupEntryForName name</tt> calls <tt>getgrnam_r</tt> to obtain
--   the <tt>GroupEntry</tt> information associated with the group called
--   <tt>name</tt>. This operation may fail with <a>isDoesNotExistError</a>
--   if no such group exists.
getGroupEntryForName :: String -> IO GroupEntry

-- | <tt>getAllGroupEntries</tt> returns all group entries on the system by
--   repeatedly calling <tt>getgrent</tt>
getAllGroupEntries :: IO [GroupEntry]
data UserEntry :: *
UserEntry :: String -> String -> UserID -> GroupID -> String -> String -> String -> UserEntry

-- | Textual name of this user (pw_name)
[userName] :: UserEntry -> String

-- | Password -- may be empty or fake if shadow is in use (pw_passwd)
[userPassword] :: UserEntry -> String

-- | Numeric ID for this user (pw_uid)
[userID] :: UserEntry -> UserID

-- | Primary group ID (pw_gid)
[userGroupID] :: UserEntry -> GroupID

-- | Usually the real name for the user (pw_gecos)
[userGecos] :: UserEntry -> String

-- | Home directory (pw_dir)
[homeDirectory] :: UserEntry -> String

-- | Default shell (pw_shell)
[userShell] :: UserEntry -> String

-- | <tt>getUserEntryForID gid</tt> calls <tt>getpwuid_r</tt> to obtain the
--   <tt>UserEntry</tt> information associated with <tt>UserID</tt>
--   <tt>uid</tt>. This operation may fail with <a>isDoesNotExistError</a>
--   if no such user exists.
getUserEntryForID :: UserID -> IO UserEntry

-- | <tt>getUserEntryForName name</tt> calls <tt>getpwnam_r</tt> to obtain
--   the <tt>UserEntry</tt> information associated with the user login
--   <tt>name</tt>. This operation may fail with <a>isDoesNotExistError</a>
--   if no such user exists.
getUserEntryForName :: String -> IO UserEntry

-- | <tt>getAllUserEntries</tt> returns all user entries on the system by
--   repeatedly calling <tt>getpwent</tt>
getAllUserEntries :: IO [UserEntry]

-- | <tt>setUserID uid</tt> calls <tt>setuid</tt> to set the real,
--   effective, and saved set-user-id associated with the current process
--   to <tt>uid</tt>.
setUserID :: UserID -> IO ()

-- | <tt>setGroupID gid</tt> calls <tt>setgid</tt> to set the real,
--   effective, and saved set-group-id associated with the current process
--   to <tt>gid</tt>.
setGroupID :: GroupID -> IO ()


-- | This module makes the operations exported by
--   <tt>System.Posix.Unistd</tt> available on all platforms. On POSIX
--   systems it re-exports operations from <tt>System.Posix.Unistd</tt>, on
--   other platforms it emulates the operations as far as possible.
module System.PosixCompat.Unistd
data SystemID :: *
SystemID :: String -> String -> String -> String -> String -> SystemID
[systemName] :: SystemID -> String
[nodeName] :: SystemID -> String
[release] :: SystemID -> String
[version] :: SystemID -> String
[machine] :: SystemID -> String
getSystemID :: IO SystemID

-- | Sleep for the specified duration (in seconds). Returns the time
--   remaining (if the sleep was interrupted by a signal, for example).
--   
--   <i>GHC Note</i>: <a>threadDelay</a> is a better choice. Since GHC uses
--   signals for its internal clock, a call to <a>sleep</a> will usually be
--   interrupted immediately. That makes <a>sleep</a> unusable in a program
--   compiled with GHC, unless the RTS timer is disabled (with <tt>+RTS
--   -V0</tt>). Furthermore, without the <tt>-threaded</tt> option,
--   <a>sleep</a> will block all other user threads. Even with the
--   <tt>-threaded</tt> option, <a>sleep</a> requires a full OS thread to
--   itself. <a>threadDelay</a> has none of these shortcomings.
sleep :: Int -> IO Int

-- | Sleep for the specified duration (in microseconds).
--   
--   <i>GHC Note</i>: <a>threadDelay</a> is a better choice. Without the
--   <tt>-threaded</tt> option, <a>usleep</a> will block all other user
--   threads. Even with the <tt>-threaded</tt> option, <a>usleep</a>
--   requires a full OS thread to itself. <a>threadDelay</a> has neither of
--   these shortcomings.
usleep :: Int -> IO ()

-- | Sleep for the specified duration (in nanoseconds)
--   
--   <i>GHC Note</i>: the comment for <a>usleep</a> also applies here.
nanosleep :: Integer -> IO ()


-- | This module re-exports the types from <tt>System.Posix.Types</tt> on
--   all platforms.
--   
--   On Windows <a>UserID</a>, <a>GroupID</a> and <a>LinkCount</a> are
--   missing, so they are redefined by this module.
module System.PosixCompat.Types


-- | This module makes the operations exported by
--   <tt>System.Posix.Time</tt> available on all platforms. On POSIX
--   systems it re-exports operations from <tt>System.Posix.Time</tt>, on
--   other platforms it emulates the operations as far as possible.
module System.PosixCompat.Time

-- | <tt>epochTime</tt> calls <tt>time</tt> to obtain the number of seconds
--   that have elapsed since the epoch (Jan 01 00:00:00 GMT 1970).
epochTime :: IO EpochTime


-- | This module makes the operations exported by
--   <tt>System.Posix.Temp</tt> available on all platforms. On POSIX
--   systems it re-exports operations from <tt>System.Posix.Temp</tt>, on
--   other platforms it emulates the operations as far as possible.
module System.PosixCompat.Temp

-- | Make a unique filename and open it for reading/writing. The returned
--   <a>FilePath</a> is the (possibly relative) path of the created file,
--   which is padded with 6 random characters. The argument is the desired
--   prefix of the filepath of the temporary file to be created.
--   
--   If you aren't using GHC or Hugs then this function simply wraps mktemp
--   and so shouldn't be considered safe.
mkstemp :: String -> IO (FilePath, Handle)


-- | This module makes the operations exported by
--   <tt>System.Posix.Files</tt> available on all platforms. On POSIX
--   systems it re-exports operations from <tt>System.Posix.Files</tt>. On
--   other platforms it emulates the operations as far as possible.
--   
--   /NOTE: the portable implementations are not well tested, in some cases
--   functions are only stubs./
module System.PosixCompat.Files

-- | Combines the two file modes into one that contains modes that appear
--   in either.
unionFileModes :: FileMode -> FileMode -> FileMode

-- | Combines two file modes into one that only contains modes that appear
--   in both.
intersectFileModes :: FileMode -> FileMode -> FileMode

-- | No permissions.
nullFileMode :: FileMode

-- | Owner has read permission.
ownerReadMode :: FileMode

-- | Owner has write permission.
ownerWriteMode :: FileMode

-- | Owner has execute permission.
ownerExecuteMode :: FileMode

-- | Owner has read, write and execute permission.
ownerModes :: FileMode

-- | Group has read permission.
groupReadMode :: FileMode

-- | Group has write permission.
groupWriteMode :: FileMode

-- | Group has execute permission.
groupExecuteMode :: FileMode

-- | Group has read, write and execute permission.
groupModes :: FileMode

-- | Others have read permission.
otherReadMode :: FileMode

-- | Others have write permission.
otherWriteMode :: FileMode

-- | Others have execute permission.
otherExecuteMode :: FileMode

-- | Others have read, write and execute permission.
otherModes :: FileMode

-- | Set user ID on execution.
setUserIDMode :: FileMode

-- | Set group ID on execution.
setGroupIDMode :: FileMode

-- | Owner, group and others have read and write permission.
stdFileMode :: FileMode

-- | Owner, group and others have read, write and execute permission.
accessModes :: FileMode

-- | <tt>setFileMode path mode</tt> changes permission of the file given by
--   <tt>path</tt> to <tt>mode</tt>. This operation may fail with
--   <a>throwErrnoPathIfMinus1_</a> if <tt>path</tt> doesn't exist or if
--   the effective user ID of the current process is not that of the file's
--   owner.
--   
--   Note: calls <tt>chmod</tt>.
setFileMode :: FilePath -> FileMode -> IO ()

-- | <tt>setFdMode fd mode</tt> acts like <tt>setFileMode</tt> but uses a
--   file descriptor <tt>fd</tt> instead of a <a>FilePath</a>.
--   
--   Note: calls <tt>fchmod</tt>.
setFdMode :: Fd -> FileMode -> IO ()

-- | <tt>setFileCreationMask mode</tt> sets the file mode creation mask to
--   <tt>mode</tt>. Modes set by this operation are subtracted from files
--   and directories upon creation. The previous file creation mask is
--   returned.
--   
--   Note: calls <tt>umask</tt>.
setFileCreationMask :: FileMode -> IO FileMode

-- | <tt>fileAccess name read write exec</tt> checks if the file (or other
--   file system object) <tt>name</tt> can be accessed for reading, writing
--   and/or executing. To check a permission set the corresponding argument
--   to <a>True</a>.
--   
--   Note: calls <tt>access</tt>.
fileAccess :: FilePath -> Bool -> Bool -> Bool -> IO Bool

-- | Checks for the existence of the file.
--   
--   Note: calls <tt>access</tt>.
fileExist :: FilePath -> IO Bool

-- | POSIX defines operations to get information, such as owner,
--   permissions, size and access times, about a file. This information is
--   represented by the <a>FileStatus</a> type.
--   
--   Note: see <tt>chmod</tt>.
data FileStatus :: *

-- | <tt>getFileStatus path</tt> calls gets the <tt>FileStatus</tt>
--   information (user ID, size, access times, etc.) for the file
--   <tt>path</tt>.
--   
--   Note: calls <tt>stat</tt>.
getFileStatus :: FilePath -> IO FileStatus

-- | <tt>getFdStatus fd</tt> acts as <tt>getFileStatus</tt> but uses a file
--   descriptor <tt>fd</tt>.
--   
--   Note: calls <tt>fstat</tt>.
getFdStatus :: Fd -> IO FileStatus

-- | Acts as <a>getFileStatus</a> except when the <a>FilePath</a> refers to
--   a symbolic link. In that case the <tt>FileStatus</tt> information of
--   the symbolic link itself is returned instead of that of the file it
--   points to.
--   
--   Note: calls <tt>lstat</tt>.
getSymbolicLinkStatus :: FilePath -> IO FileStatus

-- | ID of the device on which this file resides.
deviceID :: FileStatus -> DeviceID

-- | inode number
fileID :: FileStatus -> FileID

-- | File mode (such as permissions).
fileMode :: FileStatus -> FileMode

-- | Number of hard links to this file.
linkCount :: FileStatus -> LinkCount

-- | ID of owner.
fileOwner :: FileStatus -> UserID

-- | ID of group.
fileGroup :: FileStatus -> GroupID

-- | Describes the device that this file represents.
specialDeviceID :: FileStatus -> DeviceID

-- | Size of the file in bytes. If this file is a symbolic link the size is
--   the length of the pathname it contains.
fileSize :: FileStatus -> FileOffset

-- | Time of last access.
accessTime :: FileStatus -> EpochTime

-- | Time of last modification.
modificationTime :: FileStatus -> EpochTime

-- | Time of last status change (i.e. owner, group, link count, mode,
--   etc.).
statusChangeTime :: FileStatus -> EpochTime

-- | Checks if this file is a block device.
isBlockDevice :: FileStatus -> Bool

-- | Checks if this file is a character device.
isCharacterDevice :: FileStatus -> Bool

-- | Checks if this file is a named pipe device.
isNamedPipe :: FileStatus -> Bool

-- | Checks if this file is a regular file device.
isRegularFile :: FileStatus -> Bool

-- | Checks if this file is a directory device.
isDirectory :: FileStatus -> Bool

-- | Checks if this file is a symbolic link device.
isSymbolicLink :: FileStatus -> Bool

-- | Checks if this file is a socket device.
isSocket :: FileStatus -> Bool

-- | <tt>createNamedPipe fifo mode</tt> creates a new named pipe,
--   <tt>fifo</tt>, with permissions based on <tt>mode</tt>. May fail with
--   <a>throwErrnoPathIfMinus1_</a> if a file named <tt>name</tt> already
--   exists or if the effective user ID of the current process doesn't have
--   permission to create the pipe.
--   
--   Note: calls <tt>mkfifo</tt>.
createNamedPipe :: FilePath -> FileMode -> IO ()

-- | <tt>createDevice path mode dev</tt> creates either a regular or a
--   special file depending on the value of <tt>mode</tt> (and
--   <tt>dev</tt>). <tt>mode</tt> will normally be either
--   <a>blockSpecialMode</a> or <a>characterSpecialMode</a>. May fail with
--   <a>throwErrnoPathIfMinus1_</a> if a file named <tt>name</tt> already
--   exists or if the effective user ID of the current process doesn't have
--   permission to create the file.
--   
--   Note: calls <tt>mknod</tt>.
createDevice :: FilePath -> FileMode -> DeviceID -> IO ()

-- | <tt>createLink old new</tt> creates a new path, <tt>new</tt>, linked
--   to an existing file, <tt>old</tt>.
--   
--   Note: calls <tt>link</tt>.
createLink :: FilePath -> FilePath -> IO ()

-- | <tt>removeLink path</tt> removes the link named <tt>path</tt>.
--   
--   Note: calls <tt>unlink</tt>.
removeLink :: FilePath -> IO ()

-- | <tt>createSymbolicLink file1 file2</tt> creates a symbolic link named
--   <tt>file2</tt> which points to the file <tt>file1</tt>.
--   
--   Symbolic links are interpreted at run-time as if the contents of the
--   link had been substituted into the path being followed to find a file
--   or directory.
--   
--   Note: calls <tt>symlink</tt>.
createSymbolicLink :: FilePath -> FilePath -> IO ()

-- | Reads the <tt>FilePath</tt> pointed to by the symbolic link and
--   returns it.
--   
--   Note: calls <tt>readlink</tt>.
readSymbolicLink :: FilePath -> IO FilePath

-- | <tt>rename old new</tt> renames a file or directory from <tt>old</tt>
--   to <tt>new</tt>.
--   
--   Note: calls <tt>rename</tt>.
rename :: FilePath -> FilePath -> IO ()

-- | <tt>setOwnerAndGroup path uid gid</tt> changes the owner and group of
--   <tt>path</tt> to <tt>uid</tt> and <tt>gid</tt>, respectively.
--   
--   If <tt>uid</tt> or <tt>gid</tt> is specified as -1, then that ID is
--   not changed.
--   
--   Note: calls <tt>chown</tt>.
setOwnerAndGroup :: FilePath -> UserID -> GroupID -> IO ()

-- | Acts as <tt>setOwnerAndGroup</tt> but uses a file descriptor instead
--   of a <a>FilePath</a>.
--   
--   Note: calls <tt>fchown</tt>.
setFdOwnerAndGroup :: Fd -> UserID -> GroupID -> IO ()

-- | Acts as <a>setOwnerAndGroup</a> but does not follow symlinks (and thus
--   changes permissions on the link itself).
--   
--   Note: calls <tt>lchown</tt>.
setSymbolicLinkOwnerAndGroup :: FilePath -> UserID -> GroupID -> IO ()

-- | <tt>setFileTimes path atime mtime</tt> sets the access and
--   modification times associated with file <tt>path</tt> to
--   <tt>atime</tt> and <tt>mtime</tt>, respectively.
--   
--   Note: calls <tt>utime</tt>.
setFileTimes :: FilePath -> EpochTime -> EpochTime -> IO ()

-- | <tt>touchFile path</tt> sets the access and modification times
--   associated with file <tt>path</tt> to the current time.
--   
--   Note: calls <tt>utime</tt>.
touchFile :: FilePath -> IO ()

-- | Truncates the file down to the specified length. If the file was
--   larger than the given length before this operation was performed the
--   extra is lost.
--   
--   Note: calls <tt>truncate</tt>.
setFileSize :: FilePath -> FileOffset -> IO ()

-- | Acts as <tt>setFileSize</tt> but uses a file descriptor instead of a
--   <a>FilePath</a>.
--   
--   Note: calls <tt>ftruncate</tt>.
setFdSize :: Fd -> FileOffset -> IO ()
data PathVar :: *
FileSizeBits :: PathVar
LinkLimit :: PathVar
InputLineLimit :: PathVar
InputQueueLimit :: PathVar
FileNameLimit :: PathVar
PathNameLimit :: PathVar
PipeBufferLimit :: PathVar
SymbolicLinkLimit :: PathVar
SetOwnerAndGroupIsRestricted :: PathVar
FileNamesAreNotTruncated :: PathVar
VDisableChar :: PathVar
AsyncIOAvailable :: PathVar
PrioIOAvailable :: PathVar
SyncIOAvailable :: PathVar

-- | <tt>getPathVar var path</tt> obtains the dynamic value of the
--   requested configurable file limit or option associated with file or
--   directory <tt>path</tt>. For defined file limits, <tt>getPathVar</tt>
--   returns the associated value. For defined file options, the result of
--   <tt>getPathVar</tt> is undefined, but not failure.
--   
--   Note: calls <tt>pathconf</tt>.
getPathVar :: FilePath -> PathVar -> IO Limit

-- | <tt>getFdPathVar var fd</tt> obtains the dynamic value of the
--   requested configurable file limit or option associated with the file
--   or directory attached to the open channel <tt>fd</tt>. For defined
--   file limits, <tt>getFdPathVar</tt> returns the associated value. For
--   defined file options, the result of <tt>getFdPathVar</tt> is
--   undefined, but not failure.
--   
--   Note: calls <tt>fpathconf</tt>.
getFdPathVar :: Fd -> PathVar -> IO Limit


-- | This module provides some functions not present in the unix package.
module System.PosixCompat.Extensions
type CMajor = CUInt
type CMinor = CUInt

-- | Gets the major number from a <a>DeviceID</a> for a device file.
--   
--   The portable implementation always returns <tt>0</tt>.
deviceMajor :: DeviceID -> CMajor

-- | Gets the minor number from a <a>DeviceID</a> for a device file.
--   
--   The portable implementation always returns <tt>0</tt>.
deviceMinor :: DeviceID -> CMinor

-- | Creates a <a>DeviceID</a> for a device file given a major and minor
--   number.
makeDeviceID :: CMajor -> CMinor -> DeviceID


-- | The <tt>unix-compat</tt> package provides portable implementations of
--   parts of the <tt>unix</tt> package. On POSIX system it re-exports
--   operations from the <tt>unix</tt> package, on other platforms it
--   emulates the operations as far as possible.
module System.PosixCompat

-- | <a>True</a> if unix-compat is using its portable implementation, or
--   <a>False</a> if the unix package is simply being re-exported.
usingPortableImpl :: Bool