Add Hint: getFileStatus and getSymbolicLinkStatus

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

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

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 '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
 getFdStatus (Fd fd) = do

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

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

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