| unix-2.3.2.0: POSIX functionality | Source code | Contents | Index

System.Posix.Files

Portability | non-portable (requires POSIX)
Stability | provisional
Maintainer | libraries@haskell.org

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

Functions defined by the POSIX standards for manipulating and querying the file system. Names of underlying POSIX functions are indicated whenever possible. A more complete documentation of the POSIX functions together with a more detailed description of different error conditions are usually available in the system's manual pages or from http://www.unix.org/version3/online.html (free registration required).

When a function that calls an underlying POSIX function fails, the errno code is converted to an `IOError` using Foreign.C.Error.errnoToIOError. For a list of which errno codes may be generated, consult the POSIX documentation for the underlying function.

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
fileTypeModes :: FileMode
blockSpecialMode :: FileMode
characterSpecialMode :: FileMode
namedPipeMode :: FileMode
regularFileMode :: FileMode
directoryMode :: FileMode
symbolicLinkMode :: FileMode
socketMode :: 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
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.

fileTypeModes :: FileMode | Source

blockSpecialMode :: FileMode | Source

characterSpecialMode :: FileMode | Source

namedPipeMode :: FileMode | Source

regularFileMode :: FileMode | Source

directoryMode :: FileMode | Source

symbolicLinkMode :: FileMode | Source

socketMode :: FileMode | Source

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

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.).

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 file1 file2` creates a symbolic link named `file2` which points to the file `file1`. 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`.
Produced by Haddock version 2.4.2