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 | Safe |
Language | Haskell2010 |
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
- 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 :: RawFilePath -> FileMode -> IO ()
- setFdMode :: Fd -> FileMode -> IO ()
- setFileCreationMask :: FileMode -> IO FileMode
- fileAccess :: RawFilePath -> Bool -> Bool -> Bool -> IO Bool
- fileExist :: RawFilePath -> IO Bool
- data FileStatus
- getFileStatus :: RawFilePath -> IO FileStatus
- getFdStatus :: Fd -> IO FileStatus
- getSymbolicLinkStatus :: RawFilePath -> 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
- fileBlockSize :: FileStatus -> Maybe CBlkSize
- fileBlocks :: FileStatus -> Maybe CBlkCnt
- createNamedPipe :: RawFilePath -> FileMode -> IO ()
- createDevice :: RawFilePath -> FileMode -> DeviceID -> IO ()
- createLink :: RawFilePath -> RawFilePath -> IO ()
- removeLink :: RawFilePath -> IO ()
- createSymbolicLink :: RawFilePath -> RawFilePath -> IO ()
- readSymbolicLink :: RawFilePath -> IO RawFilePath
- rename :: RawFilePath -> RawFilePath -> IO ()
- setOwnerAndGroup :: RawFilePath -> UserID -> GroupID -> IO ()
- setFdOwnerAndGroup :: Fd -> UserID -> GroupID -> IO ()
- setSymbolicLinkOwnerAndGroup :: RawFilePath -> UserID -> GroupID -> IO ()
- setFileTimes :: RawFilePath -> EpochTime -> EpochTime -> IO ()
- setFileTimesHiRes :: RawFilePath -> POSIXTime -> POSIXTime -> IO ()
- setFdTimesHiRes :: Fd -> POSIXTime -> POSIXTime -> IO ()
- setSymbolicLinkTimesHiRes :: RawFilePath -> POSIXTime -> POSIXTime -> IO ()
- touchFile :: RawFilePath -> IO ()
- touchFd :: Fd -> IO ()
- touchSymbolicLink :: RawFilePath -> IO ()
- setFileSize :: RawFilePath -> FileOffset -> IO ()
- setFdSize :: Fd -> FileOffset -> IO ()
- data PathVar
- getPathVar :: RawFilePath -> 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 :: RawFilePath -> 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 :: RawFilePath -> 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 :: RawFilePath -> 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 :: RawFilePath -> 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 :: RawFilePath -> IO FileStatus Source #
Acts as getFileStatus
except when the RawFilePath
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.
fileBlockSize :: FileStatus -> Maybe CBlkSize Source #
Gives the preferred block size for efficient filesystem I/O in
bytes. Returns Nothing
if st_blocksize
is not supported on this
platform.
fileBlocks :: FileStatus -> Maybe CBlkCnt Source #
Number of blocks allocated for this file, in units of
512-bytes. Returns Nothing
if st_blocks
is not supported on this
platform.
Creation
createNamedPipe :: RawFilePath -> 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 :: RawFilePath -> 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 :: RawFilePath -> RawFilePath -> IO () Source #
createLink old new
creates a new path, new
, linked to an existing file,
old
.
Note: calls link
.
removeLink :: RawFilePath -> IO () Source #
removeLink path
removes the link named path
.
Note: calls unlink
.
Symbolic links
createSymbolicLink :: RawFilePath -> RawFilePath -> 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 :: RawFilePath -> IO RawFilePath Source #
Reads the RawFilePath
pointed to by the symbolic link and returns it.
Note: calls readlink
.
Renaming files
rename :: RawFilePath -> RawFilePath -> IO () Source #
rename old new
renames a file or directory from old
to new
.
Note: calls rename
.
Changing file ownership
setOwnerAndGroup :: RawFilePath -> 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 :: RawFilePath -> 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 :: RawFilePath -> 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 :: RawFilePath -> POSIXTime -> POSIXTime -> IO () Source #
Like setFileTimes
but timestamps can have sub-second resolution.
Note: calls utimensat
or utimes
. Support for high resolution timestamps
is filesystem dependent with the following limitations:
- HFS+ volumes on OS X truncate the sub-second part of the timestamp.
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
. Support for high resolution timestamps
is filesystem dependent with the following limitations:
- HFS+ volumes on OS X truncate the sub-second part of the timestamp.
Since: 2.7.0.0
setSymbolicLinkTimesHiRes :: RawFilePath -> 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
. Support for high resolution timestamps
is filesystem dependent with the following limitations:
- HFS+ volumes on OS X truncate the sub-second part of the timestamp.
touchFile :: RawFilePath -> 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 :: RawFilePath -> 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
.
Setting file sizes
setFileSize :: RawFilePath -> 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
getPathVar :: RawFilePath -> 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
.