unix-2.4.2.0: POSIX functionality

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

System.Posix.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

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

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

intersectFileModes :: FileMode -> FileMode -> FileMode

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

nullFileMode :: FileMode

No permissions.

ownerReadMode :: FileMode

Owner has read permission.

ownerWriteMode :: FileMode

Owner has write permission.

ownerExecuteMode :: FileMode

Owner has execute permission.

ownerModes :: FileMode

Owner has read, write and execute permission.

groupReadMode :: FileMode

Group has read permission.

groupWriteMode :: FileMode

Group has write permission.

groupExecuteMode :: FileMode

Group has execute permission.

groupModes :: FileMode

Group has read, write and execute permission.

otherReadMode :: FileMode

Others have read permission.

otherWriteMode :: FileMode

Others have write permission.

otherExecuteMode :: FileMode

Others have execute permission.

otherModes :: FileMode

Others have read, write and execute permission.

setUserIDMode :: FileMode

Set user ID on execution.

setGroupIDMode :: FileMode

Set group ID on execution.

stdFileMode :: FileMode

Owner, group and others have read and write permission.

accessModes :: FileMode

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

fileTypeModes :: FileMode

blockSpecialMode :: FileMode

characterSpecialMode :: FileMode

namedPipeMode :: FileMode

regularFileMode :: FileMode

directoryMode :: FileMode

symbolicLinkMode :: FileMode

socketMode :: FileMode

## Setting file modes

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

`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 ()

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

Note: calls `fchmod`.

setFileCreationMask :: FileMode -> IO FileMode

`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

`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

Checks for the existence of the file.

Note: calls `access`.

# File status

data FileStatus

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

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

Note: calls `stat`.

getFdStatus :: Fd -> IO FileStatus

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

Note: calls `fstat`.

getSymbolicLinkStatus :: FilePath -> IO FileStatus

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

ID of the device on which this file resides.

fileID :: FileStatus -> FileID

inode number

fileMode :: FileStatus -> FileMode

File mode (such as permissions).

linkCount :: FileStatus -> LinkCount

Number of hard links to this file.

fileOwner :: FileStatus -> UserID

ID of owner.

fileGroup :: FileStatus -> GroupID

ID of group.

specialDeviceID :: FileStatus -> DeviceID

Describes the device that this file represents.

fileSize :: FileStatus -> FileOffset

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

Time of last access.

modificationTime :: FileStatus -> EpochTime

Time of last modification.

statusChangeTime :: FileStatus -> EpochTime

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

isBlockDevice :: FileStatus -> Bool

Checks if this file is a block device.

isCharacterDevice :: FileStatus -> Bool

Checks if this file is a character device.

isNamedPipe :: FileStatus -> Bool

Checks if this file is a named pipe device.

isRegularFile :: FileStatus -> Bool

Checks if this file is a regular file device.

isDirectory :: FileStatus -> Bool

Checks if this file is a directory device.

isSymbolicLink :: FileStatus -> Bool

Checks if this file is a symbolic link device.

isSocket :: FileStatus -> Bool

Checks if this file is a socket device.

# Creation

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

`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 ()

`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 ()

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

Note: calls `link`.

removeLink :: FilePath -> IO ()

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

Note: calls `unlink`.

# Symbolic links

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

`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

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

Note: calls `readlink`.

# Renaming files

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

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

Note: calls `rename`.

# Changing file ownership

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

`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 ()

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

Note: calls `fchown`.

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

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

`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 ()

`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 ()

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

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

Note: calls `ftruncate`.

# Find system-specific limits for a file

data PathVar

Constructors

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

getPathVar :: FilePath -> PathVar -> IO Limit

`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

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