From 328ac2d1ae8467285162a53b5a3ff94a1784a20b Mon Sep 17 00:00:00 2001 From: VegOwOtenks Date: Tue, 7 Oct 2025 15:06:30 +0200 Subject: [PATCH 01/12] Add Hint: getFileStatus and getSymbolicLinkStatus --- System/Posix/Files.hsc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/System/Posix/Files.hsc b/System/Posix/Files.hsc index 4243bc3..fc47ac2 100644 --- a/System/Posix/Files.hsc +++ b/System/Posix/Files.hsc @@ -245,6 +245,8 @@ access name flags = -- | @getFileStatus path@ calls gets the @FileStatus@ information (user ID, -- size, access times, etc.) for the file @path@. -- +-- This will dereference symbolic links, if you want to get the status of a link file, use 'getSymbolicLinkStatus' instead. +-- -- Note: calls @stat@. getFileStatus :: FilePath -> IO FileStatus getFileStatus path = do From 0b36bac054a7a96fc11295f9f7d0f16c7fc44d32 Mon Sep 17 00:00:00 2001 From: VegOwOtenks Date: Thu, 9 Oct 2025 10:19:04 +0200 Subject: [PATCH 02/12] Distribute the documentation of 'getFileStatus' --- System/Posix/Files/ByteString.hsc | 2 ++ System/Posix/Files/Common.hsc | 3 +++ System/Posix/Files/PosixString.hsc | 2 ++ 3 files changed, 7 insertions(+) diff --git a/System/Posix/Files/ByteString.hsc b/System/Posix/Files/ByteString.hsc index e9d22e4..08b1b01 100644 --- a/System/Posix/Files/ByteString.hsc +++ b/System/Posix/Files/ByteString.hsc @@ -240,6 +240,8 @@ access name flags = -- | @getFileStatus path@ calls gets the @FileStatus@ information (user ID, -- size, access times, etc.) for the file @path@. -- +-- This will dereference symbolic links, if you want to get the status of a link file, use 'getSymbolicLinkStatus' instead. +-- -- Note: calls @stat@. getFileStatus :: RawFilePath -> IO FileStatus getFileStatus path = do diff --git a/System/Posix/Files/Common.hsc b/System/Posix/Files/Common.hsc index 00ba5be..5c2593e 100644 --- a/System/Posix/Files/Common.hsc +++ b/System/Posix/Files/Common.hsc @@ -509,6 +509,9 @@ isSocket stat = -- | @getFdStatus fd@ acts as 'getFileStatus' but uses a file descriptor @fd@. -- +-- This will not dereference symbolic links by itself, but 'openFd' does so by default. +-- To learn more about this, see `man 7 symlink` section "Obtaining a file descriptor that refers to a symbolic link". +-- -- Note: calls @fstat@. getFdStatus :: Fd -> IO FileStatus getFdStatus (Fd fd) = do diff --git a/System/Posix/Files/PosixString.hsc b/System/Posix/Files/PosixString.hsc index 3466f83..2444896 100644 --- a/System/Posix/Files/PosixString.hsc +++ b/System/Posix/Files/PosixString.hsc @@ -239,6 +239,8 @@ access name flags = -- | @getFileStatus path@ calls gets the @FileStatus@ information (user ID, -- size, access times, etc.) for the file @path@. -- +-- This will dereference symbolic links, if you want to get the status of a link file, use 'getSymbolicLinkStatus' instead. +-- -- Note: calls @stat@. getFileStatus :: PosixPath -> IO FileStatus getFileStatus path = do From 5b0f63419d06de60b6df445e0f4b0c963ec31226 Mon Sep 17 00:00:00 2001 From: VegOwOtenks Date: Thu, 9 Oct 2025 10:25:20 +0200 Subject: [PATCH 03/12] Documentation about symbolic links and file-descriptors --- System/Posix/Files/Common.hsc | 4 ++-- System/Posix/IO.hsc | 4 ++++ System/Posix/IO/Common.hsc | 3 +++ 3 files changed, 9 insertions(+), 2 deletions(-) diff --git a/System/Posix/Files/Common.hsc b/System/Posix/Files/Common.hsc index 5c2593e..1e5bbe9 100644 --- a/System/Posix/Files/Common.hsc +++ b/System/Posix/Files/Common.hsc @@ -509,8 +509,8 @@ isSocket stat = -- | @getFdStatus fd@ acts as 'getFileStatus' but uses a file descriptor @fd@. -- --- This will not dereference symbolic links by itself, but 'openFd' does so by default. --- To learn more about this, see `man 7 symlink` section "Obtaining a file descriptor that refers to a symbolic link". +-- This will not dereference symbolic links by itself, but 'System.Posix.IO.openFd' may do so, depending on the flags passed. +-- To learn more about this, see `man 7 symlink` section "Obtaining a file descriptor that refers to a symbolic link" or the documentation of 'System.Posix.IO.openFd'. -- -- Note: calls @fstat@. getFdStatus :: Fd -> IO FileStatus diff --git a/System/Posix/IO.hsc b/System/Posix/IO.hsc index 810089e..4e695ad 100644 --- a/System/Posix/IO.hsc +++ b/System/Posix/IO.hsc @@ -77,6 +77,8 @@ import System.Posix.Internals ( withFilePath ) -- |Open and optionally create this file. See 'System.Posix.Files' -- for information on how to use the 'FileMode' type. +-- +-- It is currently not possible to obtain a file-descriptor to a symbolic link, they will always be dereferenced. See note in 'OpenFileFlags'. openFd :: FilePath -> OpenMode -> OpenFileFlags @@ -89,6 +91,8 @@ openFd = openFdAt Nothing -- navigating changing directory trees, or to retain access to a portion of the -- directory tree that would otherwise become inaccessible after dropping -- privileges. +-- +-- It is currently not possible to obtain a file-descriptor to a symbolic link, they will always be dereferenced. See note in 'OpenFileFlags'. openFdAt :: Maybe Fd -- ^ Optional directory file descriptor -> FilePath -- ^ Pathname to open -> OpenMode -- ^ Read-only, read-write or write-only diff --git a/System/Posix/IO/Common.hsc b/System/Posix/IO/Common.hsc index 63e59c8..c18f7da 100644 --- a/System/Posix/IO/Common.hsc +++ b/System/Posix/IO/Common.hsc @@ -159,6 +159,9 @@ data OpenMode = ReadOnly | WriteOnly | ReadWrite deriving (Read, Show, Eq, Ord) -- |Correspond to some of the int flags from C's fcntl.h. +-- +-- Using a combination of O_PATH and O_NOFOLLOW it would be possible to open an file-descriptor referring directly to a symbolic link, but this is currently not possible. +-- Fore more details, see `man 7 symlink` section "Obtaining a file descriptor that refers to a symbolic link". data OpenFileFlags = OpenFileFlags { append :: Bool, -- ^ O_APPEND From f471d63354871562c7e3509acdae577a5fe449e8 Mon Sep 17 00:00:00 2001 From: VegOwOtenks Date: Thu, 9 Oct 2025 10:30:49 +0200 Subject: [PATCH 04/12] Fix the haddock markup --- System/Posix/Files/Common.hsc | 2 +- System/Posix/IO/Common.hsc | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/System/Posix/Files/Common.hsc b/System/Posix/Files/Common.hsc index 1e5bbe9..2eb752b 100644 --- a/System/Posix/Files/Common.hsc +++ b/System/Posix/Files/Common.hsc @@ -510,7 +510,7 @@ isSocket stat = -- | @getFdStatus fd@ acts as 'getFileStatus' but uses a file descriptor @fd@. -- -- This will not dereference symbolic links by itself, but 'System.Posix.IO.openFd' may do so, depending on the flags passed. --- To learn more about this, see `man 7 symlink` section "Obtaining a file descriptor that refers to a symbolic link" or the documentation of 'System.Posix.IO.openFd'. +-- To learn more about this, see @man 7 symlink@ section "Obtaining a file descriptor that refers to a symbolic link" or the documentation of 'System.Posix.IO.openFd'. -- -- Note: calls @fstat@. getFdStatus :: Fd -> IO FileStatus diff --git a/System/Posix/IO/Common.hsc b/System/Posix/IO/Common.hsc index c18f7da..8914b0a 100644 --- a/System/Posix/IO/Common.hsc +++ b/System/Posix/IO/Common.hsc @@ -160,8 +160,8 @@ data OpenMode = ReadOnly | WriteOnly | ReadWrite -- |Correspond to some of the int flags from C's fcntl.h. -- --- Using a combination of O_PATH and O_NOFOLLOW it would be possible to open an file-descriptor referring directly to a symbolic link, but this is currently not possible. --- Fore more details, see `man 7 symlink` section "Obtaining a file descriptor that refers to a symbolic link". +-- Using a combination of O_PATH and O_NOFOLLOW it would be possible to open an file-descriptor referring directly to a symbolic link, but this is currently not implemented. +-- Fore more details, see @man 7 symlink@ section "Obtaining a file descriptor that refers to a symbolic link". data OpenFileFlags = OpenFileFlags { append :: Bool, -- ^ O_APPEND From 15b080c46e51f774852ce44898bafc5edfacae9b Mon Sep 17 00:00:00 2001 From: VegOwOtenks <90334612+Hyalunar@users.noreply.github.com> Date: Tue, 14 Oct 2025 12:19:10 +0200 Subject: [PATCH 05/12] Enhance Documentation Wording Co-authored-by: Viktor Dukhovni --- System/Posix/Files.hsc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/System/Posix/Files.hsc b/System/Posix/Files.hsc index fc47ac2..5310e92 100644 --- a/System/Posix/Files.hsc +++ b/System/Posix/Files.hsc @@ -242,7 +242,7 @@ access name flags = else throwErrnoPath "fileAccess" name --- | @getFileStatus path@ calls gets the @FileStatus@ information (user ID, +-- | @getFileStatus path@ retrieves the @FileStatus@ information (user ID, -- size, access times, etc.) for the file @path@. -- -- This will dereference symbolic links, if you want to get the status of a link file, use 'getSymbolicLinkStatus' instead. From d7111218ebf9360172be53cb76fd0fc852fc7c69 Mon Sep 17 00:00:00 2001 From: VegOwOtenks Date: Tue, 14 Oct 2025 12:25:02 +0200 Subject: [PATCH 06/12] Remove a linux-specific hint --- System/Posix/IO/Common.hsc | 3 --- 1 file changed, 3 deletions(-) diff --git a/System/Posix/IO/Common.hsc b/System/Posix/IO/Common.hsc index 8914b0a..63e59c8 100644 --- a/System/Posix/IO/Common.hsc +++ b/System/Posix/IO/Common.hsc @@ -159,9 +159,6 @@ data OpenMode = ReadOnly | WriteOnly | ReadWrite deriving (Read, Show, Eq, Ord) -- |Correspond to some of the int flags from C's fcntl.h. --- --- Using a combination of O_PATH and O_NOFOLLOW it would be possible to open an file-descriptor referring directly to a symbolic link, but this is currently not implemented. --- Fore more details, see @man 7 symlink@ section "Obtaining a file descriptor that refers to a symbolic link". data OpenFileFlags = OpenFileFlags { append :: Bool, -- ^ O_APPEND From 080473709ba4f6beeddd566af1d657c6cb4d8751 Mon Sep 17 00:00:00 2001 From: VegOwOtenks Date: Tue, 14 Oct 2025 12:26:20 +0200 Subject: [PATCH 07/12] Remove a platform-specific hint --- System/Posix/IO.hsc | 2 -- 1 file changed, 2 deletions(-) diff --git a/System/Posix/IO.hsc b/System/Posix/IO.hsc index 4e695ad..1a95fa1 100644 --- a/System/Posix/IO.hsc +++ b/System/Posix/IO.hsc @@ -77,8 +77,6 @@ import System.Posix.Internals ( withFilePath ) -- |Open and optionally create this file. See 'System.Posix.Files' -- for information on how to use the 'FileMode' type. --- --- It is currently not possible to obtain a file-descriptor to a symbolic link, they will always be dereferenced. See note in 'OpenFileFlags'. openFd :: FilePath -> OpenMode -> OpenFileFlags From e2deaa5cff39a18f6f6ce48aa38ab3e3e669ab8a Mon Sep 17 00:00:00 2001 From: VegOwOtenks Date: Tue, 14 Oct 2025 12:29:11 +0200 Subject: [PATCH 08/12] Uniform comments among string APIs --- System/Posix/Files/ByteString.hsc | 3 ++- System/Posix/Files/PosixString.hsc | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/System/Posix/Files/ByteString.hsc b/System/Posix/Files/ByteString.hsc index 08b1b01..8d3704e 100644 --- a/System/Posix/Files/ByteString.hsc +++ b/System/Posix/Files/ByteString.hsc @@ -240,7 +240,8 @@ access name flags = -- | @getFileStatus path@ calls gets the @FileStatus@ information (user ID, -- size, access times, etc.) for the file @path@. -- --- This will dereference symbolic links, if you want to get the status of a link file, use 'getSymbolicLinkStatus' instead. +-- 'getFileStatus' dereferences symbolic links, to retrieve the status of a symlink, +-- use 'getSymbolicLinkStatus' instead. -- -- Note: calls @stat@. getFileStatus :: RawFilePath -> IO FileStatus diff --git a/System/Posix/Files/PosixString.hsc b/System/Posix/Files/PosixString.hsc index 2444896..6aff131 100644 --- a/System/Posix/Files/PosixString.hsc +++ b/System/Posix/Files/PosixString.hsc @@ -239,7 +239,8 @@ access name flags = -- | @getFileStatus path@ calls gets the @FileStatus@ information (user ID, -- size, access times, etc.) for the file @path@. -- --- This will dereference symbolic links, if you want to get the status of a link file, use 'getSymbolicLinkStatus' instead. +-- 'getFileStatus' dereferences symbolic links, to retrieve the status of a symlink, +-- use 'getSymbolicLinkStatus' instead. -- -- Note: calls @stat@. getFileStatus :: PosixPath -> IO FileStatus From 6267f0ee84ea6534d4e7485b5eb007e7fbddda7b Mon Sep 17 00:00:00 2001 From: VegOwOtenks <90334612+Hyalunar@users.noreply.github.com> Date: Tue, 14 Oct 2025 12:30:11 +0200 Subject: [PATCH 09/12] Remove platform-specific hint Co-authored-by: Viktor Dukhovni --- System/Posix/IO.hsc | 2 -- 1 file changed, 2 deletions(-) diff --git a/System/Posix/IO.hsc b/System/Posix/IO.hsc index 1a95fa1..810089e 100644 --- a/System/Posix/IO.hsc +++ b/System/Posix/IO.hsc @@ -89,8 +89,6 @@ openFd = openFdAt Nothing -- navigating changing directory trees, or to retain access to a portion of the -- directory tree that would otherwise become inaccessible after dropping -- privileges. --- --- It is currently not possible to obtain a file-descriptor to a symbolic link, they will always be dereferenced. See note in 'OpenFileFlags'. openFdAt :: Maybe Fd -- ^ Optional directory file descriptor -> FilePath -- ^ Pathname to open -> OpenMode -- ^ Read-only, read-write or write-only From 66a698ba20ddc08f0de5c3d2b5e59bf062fe9f23 Mon Sep 17 00:00:00 2001 From: VegOwOtenks <90334612+Hyalunar@users.noreply.github.com> Date: Tue, 14 Oct 2025 12:30:56 +0200 Subject: [PATCH 10/12] Undo platform-specific hint and man-page reference Co-authored-by: Viktor Dukhovni --- System/Posix/Files/Common.hsc | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/System/Posix/Files/Common.hsc b/System/Posix/Files/Common.hsc index 2eb752b..f73b03f 100644 --- a/System/Posix/Files/Common.hsc +++ b/System/Posix/Files/Common.hsc @@ -507,10 +507,8 @@ isSymbolicLink stat = isSocket stat = (fileMode stat `intersectFileModes` fileTypeModes) == socketMode --- | @getFdStatus fd@ acts as 'getFileStatus' but uses a file descriptor @fd@. --- --- This will not dereference symbolic links by itself, but 'System.Posix.IO.openFd' may do so, depending on the flags passed. --- To learn more about this, see @man 7 symlink@ section "Obtaining a file descriptor that refers to a symbolic link" or the documentation of 'System.Posix.IO.openFd'. +-- | @getFdStatus fd@ is similar to 'getFileStatus', but returns data about +-- the file associated with the descriptor @fd@. -- -- Note: calls @fstat@. getFdStatus :: Fd -> IO FileStatus From 4efee15a13a692923bc4e026520744a65463a728 Mon Sep 17 00:00:00 2001 From: VegOwOtenks Date: Tue, 14 Oct 2025 12:40:52 +0200 Subject: [PATCH 11/12] Sync the different documentations --- System/Posix/Files.hsc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/System/Posix/Files.hsc b/System/Posix/Files.hsc index 5310e92..e74b664 100644 --- a/System/Posix/Files.hsc +++ b/System/Posix/Files.hsc @@ -245,7 +245,8 @@ access name flags = -- | @getFileStatus path@ retrieves the @FileStatus@ information (user ID, -- size, access times, etc.) for the file @path@. -- --- This will dereference symbolic links, if you want to get the status of a link file, use 'getSymbolicLinkStatus' instead. +-- 'getFileStatus' dereferences symbolic links, to retrieve the status of a symlink, +-- use 'getSymbolicLinkStatus' instead. -- -- Note: calls @stat@. getFileStatus :: FilePath -> IO FileStatus From 2e8227357c3942dd1b9b6000bebf9367553edfcf Mon Sep 17 00:00:00 2001 From: VegOwOtenks Date: Wed, 29 Oct 2025 15:58:52 +0100 Subject: [PATCH 12/12] Remove the confusig comma at the end of the line --- System/Posix/Files.hsc | 2 +- System/Posix/Files/ByteString.hsc | 2 +- System/Posix/Files/PosixString.hsc | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/System/Posix/Files.hsc b/System/Posix/Files.hsc index e74b664..6750d55 100644 --- a/System/Posix/Files.hsc +++ b/System/Posix/Files.hsc @@ -245,7 +245,7 @@ access name flags = -- | @getFileStatus path@ retrieves the @FileStatus@ information (user ID, -- size, access times, etc.) for the file @path@. -- --- 'getFileStatus' dereferences symbolic links, to retrieve the status of a symlink, +-- 'getFileStatus' dereferences symbolic links, to retrieve the status of a symlink -- use 'getSymbolicLinkStatus' instead. -- -- Note: calls @stat@. diff --git a/System/Posix/Files/ByteString.hsc b/System/Posix/Files/ByteString.hsc index 8d3704e..656f757 100644 --- a/System/Posix/Files/ByteString.hsc +++ b/System/Posix/Files/ByteString.hsc @@ -240,7 +240,7 @@ access name flags = -- | @getFileStatus path@ calls gets the @FileStatus@ information (user ID, -- size, access times, etc.) for the file @path@. -- --- 'getFileStatus' dereferences symbolic links, to retrieve the status of a symlink, +-- 'getFileStatus' dereferences symbolic links, to retrieve the status of a symlink -- use 'getSymbolicLinkStatus' instead. -- -- Note: calls @stat@. diff --git a/System/Posix/Files/PosixString.hsc b/System/Posix/Files/PosixString.hsc index 6aff131..a97e2ee 100644 --- a/System/Posix/Files/PosixString.hsc +++ b/System/Posix/Files/PosixString.hsc @@ -239,7 +239,7 @@ access name flags = -- | @getFileStatus path@ calls gets the @FileStatus@ information (user ID, -- size, access times, etc.) for the file @path@. -- --- 'getFileStatus' dereferences symbolic links, to retrieve the status of a symlink, +-- 'getFileStatus' dereferences symbolic links, to retrieve the status of a symlink -- use 'getSymbolicLinkStatus' instead. -- -- Note: calls @stat@.