System.Posix.Files

unix-2.8.5.1: POSIX functionality

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

System.Posix.Files

Contents

- File modes
  - Setting file modes
  - Checking file existence and permissions
- File status
  - Obtaining file status
  - Querying file status
- Extended file status
  - Obtaining extended file status
  - Flags
  - Mask
  - Querying extended 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

- 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
- newtype FileStatus = FileStatus (ForeignPtr CStat)
- 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
- fileBlockSize :: FileStatus -> Maybe CBlkSize
- fileBlocks :: FileStatus -> Maybe CBlkCnt
- newtype ExtendedFileStatus = ExtendedFileStatus (ForeignPtr CStatx)
- newtype CAttributes = CAttributes Word64
- haveStatx :: Bool
- getExtendedFileStatus :: Maybe Fd -> FilePath -> StatxFlags -> StatxMask -> IO ExtendedFileStatus
- newtype StatxFlags = StatxFlags CInt
- defaultStatxFlags :: StatxFlags
- pattern EmptyPath :: StatxFlags
- pattern NoAutoMount :: StatxFlags
- pattern SymlinkNoFollow :: StatxFlags
- pattern SyncAsStat :: StatxFlags
- pattern ForceSync :: StatxFlags
- pattern DontSync :: StatxFlags
- newtype StatxMask = StatxMask CInt
- defaultStatxMask :: StatxMask
- pattern StatxType :: StatxMask
- pattern StatxMode :: StatxMask
- pattern StatxNlink :: StatxMask
- pattern StatxUid :: StatxMask
- pattern StatxGid :: StatxMask
- pattern StatxAtime :: StatxMask
- pattern StatxMtime :: StatxMask
- pattern StatxCtime :: StatxMask
- pattern StatxIno :: StatxMask
- pattern StatxSize :: StatxMask
- pattern StatxBlocks :: StatxMask
- pattern StatxBasicStats :: StatxMask
- pattern StatxBtime :: StatxMask
- pattern StatxMntId :: StatxMask
- pattern StatxAll :: StatxMask
- fileBlockSizeX :: ExtendedFileStatus -> CBlkSize
- linkCountX :: ExtendedFileStatus -> CNlink
- fileOwnerX :: ExtendedFileStatus -> UserID
- fileGroupX :: ExtendedFileStatus -> GroupID
- fileModeX :: ExtendedFileStatus -> FileMode
- fileIDX :: ExtendedFileStatus -> FileID
- fileSizeX :: ExtendedFileStatus -> Word64
- fileBlocksX :: ExtendedFileStatus -> Word64
- accessTimeHiResX :: ExtendedFileStatus -> POSIXTime
- creationTimeHiResX :: ExtendedFileStatus -> POSIXTime
- statusChangeTimeHiResX :: ExtendedFileStatus -> POSIXTime
- modificationTimeHiResX :: ExtendedFileStatus -> POSIXTime
- deviceIDX :: ExtendedFileStatus -> DeviceID
- specialDeviceIDX :: ExtendedFileStatus -> DeviceID
- mountIDX :: ExtendedFileStatus -> Word64
- fileCompressedX :: ExtendedFileStatus -> Bool
- fileImmutableX :: ExtendedFileStatus -> Bool
- fileAppendX :: ExtendedFileStatus -> Bool
- fileNoDumpX :: ExtendedFileStatus -> Bool
- fileEncryptedX :: ExtendedFileStatus -> Bool
- fileVerityX :: ExtendedFileStatus -> Bool
- fileDaxX :: ExtendedFileStatus -> Bool
- isBlockDeviceX :: ExtendedFileStatus -> Bool
- isCharacterDeviceX :: ExtendedFileStatus -> Bool
- isNamedPipeX :: ExtendedFileStatus -> Bool
- isRegularFileX :: ExtendedFileStatus -> Bool
- isDirectoryX :: ExtendedFileStatus -> Bool
- isSymbolicLinkX :: ExtendedFileStatus -> Bool
- isSocketX :: ExtendedFileStatus -> 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 ()
- setFileTimesHiRes :: FilePath -> POSIXTime -> POSIXTime -> IO ()
- setFdTimesHiRes :: Fd -> POSIXTime -> POSIXTime -> IO ()
- setSymbolicLinkTimesHiRes :: FilePath -> POSIXTime -> POSIXTime -> IO ()
- touchFile :: FilePath -> IO ()
- touchFd :: Fd -> IO ()
- touchSymbolicLink :: 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

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

Constructors

FileStatus (ForeignPtr CStat) | The constructor is considered internal and may change.

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

# Extended file status

newtype ExtendedFileStatus Source #

Constructors

ExtendedFileStatus (ForeignPtr CStatx) | The constructor is considered internal and may change.

newtype CAttributes Source #

Constructors

CAttributes Word64 |

#### Instances

Instances details

Bits CAttributes Source # |
Instance details Defined in System.Posix.Files.Common Methods (.&.) :: CAttributes -> CAttributes -> CAttributes # (.|.) :: CAttributes -> CAttributes -> CAttributes # xor :: CAttributes -> CAttributes -> CAttributes # complement :: CAttributes -> CAttributes # shift :: CAttributes -> Int -> CAttributes # rotate :: CAttributes -> Int -> CAttributes # zeroBits :: CAttributes # bit :: Int -> CAttributes # setBit :: CAttributes -> Int -> CAttributes # clearBit :: CAttributes -> Int -> CAttributes # complementBit :: CAttributes -> Int -> CAttributes # testBit :: CAttributes -> Int -> Bool # bitSizeMaybe :: CAttributes -> Maybe Int # bitSize :: CAttributes -> Int # isSigned :: CAttributes -> Bool # shiftL :: CAttributes -> Int -> CAttributes # unsafeShiftL :: CAttributes -> Int -> CAttributes # shiftR :: CAttributes -> Int -> CAttributes # unsafeShiftR :: CAttributes -> Int -> CAttributes # rotateL :: CAttributes -> Int -> CAttributes # rotateR :: CAttributes -> Int -> CAttributes # popCount :: CAttributes -> Int #
Storable CAttributes Source # |
Instance details Defined in System.Posix.Files.Common Methods sizeOf :: CAttributes -> Int # alignment :: CAttributes -> Int # peekElemOff :: Ptr CAttributes -> Int -> IO CAttributes # pokeElemOff :: Ptr CAttributes -> Int -> CAttributes -> IO () # peekByteOff :: Ptr b -> Int -> IO CAttributes # pokeByteOff :: Ptr b -> Int -> CAttributes -> IO () # peek :: Ptr CAttributes -> IO CAttributes # poke :: Ptr CAttributes -> CAttributes -> IO () #
Num CAttributes Source # |
Instance details Defined in System.Posix.Files.Common Methods (+) :: CAttributes -> CAttributes -> CAttributes # (-) :: CAttributes -> CAttributes -> CAttributes # (*) :: CAttributes -> CAttributes -> CAttributes # negate :: CAttributes -> CAttributes # abs :: CAttributes -> CAttributes # signum :: CAttributes -> CAttributes # fromInteger :: Integer -> CAttributes #
Read CAttributes Source # |
Instance details Defined in System.Posix.Files.Common Methods readsPrec :: Int -> ReadS CAttributes # readList :: ReadS [CAttributes] # readPrec :: ReadPrec CAttributes # readListPrec :: ReadPrec [CAttributes] #
Show CAttributes Source # |
Instance details Defined in System.Posix.Files.Common Methods showsPrec :: Int -> CAttributes -> ShowS # show :: CAttributes -> String # showList :: [CAttributes] -> ShowS #
Eq CAttributes Source # |
Instance details Defined in System.Posix.Files.Common Methods (==) :: CAttributes -> CAttributes -> Bool # (/=) :: CAttributes -> CAttributes -> Bool #
Ord CAttributes Source # |
Instance details Defined in System.Posix.Files.Common Methods compare :: CAttributes -> CAttributes -> Ordering # (<) :: CAttributes -> CAttributes -> Bool # (<=) :: CAttributes -> CAttributes -> Bool # (>) :: CAttributes -> CAttributes -> Bool # (>=) :: CAttributes -> CAttributes -> Bool # max :: CAttributes -> CAttributes -> CAttributes # min :: CAttributes -> CAttributes -> CAttributes #

haveStatx :: Bool Source #

Whether `statx` is available on this platform and `getExtendedFileStatus` and related functions will work.

## Obtaining extended file status

getExtendedFileStatus Source #

Arguments

:: Maybe Fd | Optional directory file descriptor (`dirfd`)
-> FilePath | `pathname` to open
-> StatxFlags | flags
-> StatxMask | mask
-> IO ExtendedFileStatus |

Gets extended file status information.

The target file to open is identified in one of the following ways:

- If `pathname` begins with a slash, then it is an absolute pathname that identifies the target file. In this case, `dirfd` is ignored
- If `pathname` is a string that begins with a character other than a slash and `dirfd` is a file descriptor that refers to a directory, then pathname is a relative pathname that is interpreted relative to the directory referred to by dirfd. (See `openat(2)` for an explanation of why this is useful.)
- If `pathname` is an empty string and the `EmptyPath` flag is specified in flags (see below), then the target file is the one referred to by the file descriptor `dirfd`.

Note: calls `statx`.

## Flags

newtype StatxFlags Source #

Statx flags.

See the pattern synonyms for possible flags. These are combined via `(<>)`. Flags can be tested via `(.&.)`.

The following flags influence pathname-based lookup:

- `EmptyPath`
- `NoAutoMount`
- `SymlinkNoFollow`

The following flags can be used to control what sort of synchronization the kernel will do when querying a file on a remote filesystem:

- `SyncAsStat`
- `ForceSync`
- `DontSync`

Constructors

StatxFlags CInt |

#### Instances

Instances details

Monoid StatxFlags Source # |
Instance details Defined in System.Posix.Files.Common Methods mempty :: StatxFlags # mappend :: StatxFlags -> StatxFlags -> StatxFlags # mconcat :: [StatxFlags] -> StatxFlags #
Semigroup StatxFlags Source # | ORs the flags.
Instance details Defined in System.Posix.Files.Common Methods (<>) :: StatxFlags -> StatxFlags -> StatxFlags # sconcat :: NonEmpty StatxFlags -> StatxFlags # stimes :: Integral b => b -> StatxFlags -> StatxFlags #
Bits StatxFlags Source # |
Instance details Defined in System.Posix.Files.Common Methods (.&.) :: StatxFlags -> StatxFlags -> StatxFlags # (.|.) :: StatxFlags -> StatxFlags -> StatxFlags # xor :: StatxFlags -> StatxFlags -> StatxFlags # complement :: StatxFlags -> StatxFlags # shift :: StatxFlags -> Int -> StatxFlags # rotate :: StatxFlags -> Int -> StatxFlags # zeroBits :: StatxFlags # bit :: Int -> StatxFlags # setBit :: StatxFlags -> Int -> StatxFlags # clearBit :: StatxFlags -> Int -> StatxFlags # complementBit :: StatxFlags -> Int -> StatxFlags # testBit :: StatxFlags -> Int -> Bool # bitSizeMaybe :: StatxFlags -> Maybe Int # bitSize :: StatxFlags -> Int # isSigned :: StatxFlags -> Bool # shiftL :: StatxFlags -> Int -> StatxFlags # unsafeShiftL :: StatxFlags -> Int -> StatxFlags # shiftR :: StatxFlags -> Int -> StatxFlags # unsafeShiftR :: StatxFlags -> Int -> StatxFlags # rotateL :: StatxFlags -> Int -> StatxFlags # rotateR :: StatxFlags -> Int -> StatxFlags # popCount :: StatxFlags -> Int #
Enum StatxFlags Source # |
Instance details Defined in System.Posix.Files.Common Methods succ :: StatxFlags -> StatxFlags # pred :: StatxFlags -> StatxFlags # toEnum :: Int -> StatxFlags # fromEnum :: StatxFlags -> Int # enumFrom :: StatxFlags -> [StatxFlags] # enumFromThen :: StatxFlags -> StatxFlags -> [StatxFlags] # enumFromTo :: StatxFlags -> StatxFlags -> [StatxFlags] # enumFromThenTo :: StatxFlags -> StatxFlags -> StatxFlags -> [StatxFlags] #
Num StatxFlags Source # |
Instance details Defined in System.Posix.Files.Common Methods (+) :: StatxFlags -> StatxFlags -> StatxFlags # (-) :: StatxFlags -> StatxFlags -> StatxFlags # (*) :: StatxFlags -> StatxFlags -> StatxFlags # negate :: StatxFlags -> StatxFlags # abs :: StatxFlags -> StatxFlags # signum :: StatxFlags -> StatxFlags # fromInteger :: Integer -> StatxFlags #
Read StatxFlags Source # |
Instance details Defined in System.Posix.Files.Common Methods readsPrec :: Int -> ReadS StatxFlags # readList :: ReadS [StatxFlags] # readPrec :: ReadPrec StatxFlags # readListPrec :: ReadPrec [StatxFlags] #
Integral StatxFlags Source # |
Instance details Defined in System.Posix.Files.Common Methods quot :: StatxFlags -> StatxFlags -> StatxFlags # rem :: StatxFlags -> StatxFlags -> StatxFlags # div :: StatxFlags -> StatxFlags -> StatxFlags # mod :: StatxFlags -> StatxFlags -> StatxFlags # quotRem :: StatxFlags -> StatxFlags -> (StatxFlags, StatxFlags) # divMod :: StatxFlags -> StatxFlags -> (StatxFlags, StatxFlags) # toInteger :: StatxFlags -> Integer #
Real StatxFlags Source # |
Instance details Defined in System.Posix.Files.Common Methods toRational :: StatxFlags -> Rational #
Show StatxFlags Source # |
Instance details Defined in System.Posix.Files.Common Methods showsPrec :: Int -> StatxFlags -> ShowS # show :: StatxFlags -> String # showList :: [StatxFlags] -> ShowS #
Eq StatxFlags Source # |
Instance details Defined in System.Posix.Files.Common Methods (==) :: StatxFlags -> StatxFlags -> Bool # (/=) :: StatxFlags -> StatxFlags -> Bool #
Ord StatxFlags Source # |
Instance details Defined in System.Posix.Files.Common Methods compare :: StatxFlags -> StatxFlags -> Ordering # (<) :: StatxFlags -> StatxFlags -> Bool # (<=) :: StatxFlags -> StatxFlags -> Bool # (>) :: StatxFlags -> StatxFlags -> Bool # (>=) :: StatxFlags -> StatxFlags -> Bool # max :: StatxFlags -> StatxFlags -> StatxFlags # min :: StatxFlags -> StatxFlags -> StatxFlags #

defaultStatxFlags :: StatxFlags Source #

pattern EmptyPath :: StatxFlags Source #

If pathname to `getExtendedFileStatus` is an empty string, operate on the file referred to by the 'Maybe Fd' argument.

In this case, it can refer to any type of file, not just a directory.

pattern NoAutoMount :: StatxFlags Source #

Don't automount the terminal ("basename") component of pathname if it is a directory that is an automount point. This allows the caller to gather attributes of an automount point (rather than the location it would mount). This flag can be used in tools that scan directories to prevent mass-automounting of a directory of automount points. This flag has no effect if the mount point has already been mounted over.

pattern SymlinkNoFollow :: StatxFlags Source #

If pathname is a symbolic link, do not dereference it: instead return information about the link itself, like `lstat(2)`.

pattern SyncAsStat :: StatxFlags Source #

Do whatever `stat(2)` does. This is the default and is very much filesystem-specific.

pattern ForceSync :: StatxFlags Source #

Force the attributes to be synchronized with the server. This may require that a network filesystem perform a data writeback to get the timestamps correct.

pattern DontSync :: StatxFlags Source #

Don't synchronize anything, but rather just take whatever the system has cached if possible. This may mean that the information returned is approximate, but, on a network filesystem, it may not involve a round trip to the server - even if no lease is held.

## Mask

newtype StatxMask Source #

Mask argument to `statx`. It's used to tell the kernel which fields the caller is interested in.

See the pattern synonyms for possible masks. These are combined via `(<>)`. Masks can be tested via `(.&.)`.

Constructors

StatxMask CInt |

#### Instances

Instances details

Monoid StatxMask Source # |
Instance details Defined in System.Posix.Files.Common Methods mempty :: StatxMask # mappend :: StatxMask -> StatxMask -> StatxMask # mconcat :: [StatxMask] -> StatxMask #
Semigroup StatxMask Source # | ORs the masks.
Instance details Defined in System.Posix.Files.Common Methods (<>) :: StatxMask -> StatxMask -> StatxMask # sconcat :: NonEmpty StatxMask -> StatxMask # stimes :: Integral b => b -> StatxMask -> StatxMask #
Bits StatxMask Source # |
Instance details Defined in System.Posix.Files.Common Methods (.&.) :: StatxMask -> StatxMask -> StatxMask # (.|.) :: StatxMask -> StatxMask -> StatxMask # xor :: StatxMask -> StatxMask -> StatxMask # complement :: StatxMask -> StatxMask # shift :: StatxMask -> Int -> StatxMask # rotate :: StatxMask -> Int -> StatxMask # zeroBits :: StatxMask # bit :: Int -> StatxMask # setBit :: StatxMask -> Int -> StatxMask # clearBit :: StatxMask -> Int -> StatxMask # complementBit :: StatxMask -> Int -> StatxMask # testBit :: StatxMask -> Int -> Bool # bitSizeMaybe :: StatxMask -> Maybe Int # bitSize :: StatxMask -> Int # isSigned :: StatxMask -> Bool # shiftL :: StatxMask -> Int -> StatxMask # unsafeShiftL :: StatxMask -> Int -> StatxMask # shiftR :: StatxMask -> Int -> StatxMask # unsafeShiftR :: StatxMask -> Int -> StatxMask # rotateL :: StatxMask -> Int -> StatxMask # rotateR :: StatxMask -> Int -> StatxMask # popCount :: StatxMask -> Int #
Enum StatxMask Source # |
Instance details Defined in System.Posix.Files.Common Methods succ :: StatxMask -> StatxMask # pred :: StatxMask -> StatxMask # toEnum :: Int -> StatxMask # fromEnum :: StatxMask -> Int # enumFrom :: StatxMask -> [StatxMask] # enumFromThen :: StatxMask -> StatxMask -> [StatxMask] # enumFromTo :: StatxMask -> StatxMask -> [StatxMask] # enumFromThenTo :: StatxMask -> StatxMask -> StatxMask -> [StatxMask] #
Num StatxMask Source # |
Instance details Defined in System.Posix.Files.Common Methods (+) :: StatxMask -> StatxMask -> StatxMask # (-) :: StatxMask -> StatxMask -> StatxMask # (*) :: StatxMask -> StatxMask -> StatxMask # negate :: StatxMask -> StatxMask # abs :: StatxMask -> StatxMask # signum :: StatxMask -> StatxMask # fromInteger :: Integer -> StatxMask #
Read StatxMask Source # |
Instance details Defined in System.Posix.Files.Common Methods readsPrec :: Int -> ReadS StatxMask # readList :: ReadS [StatxMask] # readPrec :: ReadPrec StatxMask # readListPrec :: ReadPrec [StatxMask] #
Integral StatxMask Source # |
Instance details Defined in System.Posix.Files.Common Methods quot :: StatxMask -> StatxMask -> StatxMask # rem :: StatxMask -> StatxMask -> StatxMask # div :: StatxMask -> StatxMask -> StatxMask # mod :: StatxMask -> StatxMask -> StatxMask # quotRem :: StatxMask -> StatxMask -> (StatxMask, StatxMask) # divMod :: StatxMask -> StatxMask -> (StatxMask, StatxMask) # toInteger :: StatxMask -> Integer #
Real StatxMask Source # |
Instance details Defined in System.Posix.Files.Common Methods toRational :: StatxMask -> Rational #
Show StatxMask Source # |
Instance details Defined in System.Posix.Files.Common Methods showsPrec :: Int -> StatxMask -> ShowS # show :: StatxMask -> String # showList :: [StatxMask] -> ShowS #
Eq StatxMask Source # |
Instance details Defined in System.Posix.Files.Common Methods (==) :: StatxMask -> StatxMask -> Bool # (/=) :: StatxMask -> StatxMask -> Bool #
Ord StatxMask Source # |
Instance details Defined in System.Posix.Files.Common Methods compare :: StatxMask -> StatxMask -> Ordering # (<) :: StatxMask -> StatxMask -> Bool # (<=) :: StatxMask -> StatxMask -> Bool # (>) :: StatxMask -> StatxMask -> Bool # (>=) :: StatxMask -> StatxMask -> Bool # max :: StatxMask -> StatxMask -> StatxMask # min :: StatxMask -> StatxMask -> StatxMask #

defaultStatxMask :: StatxMask Source #

pattern StatxType :: StatxMask Source #

Want `stx_mode & S_IFMT`.

pattern StatxMode :: StatxMask Source #

Want `stx_mode & ~S_IFMT`.

pattern StatxNlink :: StatxMask Source #

Want `stx_nlink`.

pattern StatxUid :: StatxMask Source #

Want `stx_uid`.

pattern StatxGid :: StatxMask Source #

Want `stx_gid`.

pattern StatxAtime :: StatxMask Source #

Want `stx_atime`.

pattern StatxMtime :: StatxMask Source #

Want `stx_mtime`.

pattern StatxCtime :: StatxMask Source #

Want `stx_ctime`.

pattern StatxIno :: StatxMask Source #

Want `stx_ino`.

pattern StatxSize :: StatxMask Source #

Want `stx_size`.

pattern StatxBlocks :: StatxMask Source #

Want `stx_blocks`.

pattern StatxBasicStats :: StatxMask Source #

Want all of the above.

pattern StatxBtime :: StatxMask Source #

Want `stx_btime`.

pattern StatxMntId :: StatxMask Source #

Want `stx_mnt_id`.

pattern StatxAll :: StatxMask Source #

Want all currently available fields.

## Querying extended file status

fileBlockSizeX :: ExtendedFileStatus -> CBlkSize Source #

The "preferred" block size for efficient filesystem I/O. (Writing to a file in smaller chunks may cause an inefficient read-mod‐ify-rewrite.)

linkCountX :: ExtendedFileStatus -> CNlink Source #

The number of hard links on a file.

fileOwnerX :: ExtendedFileStatus -> UserID Source #

Te user ID of the owner of the file.

fileGroupX :: ExtendedFileStatus -> GroupID Source #

The ID of the group owner of the file.

fileModeX :: ExtendedFileStatus -> FileMode Source #

The file type and mode. See `inode(7)` for details.

fileIDX :: ExtendedFileStatus -> FileID Source #

The inode number of the file.

fileSizeX :: ExtendedFileStatus -> Word64 Source #

The size of the file (if it is a regular file or a symbolic link) in bytes. The size of a symbolic link is the length of the pathname it contains, without a terminating null byte.

fileBlocksX :: ExtendedFileStatus -> Word64 Source #

The number of blocks allocated to the file on the medium, in 512-byte units. (This may be smaller than stx_size/512 when the file has holes.)

accessTimeHiResX :: ExtendedFileStatus -> POSIXTime Source #

The file's last access timestamp.

creationTimeHiResX :: ExtendedFileStatus -> POSIXTime Source #

The file's creation timestamp.

statusChangeTimeHiResX :: ExtendedFileStatus -> POSIXTime Source #

The file's last status change timestamp.

modificationTimeHiResX :: ExtendedFileStatus -> POSIXTime Source #

The file's last modification timestamp.

deviceIDX :: ExtendedFileStatus -> DeviceID Source #

ID of the device on which this file resides.

specialDeviceIDX :: ExtendedFileStatus -> DeviceID Source #

Describes the device that this file represents.

mountIDX :: ExtendedFileStatus -> Word64 Source #

Warning: mountIDX: not available on this platform, will throw error (CPP guard: `#if HAVE_STATX_MNT_ID`)

The mount ID of the mount containing the file. This is the same number reported by name_to_handle_at(2) and corresponds to the number in the first field in one of the records in procself/mountinfo.

fileCompressedX :: ExtendedFileStatus -> Bool Source #

The file is compressed by the filesystem and may take extra resources to access. This is an extended attribute.

fileImmutableX :: ExtendedFileStatus -> Bool Source #

The file cannot be modified: it cannot be deleted or renamed, no hard links can be created to this file and no data can be written to it. See `chattr(1)`. This is an extended attribute.

fileAppendX :: ExtendedFileStatus -> Bool Source #

The file can only be opened in append mode for writing. Random access writing is not permitted. See `chattr(1)`. This is an extended attribute.

fileNoDumpX :: ExtendedFileStatus -> Bool Source #

File is not a candidate for backup when a backup program such as `dump(8)` is run. See `chattr(1)`. This is an extended attribute.

fileEncryptedX :: ExtendedFileStatus -> Bool Source #

A key is required for the file to be encrypted by the filesystem. This is an extended attribute.

fileVerityX :: ExtendedFileStatus -> Bool Source #

Warning: fileVerityX: not available on this platform, will default to `False` (CPP guard: `#if STATX_ATTR_VERITY`)

The file has fs-verity enabled. It cannot be written to, and all reads from it will be verified against a cryptographic hash that covers the entire file (e.g., via a Merkle tree). This is an extended attribute. Since Linux 5.5.

fileDaxX :: ExtendedFileStatus -> Bool Source #

Warning: fileDaxX: not available on this platform, will default to `False` (CPP guard: `#if STATX_ATTR_DAX`)

The file is in the DAX (cpu direct access) state. This is an extended attribute. Since Linux 5.8.

isBlockDeviceX :: ExtendedFileStatus -> Bool Source #

Checks if this file is a block device.

isCharacterDeviceX :: ExtendedFileStatus -> Bool Source #

Checks if this file is a character device.

isNamedPipeX :: ExtendedFileStatus -> Bool Source #

Checks if this file is a named pipe device.

isRegularFileX :: ExtendedFileStatus -> Bool Source #

Checks if this file is a regular file device.

isDirectoryX :: ExtendedFileStatus -> Bool Source #

Checks if this file is a directory device.

isSymbolicLinkX :: ExtendedFileStatus -> Bool Source #

Checks if this file is a symbolic link device.

isSocketX :: ExtendedFileStatus -> 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 name1 name2` creates a symbolic link named `name2` which points to the file `name1`.

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