HORIZON HASKELLDocslts/ghc-9.10.xc74966e2026-09-27Search names, modules, packages, or :: a typeCtrl K

GHC 9.10.3 · lts/ghc-9.10.x · c74966e · 2026-09-27

Moduleunix-2.8.7.0Haskell2010

System.Posix.Files

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.

  • 6 types
  • 112 values
  • Packageunix-2.8.7.0
  • Exports139
  • LanguageHaskell2010
  • LicenceBSD-3-Clause
  • SourceFiles.hsc

File modes

27 declarations

Setting file modes

valuesetFileMode :: 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.

valuesetFdMode :: Fd -> FileMode -> IO ()
#

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

Note: calls fchmod.

valuesetFileCreationMask :: 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

valuefileAccess :: 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.

File status

1 declaration
newtypenewtype 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.

Limitations: Support for high resolution timestamps is filesystem dependent:

  • HFS+ volumes on OS X only support whole-second times.

Constructors

Obtaining file status

valuegetFileStatus :: FilePath -> IO FileStatus
#

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

Note: calls stat.

valuegetFdStatus :: Fd -> IO FileStatus
#

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

Note: calls fstat.

Querying file status

valuefileSize :: 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.

valuestatusChangeTimeHiRes :: FileStatus -> POSIXTime
#

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.

valuefileBlockSize :: FileStatus -> Maybe CBlkSize
#

Gives the preferred block size for efficient filesystem I/O in bytes. Returns Nothing if st_blocksize is not supported on this platform.

valuefileBlocks :: FileStatus -> Maybe CBlkCnt
#

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

3 declarations
newtypenewtype CAttributes
#

Constructors

Instances7Eq, Num, Ord, Read, Show, Bits, …
valuehaveStatx :: Bool
#

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

Obtaining extended file status

valuegetExtendedFileStatus
  1. :: Maybe Fd

    Optional directory file descriptor (dirfd)

  2. -> FilePath

    pathname to open

  3. -> StatxFlags

    flags

  4. -> StatxMask

    mask

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

newtypenewtype StatxFlags
#

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:

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

Constructors

Instances11Enum, Eq, Integral, Num, Ord, Read, …
patternpattern EmptyPath :: StatxFlags
#

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.

patternpattern NoAutoMount :: StatxFlags
#

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.

patternpattern SymlinkNoFollow :: StatxFlags
#

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

patternpattern SyncAsStat :: StatxFlags
#

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

patternpattern ForceSync :: StatxFlags
#

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.

patternpattern DontSync :: StatxFlags
#

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

newtypenewtype StatxMask
#

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

Instances11Enum, Eq, Integral, Num, Ord, Read, …

Querying extended file status

valuefileSizeX :: ExtendedFileStatus -> Word64
#

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.

valuefileBlocksX :: ExtendedFileStatus -> Word64
#

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

valuemountIDX :: ExtendedFileStatus -> Word64
#

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.

valuefileImmutableX :: ExtendedFileStatus -> Bool
#

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.

valuefileAppendX :: ExtendedFileStatus -> Bool
#

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.

valuefileNoDumpX :: ExtendedFileStatus -> Bool
#

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.

valuefileVerityX :: ExtendedFileStatus -> Bool
#

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.

Creation

2 declarations
valuecreateNamedPipe :: 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.

Hard links

2 declarations

Symbolic links

2 declarations

Renaming files

1 declaration
valuerename :: FilePath -> FilePath -> IO ()
#

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

Note: calls rename.

Changing file ownership

3 declarations
valuesetOwnerAndGroup :: 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.

Changing file timestamps

7 declarations
valuesetFileTimes :: 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.

valuesetFileTimesHiRes :: FilePath -> POSIXTime -> POSIXTime -> IO ()
#

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.

valuesetFdTimesHiRes :: Fd -> POSIXTime -> POSIXTime -> IO ()
#

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.

valuesetSymbolicLinkTimesHiRes :: FilePath -> POSIXTime -> POSIXTime -> IO ()
#

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.

valuetouchFile :: FilePath -> IO ()
#

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

Note: calls utime.

valuetouchFd :: Fd -> IO ()
#

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.

Setting file sizes

2 declarations
valuesetFileSize :: 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.

Find system-specific limits for a file

3 declarations
valuegetPathVar :: 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.

valuegetFdPathVar :: 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.