| Portability | non-portable (requires POSIX) |
|---|---|
| Stability | provisional |
| Maintainer | libraries@haskell.org |
| Safe Haskell | Trustworthy |
System.Posix.Files
Contents
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.
- 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
- 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
- getPathVar :: FilePath -> PathVar -> IO Limit
- getFdPathVar :: Fd -> PathVar -> IO Limit
File modes
unionFileModes :: FileMode -> FileMode -> FileModeSource
Combines the two file modes into one that contains modes that appear in either.
intersectFileModes :: FileMode -> FileMode -> FileModeSource
Combines two file modes into one that only contains modes that appear in both.
nullFileMode :: FileModeSource
No permissions.
ownerReadMode :: FileModeSource
Owner has read permission.
ownerWriteMode :: FileModeSource
Owner has write permission.
ownerExecuteMode :: FileModeSource
Owner has execute permission.
Owner has read, write and execute permission.
groupReadMode :: FileModeSource
Group has read permission.
groupWriteMode :: FileModeSource
Group has write permission.
groupExecuteMode :: FileModeSource
Group has execute permission.
Group has read, write and execute permission.
otherReadMode :: FileModeSource
Others have read permission.
otherWriteMode :: FileModeSource
Others have write permission.
otherExecuteMode :: FileModeSource
Others have execute permission.
Others have read, write and execute permission.
setUserIDMode :: FileModeSource
Set user ID on execution.
setGroupIDMode :: FileModeSource
Set group ID on execution.
Owner, group and others have read and write permission.
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 FileModeSource
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 BoolSource
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.
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 FileStatusSource
getFileStatus path calls gets the FileStatus information (user ID,
size, access times, etc.) for the file path.
Note: calls stat.
getFdStatus :: Fd -> IO FileStatusSource
getFdStatus fd acts as getFileStatus but uses a file descriptor fd.
Note: calls fstat.
getSymbolicLinkStatus :: FilePath -> IO FileStatusSource
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 -> DeviceIDSource
ID of the device on which this file resides.
fileID :: FileStatus -> FileIDSource
inode number
fileMode :: FileStatus -> FileModeSource
File mode (such as permissions).
linkCount :: FileStatus -> LinkCountSource
Number of hard links to this file.
fileOwner :: FileStatus -> UserIDSource
ID of owner.
fileGroup :: FileStatus -> GroupIDSource
ID of group.
specialDeviceID :: FileStatus -> DeviceIDSource
Describes the device that this file represents.
fileSize :: FileStatus -> FileOffsetSource
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 -> EpochTimeSource
Time of last access.
modificationTime :: FileStatus -> EpochTimeSource
Time of last modification.
statusChangeTime :: FileStatus -> EpochTimeSource
Time of last status change (i.e. owner, group, link count, mode, etc.).
accessTimeHiRes :: FileStatus -> POSIXTimeSource
Time of last access in sub-second resolution.
modificationTimeHiRes :: FileStatus -> POSIXTimeSource
Time of last modification in sub-second resolution.
statusChangeTimeHiRes :: FileStatus -> POSIXTimeSource
Time of last status change (i.e. owner, group, link count, mode, etc.) in sub-second resolution.
isBlockDevice :: FileStatus -> BoolSource
Checks if this file is a block device.
isCharacterDevice :: FileStatus -> BoolSource
Checks if this file is a character device.
isNamedPipe :: FileStatus -> BoolSource
Checks if this file is a named pipe device.
isRegularFile :: FileStatus -> BoolSource
Checks if this file is a regular file device.
isDirectory :: FileStatus -> BoolSource
Checks if this file is a directory device.
isSymbolicLink :: FileStatus -> BoolSource
Checks if this file is a symbolic link device.
isSocket :: FileStatus -> BoolSource
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 FilePathSource
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
getPathVar :: FilePath -> PathVar -> IO LimitSource
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 LimitSource
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.