unix-compat-0.7.4.1: Portable POSIX-compatibility layer.

Safe Haskell | Safe-Inferred
Language | Haskell2010

System.PosixCompat.Files

Contents

- File modes
  - Setting file modes
  - Checking file existence and permissions
- File status
  - Obtaining file status
  - Querying file status
- Creation
- Hard links
- Symbolic links
- Renaming files
- Changing file ownership
- Changing file timestamps
- Setting file sizes
- Find system-specific limits for a file

Description

This module makes the operations exported by `System.Posix.Files` available on all platforms. On POSIX systems it re-exports operations from `System.Posix.Files`. 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./

Synopsis

- unionFileModes :: FileMode -> FileMode -> FileMode
- intersectFileModes :: FileMode -> FileMode -> FileMode
- nullFileMode :: FileMode
- ownerReadMode :: FileMode
- ownerWriteMode :: FileMode
- ownerExecuteMode :: FileMode
- ownerModes :: FileMode
- groupReadMode :: FileMode
- groupWriteMode :: FileMode
- groupExecuteMode :: FileMode
- groupModes :: FileMode
- otherReadMode :: FileMode
- otherWriteMode :: FileMode
- otherExecuteMode :: FileMode
- otherModes :: FileMode
- setUserIDMode :: FileMode
- setGroupIDMode :: FileMode
- stdFileMode :: FileMode
- accessModes :: FileMode
- setFileMode :: FilePath -> FileMode -> IO ()
- setFdMode :: Fd -> FileMode -> IO ()
- setFileCreationMask :: FileMode -> IO FileMode
- fileAccess :: FilePath -> Bool -> Bool -> Bool -> IO Bool
- fileExist :: FilePath -> IO Bool
- data FileStatus
- getFileStatus :: FilePath -> IO FileStatus
- getFdStatus :: Fd -> IO FileStatus
- getSymbolicLinkStatus :: FilePath -> IO FileStatus
- deviceID :: FileStatus -> DeviceID
- fileID :: FileStatus -> FileID
- fileMode :: FileStatus -> FileMode
- linkCount :: FileStatus -> LinkCount
- fileOwner :: FileStatus -> UserID
- fileGroup :: FileStatus -> GroupID
- specialDeviceID :: FileStatus -> DeviceID
- fileSize :: FileStatus -> FileOffset
- accessTime :: FileStatus -> EpochTime
- modificationTime :: FileStatus -> EpochTime
- statusChangeTime :: FileStatus -> EpochTime
- accessTimeHiRes :: FileStatus -> POSIXTime
- modificationTimeHiRes :: FileStatus -> POSIXTime
- statusChangeTimeHiRes :: FileStatus -> POSIXTime
- isBlockDevice :: FileStatus -> Bool
- isCharacterDevice :: FileStatus -> Bool
- isNamedPipe :: FileStatus -> Bool
- isRegularFile :: FileStatus -> Bool
- isDirectory :: FileStatus -> Bool
- isSymbolicLink :: FileStatus -> Bool
- isSocket :: FileStatus -> Bool
- createNamedPipe :: FilePath -> FileMode -> IO ()
- createDevice :: FilePath -> FileMode -> DeviceID -> IO ()
- createLink :: FilePath -> FilePath -> IO ()
- removeLink :: FilePath -> IO ()
- createSymbolicLink :: FilePath -> FilePath -> IO ()
- readSymbolicLink :: FilePath -> IO FilePath
- rename :: FilePath -> FilePath -> IO ()
- setOwnerAndGroup :: FilePath -> UserID -> GroupID -> IO ()
- setFdOwnerAndGroup :: Fd -> UserID -> GroupID -> IO ()
- setSymbolicLinkOwnerAndGroup :: FilePath -> UserID -> GroupID -> IO ()
- setFileTimes :: FilePath -> EpochTime -> EpochTime -> IO ()
- touchFile :: FilePath -> IO ()
- setFileSize :: FilePath -> FileOffset -> IO ()
- setFdSize :: Fd -> FileOffset -> IO ()
- data PathVar
  - = FileSizeBits
  - | LinkLimit
  - | InputLineLimit
  - | InputQueueLimit
  - | FileNameLimit
  - | PathNameLimit
  - | PipeBufferLimit
  - | SymbolicLinkLimit
  - | SetOwnerAndGroupIsRestricted
  - | FileNamesAreNotTruncated
  - | VDisableChar
  - | AsyncIOAvailable
  - | PrioIOAvailable
  - | SyncIOAvailable
- getPathVar :: FilePath -> PathVar -> IO Limit
- getFdPathVar :: Fd -> PathVar -> IO Limit

# File modes

unionFileModes :: FileMode -> FileMode -> FileMode Source #

Combines the two file modes into one that contains modes that appear in either.

intersectFileModes :: FileMode -> FileMode -> FileMode Source #

Combines two file modes into one that only contains modes that appear in both.

nullFileMode :: FileMode Source #

No permissions.

ownerReadMode :: FileMode Source #

Owner has read permission.

ownerWriteMode :: FileMode Source #

Owner has write permission.

ownerExecuteMode :: FileMode Source #

Owner has execute permission.

ownerModes :: FileMode Source #

Owner has read, write and execute permission.

groupReadMode :: FileMode Source #

Group has read permission.

groupWriteMode :: FileMode Source #

Group has write permission.

groupExecuteMode :: FileMode Source #

Group has execute permission.

groupModes :: FileMode Source #

Group has read, write and execute permission.

otherReadMode :: FileMode Source #

Others have read permission.

otherWriteMode :: FileMode Source #

Others have write permission.

otherExecuteMode :: FileMode Source #

Others have execute permission.

otherModes :: FileMode Source #

Others have read, write and execute permission.

setUserIDMode :: FileMode Source #

Set user ID on execution.

setGroupIDMode :: FileMode Source #

Set group ID on execution.

stdFileMode :: FileMode Source #

Owner, group and others have read and write permission.

accessModes :: FileMode Source #

Owner, group and others have read, write and execute permission.

## Setting file modes

setFileMode :: FilePath -> FileMode -> IO () Source #

`setFileMode path mode` changes permission of the file given by `path` to `mode`. This operation may fail with `throwErrnoPathIfMinus1_` if `path` doesn't exist or if the effective user ID of the current process is not that of the file's owner.

Note: calls `chmod`.

setFdMode :: Fd -> FileMode -> IO () Source #

`setFdMode fd mode` acts like `setFileMode` but uses a file descriptor `fd` instead of a `FilePath`.

Note: calls `fchmod`.

setFileCreationMask :: FileMode -> IO FileMode Source #

`setFileCreationMask mode` sets the file mode creation mask to `mode`. Modes set by this operation are subtracted from files and directories upon creation. The previous file creation mask is returned.

Note: calls `umask`.

## Checking file existence and permissions

fileAccess :: FilePath -> Bool -> Bool -> Bool -> IO Bool Source #

`fileAccess name read write exec` checks if the file (or other file system object) `name` can be accessed for reading, writing and/or executing. To check a permission set the corresponding argument to `True`.

Note: calls `access`.

fileExist :: FilePath -> IO Bool Source #

Checks for the existence of the file.

Note: calls `access`.

# File status

data FileStatus Source #

POSIX defines operations to get information, such as owner, permissions, size and access times, about a file. This information is represented by the `FileStatus` type.

Note: see `chmod`.

Limitations: Support for high resolution timestamps is filesystem dependent:

- HFS+ volumes on OS X only support whole-second times.

## Obtaining file status

getFileStatus :: FilePath -> IO FileStatus Source #

`getFileStatus path` calls gets the `FileStatus` information (user ID, size, access times, etc.) for the file `path`.

Note: calls `stat`.

getFdStatus :: Fd -> IO FileStatus Source #

`getFdStatus fd` acts as `getFileStatus` but uses a file descriptor `fd`.

Note: calls `fstat`.

getSymbolicLinkStatus :: FilePath -> IO FileStatus Source #

Acts as `getFileStatus` except when the `FilePath` refers to a symbolic link. In that case the `FileStatus` information of the symbolic link itself is returned instead of that of the file it points to.

Note: calls `lstat`.

## Querying file status

deviceID :: FileStatus -> DeviceID Source #

ID of the device on which this file resides.

fileID :: FileStatus -> FileID Source #

inode number

fileMode :: FileStatus -> FileMode Source #

File mode (such as permissions).

linkCount :: FileStatus -> LinkCount Source #

Number of hard links to this file.

fileOwner :: FileStatus -> UserID Source #

ID of owner.

fileGroup :: FileStatus -> GroupID Source #

ID of group.

specialDeviceID :: FileStatus -> DeviceID Source #

Describes the device that this file represents.

fileSize :: FileStatus -> FileOffset Source #

Size of the file in bytes. If this file is a symbolic link the size is the length of the pathname it contains.

accessTime :: FileStatus -> EpochTime Source #

Time of last access.

modificationTime :: FileStatus -> EpochTime Source #

Time of last modification.

statusChangeTime :: FileStatus -> EpochTime Source #

Time of last status change (i.e. owner, group, link count, mode, etc.).

accessTimeHiRes :: FileStatus -> POSIXTime Source #

Time of last access in sub-second resolution. Depends on the timestamp resolution of the underlying filesystem.

modificationTimeHiRes :: FileStatus -> POSIXTime Source #

Time of last modification in sub-second resolution. Depends on the timestamp resolution of the underlying filesystem.

statusChangeTimeHiRes :: FileStatus -> POSIXTime Source #

Time of last status change (i.e. owner, group, link count, mode, etc.) in sub-second resolution. Depends on the timestamp resolution of the underlying filesystem.

isBlockDevice :: FileStatus -> Bool Source #

Checks if this file is a block device.

isCharacterDevice :: FileStatus -> Bool Source #

Checks if this file is a character device.

isNamedPipe :: FileStatus -> Bool Source #

Checks if this file is a named pipe device.

isRegularFile :: FileStatus -> Bool Source #

Checks if this file is a regular file device.

isDirectory :: FileStatus -> Bool Source #

Checks if this file is a directory device.

isSymbolicLink :: FileStatus -> Bool Source #

Checks if this file is a symbolic link device.

isSocket :: FileStatus -> Bool Source #

Checks if this file is a socket device.

# Creation

createNamedPipe :: FilePath -> FileMode -> IO () Source #

`createNamedPipe fifo mode` creates a new named pipe, `fifo`, with permissions based on `mode`. May fail with `throwErrnoPathIfMinus1_` if a file named `name` already exists or if the effective user ID of the current process doesn't have permission to create the pipe.

Note: calls `mkfifo`.

createDevice :: FilePath -> FileMode -> DeviceID -> IO () Source #

`createDevice path mode dev` creates either a regular or a special file depending on the value of `mode` (and `dev`). `mode` will normally be either `blockSpecialMode` or `characterSpecialMode`. May fail with `throwErrnoPathIfMinus1_` if a file named `name` already exists or if the effective user ID of the current process doesn't have permission to create the file.

Note: calls `mknod`.

# Hard links

createLink :: FilePath -> FilePath -> IO () Source #

`createLink old new` creates a new path, `new`, linked to an existing file, `old`.

Note: calls `link`.

removeLink :: FilePath -> IO () Source #

`removeLink path` removes the link named `path`.

Note: calls `unlink`.

# Symbolic links

createSymbolicLink :: FilePath -> FilePath -> IO () Source #

`createSymbolicLink name1 name2` creates a symbolic link named `name2` which points to the file `name1`.

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 `symlink`.

readSymbolicLink :: FilePath -> IO FilePath Source #

Reads the `FilePath` pointed to by the symbolic link and returns it.

Note: calls `readlink`.

# Renaming files

rename :: FilePath -> FilePath -> IO () Source #

`rename old new` renames a file or directory from `old` to `new`.

Note: calls `rename`.

# Changing file ownership

setOwnerAndGroup :: FilePath -> UserID -> GroupID -> IO () Source #

`setOwnerAndGroup path uid gid` changes the owner and group of `path` to `uid` and `gid`, respectively.

If `uid` or `gid` is specified as -1, then that ID is not changed.

Note: calls `chown`.

setFdOwnerAndGroup :: Fd -> UserID -> GroupID -> IO () Source #

Acts as `setOwnerAndGroup` but uses a file descriptor instead of a `FilePath`.

Note: calls `fchown`.

setSymbolicLinkOwnerAndGroup :: FilePath -> UserID -> GroupID -> IO () Source #

Acts as `setOwnerAndGroup` but does not follow symlinks (and thus changes permissions on the link itself).

Note: calls `lchown`.

# Changing file timestamps

setFileTimes :: FilePath -> EpochTime -> EpochTime -> IO () Source #

`setFileTimes path atime mtime` sets the access and modification times associated with file `path` to `atime` and `mtime`, respectively.

Note: calls `utime`.

touchFile :: FilePath -> IO () Source #

`touchFile path` sets the access and modification times associated with file `path` to the current time.

Note: calls `utime`.

# Setting file sizes

setFileSize :: FilePath -> FileOffset -> IO () Source #

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 `truncate`.

setFdSize :: Fd -> FileOffset -> IO () Source #

Acts as `setFileSize` but uses a file descriptor instead of a `FilePath`.

Note: calls `ftruncate`.

# Find system-specific limits for a file

data PathVar Source #

Constructors

FileSizeBits |
LinkLimit |
InputLineLimit |
InputQueueLimit |
FileNameLimit |
PathNameLimit |
PipeBufferLimit |
SymbolicLinkLimit |
SetOwnerAndGroupIsRestricted |
FileNamesAreNotTruncated |
VDisableChar |
AsyncIOAvailable |
PrioIOAvailable |
SyncIOAvailable |

getPathVar :: FilePath -> PathVar -> IO Limit Source #

`getPathVar var path` obtains the dynamic value of the requested configurable file limit or option associated with file or directory `path`. For defined file limits, `getPathVar` returns the associated value. For defined file options, the result of `getPathVar` is undefined, but not failure.

Note: calls `pathconf`.

getFdPathVar :: Fd -> PathVar -> IO Limit Source #

`getFdPathVar var fd` obtains the dynamic value of the requested configurable file limit or option associated with the file or directory attached to the open channel `fd`. For defined file limits, `getFdPathVar` returns the associated value. For defined file options, the result of `getFdPathVar` is undefined, but not failure.

Note: calls `fpathconf`.