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.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 errnoToIOError. For a list of which errno codes may be generated, consult the POSIX documentation for the underlying function.

Synopsis

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

accessTimeHiRes :: FileStatus -> POSIXTime Source

Time of last access in sub-second resolution.

modificationTimeHiRes :: FileStatus -> POSIXTime Source

Time of last modification in sub-second resolution.

statusChangeTimeHiRes :: FileStatus -> POSIXTime Source

Time of last status change (i.e. owner, group, link count, mode, etc.) in sub-second resolution.

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.

setFileTimesHiRes :: FilePath -> POSIXTime -> POSIXTime -> IO () Source

Like setFileTimes but timestamps can have sub-second resolution.

Note: calls utimensat or utimes.

Since: 2.7.0.0

setFdTimesHiRes :: Fd -> POSIXTime -> POSIXTime -> IO () Source

Like setFileTimesHiRes but uses a file descriptor instead of a path. This operation is not supported on all platforms. On these platforms, this function will raise an exception.

Note: calls futimens or futimes.

Since: 2.7.0.0

setSymbolicLinkTimesHiRes :: FilePath -> POSIXTime -> POSIXTime -> IO () Source

Like setFileTimesHiRes but does not follow symbolic links. This operation is not supported on all platforms. On these platforms, this function will raise an exception.

Note: calls utimensat or lutimes.

Since: 2.7.0.0

touchFile :: FilePath -> IO () Source

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

Note: calls utime.

touchFd :: Fd -> IO () Source

Like touchFile but uses a file descriptor instead of a path. This operation is not supported on all platforms. On these platforms, this function will raise an exception.

Note: calls futimes.

Since: 2.7.0.0

touchSymbolicLink :: FilePath -> IO () Source

Like touchFile but does not follow symbolic links. This operation is not supported on all platforms. On these platforms, this function will raise an exception.

Note: calls lutimes.

Since: 2.7.0.0

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.