ghc/lib/std/Directory.lhs

   1 %
   2 % (c) The AQUA Project, Glasgow University, 1994-1997
   3 %
   4 \section[Directory]{Directory interface}
   5
   6 A directory contains a series of entries, each of which is a named
   7 reference to a file system object (file, directory etc.).  Some
   8 entries may be hidden, inaccessible, or have some administrative
   9 function (e.g. "." or ".." under POSIX), but in this standard all such
  10 entries are considered to form part of the directory contents.
  11 Entries in sub-directories are not, however, considered to form part
  12 of the directory contents.
  13
  14 Each file system object is referenced by a {\em path}.  There is
  15 normally at least one absolute path to each file system object.  In
  16 some operating systems, it may also be possible to have paths which
  17 are relative to the current directory.
  18
  19 \begin{code}
  20 {-# OPTIONS -#include <sys/stat.h> -#include <dirent.h> #-}
  21 module Directory
  22    (
  23     Permissions(Permissions),
  24
  25     createDirectory,
  26     removeDirectory,
  27     renameDirectory,
  28     getDirectoryContents,
  29     getCurrentDirectory,
  30     setCurrentDirectory,
  31
  32     removeFile,
  33     renameFile,
  34
  35     doesFileExist,
  36     doesDirectoryExist,
  37     getPermissions,
  38     setPermissions,
  39     getModificationTime
  40    ) where
  41
  42 import PrelBase
  43 import PrelIOBase
  44 import PrelST
  45 import PrelUnsafe       ( unsafePerformIO )
  46 import PrelArr
  47 import PrelPack         ( unpackNBytesST )
  48 import PrelForeign      ( Word(..) )
  49 import PrelAddr
  50 import Time             ( ClockTime(..) )
  51
  52 \end{code}
  53
  54 %*********************************************************
  55 %*                                                      *
  56 \subsection{Signatures}
  57 %*                                                      *
  58 %*********************************************************
  59
  60 \begin{code}
  61 createDirectory         :: FilePath -> IO ()
  62 removeDirectory         :: FilePath -> IO ()
  63 removeFile              :: FilePath -> IO ()
  64 renameDirectory         :: FilePath -> FilePath -> IO ()
  65 renameFile              :: FilePath -> FilePath -> IO ()
  66 getDirectoryContents    :: FilePath -> IO [FilePath]
  67 getCurrentDirectory     :: IO FilePath
  68 setCurrentDirectory     :: FilePath -> IO ()
  69 doesFileExist           :: FilePath -> IO Bool
  70 doesDirectoryExist      :: FilePath -> IO Bool
  71 getPermissions          :: FilePath -> IO Permissions
  72 setPermissions          :: FilePath -> Permissions -> IO ()
  73 getModificationTime     :: FilePath -> IO ClockTime
  74 \end{code}
  75
  76
  77 %*********************************************************
  78 %*                                                      *
  79 \subsection{Permissions}
  80 %*                                                      *
  81 %*********************************************************
  82
  83 The @Permissions@ type is used to record whether certain
  84 operations are permissible on a file/directory:
  85 [to whom? - owner/group/world - the Report don't say much]
  86
  87 \begin{code}
  88 data Permissions
  89  = Permissions {
  90     readable,   writeable,
  91     executable, searchable :: Bool
  92    } deriving (Eq, Ord, Read, Show)
  93 \end{code}
  94
  95 %*********************************************************
  96 %*                                                      *
  97 \subsection{Implementation}
  98 %*                                                      *
  99 %*********************************************************
 100
 101 @createDirectory dir@ creates a new directory {\em dir} which is
 102 initially empty, or as near to empty as the operating system
 103 allows.
 104
 105 The operation may fail with:
 106
 107 \begin{itemize}
 108 \item @isPermissionError@ / @PermissionDenied@
 109 The process has insufficient privileges to perform the operation.
 110 @[EROFS, EACCES]@
 111 \item @isAlreadyExistsError@ / @AlreadyExists@
 112 The operand refers to a directory that already exists.
 113 @ [EEXIST]@
 114 \item @HardwareFault@
 115 A physical I/O error has occurred.
 116 @ [EIO]@
 117 \item @InvalidArgument@
 118 The operand is not a valid directory name.
 119 @[ENAMETOOLONG, ELOOP]@
 120 \item @NoSuchThing@
 121 There is no path to the directory.
 122 @[ENOENT, ENOTDIR]@
 123 \item @ResourceExhausted@
 124 Insufficient resources (virtual memory, process file descriptors,
 125 physical disk space, etc.) are available to perform the operation.
 126 @[EDQUOT, ENOSPC, ENOMEM, EMLINK]@
 127 \item @InappropriateType@
 128 The path refers to an existing non-directory object.
 129 @[EEXIST]@
 130 \end{itemize}
 131
 132 \begin{code}
 133 createDirectory path = do
 134     rc <- _ccall_ createDirectory path
 135     if rc == 0 then return () else
 136         constructErrorAndFail "createDirectory"
 137 \end{code}
 138
 139 @removeDirectory dir@ removes an existing directory {\em dir}.  The
 140 implementation may specify additional constraints which must be
 141 satisfied before a directory can be removed (e.g. the directory has to
 142 be empty, or may not be in use by other processes).  It is not legal
 143 for an implementation to partially remove a directory unless the
 144 entire directory is removed. A conformant implementation need not
 145 support directory removal in all situations (e.g. removal of the root
 146 directory).
 147
 148 The operation may fail with:
 149 \begin{itemize}
 150 \item @HardwareFault@
 151 A physical I/O error has occurred.
 152 [@EIO@]
 153 \item @InvalidArgument@
 154 The operand is not a valid directory name.
 155 @[ENAMETOOLONG, ELOOP]@
 156 \item @isDoesNotExist@ / @NoSuchThing@
 157 The directory does not exist.
 158 @[ENOENT, ENOTDIR]@
 159 \item @isPermissionError@ / @PermissionDenied@
 160 The process has insufficient privileges to perform the operation.
 161 @[EROFS, EACCES, EPERM]@
 162 \item @UnsatisfiedConstraints@
 163 Implementation-dependent constraints are not satisfied.
 164 @[EBUSY, ENOTEMPTY, EEXIST]@
 165 \item @UnsupportedOperation@
 166 The implementation does not support removal in this situation.
 167 @[EINVAL]@
 168 \item @InappropriateType@
 169 The operand refers to an existing non-directory object.
 170 @[ENOTDIR]@
 171 \end{itemize}
 172
 173 \begin{code}
 174 removeDirectory path = do
 175     rc <- _ccall_ removeDirectory path
 176     if rc == 0 then
 177         return ()
 178      else
 179         constructErrorAndFail "removeDirectory"
 180 \end{code}
 181
 182 @removeFile file@ removes the directory entry for an existing file
 183 {\em file}, where {\em file} is not itself a directory. The
 184 implementation may specify additional constraints which must be
 185 satisfied before a file can be removed (e.g. the file may not be in
 186 use by other processes).
 187
 188 The operation may fail with:
 189 \begin{itemize}
 190 \item @HardwareFault@
 191 A physical I/O error has occurred.
 192 @[EIO]@
 193 \item @InvalidArgument@
 194 The operand is not a valid file name.
 195 @[ENAMETOOLONG, ELOOP]@
 196 \item @isDoesNotExist@ / @NoSuchThing@
 197 The file does not exist.
 198 @[ENOENT, ENOTDIR]@
 199 \item @isPermissionError@ / @PermissionDenied@
 200 The process has insufficient privileges to perform the operation.
 201 @[EROFS, EACCES, EPERM]@
 202 \item @UnsatisfiedConstraints@
 203 Implementation-dependent constraints are not satisfied.
 204 @[EBUSY]@
 205 \item @InappropriateType@
 206 The operand refers to an existing directory.
 207 @[EPERM, EINVAL]@
 208 \end{itemize}
 209
 210 \begin{code}
 211 removeFile path = do
 212     rc <- _ccall_ removeFile path
 213     if rc == 0 then
 214         return ()
 215      else
 216         constructErrorAndFail "removeFile"
 217 \end{code}
 218
 219 @renameDirectory old@ {\em new} changes the name of an existing
 220 directory from {\em old} to {\em new}.  If the {\em new} directory
 221 already exists, it is atomically replaced by the {\em old} directory.
 222 If the {\em new} directory is neither the {\em old} directory nor an
 223 alias of the {\em old} directory, it is removed as if by
 224 $removeDirectory$.  A conformant implementation need not support
 225 renaming directories in all situations (e.g. renaming to an existing
 226 directory, or across different physical devices), but the constraints
 227 must be documented.
 228
 229 The operation may fail with:
 230 \begin{itemize}
 231 \item @HardwareFault@
 232 A physical I/O error has occurred.
 233 @[EIO]@
 234 \item @InvalidArgument@
 235 Either operand is not a valid directory name.
 236 @[ENAMETOOLONG, ELOOP]@
 237 \item @isDoesNotExistError@ / @NoSuchThing@
 238 The original directory does not exist, or there is no path to the target.
 239 @[ENOENT, ENOTDIR]@
 240 \item @isPermissionError@ / @PermissionDenied@
 241 The process has insufficient privileges to perform the operation.
 242 @[EROFS, EACCES, EPERM]@
 243 \item @ResourceExhausted@
 244 Insufficient resources are available to perform the operation.
 245 @[EDQUOT, ENOSPC, ENOMEM, EMLINK]@
 246 \item @UnsatisfiedConstraints@
 247 Implementation-dependent constraints are not satisfied.
 248 @[EBUSY, ENOTEMPTY, EEXIST]@
 249 \item @UnsupportedOperation@
 250 The implementation does not support renaming in this situation.
 251 @[EINVAL, EXDEV]@
 252 \item @InappropriateType@
 253 Either path refers to an existing non-directory object.
 254 @[ENOTDIR, EISDIR]@
 255 \end{itemize}
 256
 257 \begin{code}
 258 renameDirectory opath npath = do
 259     rc <- _ccall_ renameDirectory opath npath
 260     if rc == 0 then
 261         return ()
 262      else
 263         constructErrorAndFail "renameDirectory"
 264 \end{code}
 265
 266 @renameFile old@ {\em new} changes the name of an existing file system
 267 object from {\em old} to {\em new}.  If the {\em new} object already
 268 exists, it is atomically replaced by the {\em old} object.  Neither
 269 path may refer to an existing directory.  A conformant implementation
 270 need not support renaming files in all situations (e.g. renaming
 271 across different physical devices), but the constraints must be
 272 documented.
 273
 274 The operation may fail with:
 275 \begin{itemize}
 276 \item @HardwareFault@
 277 A physical I/O error has occurred.
 278 @[EIO]@
 279 \item @InvalidArgument@
 280 Either operand is not a valid file name.
 281 @[ENAMETOOLONG, ELOOP]@
 282 \item @isDoesNotExistError@ / @NoSuchThing@
 283 The original file does not exist, or there is no path to the target.
 284 @[ENOENT, ENOTDIR]@
 285 \item @isPermissionError@ / @PermissionDenied@
 286 The process has insufficient privileges to perform the operation.
 287 @[EROFS, EACCES, EPERM]@
 288 \item @ResourceExhausted@
 289 Insufficient resources are available to perform the operation.
 290 @[EDQUOT, ENOSPC, ENOMEM, EMLINK]@
 291 \item @UnsatisfiedConstraints@
 292 Implementation-dependent constraints are not satisfied.
 293 @[EBUSY]@
 294 \item @UnsupportedOperation@
 295 The implementation does not support renaming in this situation.
 296 @[EXDEV]@
 297 \item @InappropriateType@
 298 Either path refers to an existing directory.
 299 @[ENOTDIR, EISDIR, EINVAL, EEXIST, ENOTEMPTY]@
 300 \end{itemize}
 301
 302 \begin{code}
 303 renameFile opath npath = do
 304     rc <- _ccall_ renameFile opath npath
 305     if rc == 0 then
 306         return ()
 307      else
 308         constructErrorAndFail   "renameFile"
 309 \end{code}
 310
 311 @getDirectoryContents dir@ returns a list of {\em all} entries
 312 in {\em dir}.
 313
 314 The operation may fail with:
 315 \begin{itemize}
 316 \item @HardwareFault@
 317 A physical I/O error has occurred.
 318 @[EIO]@
 319 \item @InvalidArgument@
 320 The operand is not a valid directory name.
 321 @[ENAMETOOLONG, ELOOP]@
 322 \item @isDoesNotExistError@ / @NoSuchThing@
 323 The directory does not exist.
 324 @[ENOENT, ENOTDIR]@
 325 \item @isPermissionError@ / @PermissionDenied@
 326 The process has insufficient privileges to perform the operation.
 327 @[EACCES]@
 328 \item @ResourceExhausted@
 329 Insufficient resources are available to perform the operation.
 330 @[EMFILE, ENFILE]@
 331 \item @InappropriateType@
 332 The path refers to an existing non-directory object.
 333 @[ENOTDIR]@
 334 \end{itemize}
 335
 336 \begin{code}
 337 --getDirectoryContents :: FilePath -> IO [FilePath]
 338 getDirectoryContents path = do
 339     dir <- _ccall_ openDir__ path
 340     if dir == ``NULL''
 341         then constructErrorAndFail "getDirectoryContents"
 342         else loop dir
 343   where
 344     loop :: Addr -> IO [String]
 345     loop dir  = do
 346       dirent_ptr <- _ccall_ readDir__ dir
 347       if (dirent_ptr::Addr) == ``NULL''
 348        then do
 349           return []
 350        else do
 351           str     <- _casm_ `` %r=(char*)((struct dirent*)%0)->d_name; '' dirent_ptr
 352             -- not using the unpackCString function here, since we have to force
 353             -- the unmarshalling of the directory entry right here as subsequent
 354             -- calls to readdir() may overwrite it.
 355           len     <- _ccall_ strlen str
 356           entry   <- stToIO (unpackNBytesST str len)
 357           entries <- loop dir
 358           return (entry:entries)
 359 \end{code}
 360
 361 If the operating system has a notion of current directories,
 362 @getCurrentDirectory@ returns an absolute path to the
 363 current directory of the calling process.
 364
 365 The operation may fail with:
 366 \begin{itemize}
 367 \item @HardwareFault@
 368 A physical I/O error has occurred.
 369 @[EIO]@
 370 \item @isDoesNotExistError@ / @NoSuchThing@
 371 There is no path referring to the current directory.
 372 @[EPERM, ENOENT, ESTALE...]@
 373 \item @isPermissionError@ / @PermissionDenied@
 374 The process has insufficient privileges to perform the operation.
 375 @[EACCES]@
 376 \item @ResourceExhausted@
 377 Insufficient resources are available to perform the operation.
 378 \item @UnsupportedOperation@
 379 The operating system has no notion of current directory.
 380 \end{itemize}
 381
 382 \begin{code}
 383 getCurrentDirectory = do
 384     str <- _ccall_ getCurrentDirectory
 385     if str /= ``NULL''
 386         then do
 387             len <- _ccall_ strlen str
 388             pwd <- stToIO (unpackNBytesST str len)
 389             _ccall_ free str
 390             return pwd
 391         else
 392             constructErrorAndFail "getCurrentDirectory"
 393 \end{code}
 394
 395 If the operating system has a notion of current directories,
 396 @setCurrentDirectory dir@ changes the current
 397 directory of the calling process to {\em dir}.
 398
 399 The operation may fail with:
 400 \begin{itemize}
 401 \item @HardwareFault@
 402 A physical I/O error has occurred.
 403 @[EIO]@
 404 \item @InvalidArgument@
 405 The operand is not a valid directory name.
 406 @[ENAMETOOLONG, ELOOP]@
 407 \item @isDoesNotExistError@ / @NoSuchThing@
 408 The directory does not exist.
 409 @[ENOENT, ENOTDIR]@
 410 \item @isPermissionError@ / @PermissionDenied@
 411 The process has insufficient privileges to perform the operation.
 412 @[EACCES]@
 413 \item @UnsupportedOperation@
 414 The operating system has no notion of current directory, or the
 415 current directory cannot be dynamically changed.
 416 \item @InappropriateType@
 417 The path refers to an existing non-directory object.
 418 @[ENOTDIR]@
 419 \end{itemize}
 420
 421 \begin{code}
 422 setCurrentDirectory path = do
 423     rc <- _ccall_ setCurrentDirectory path
 424     if rc == 0
 425         then return ()
 426         else constructErrorAndFail "setCurrentDirectory"
 427 \end{code}
 428
 429
 430 \begin{code}
 431 --doesFileExist :: FilePath -> IO Bool
 432 doesFileExist name = do
 433   rc <- _ccall_ access name (``F_OK''::Int)
 434   return (rc == 0)
 435
 436 --doesDirectoryExist :: FilePath -> IO Bool
 437 doesDirectoryExist name =
 438  (getFileStatus name >>= \ st -> return (isDirectory st))
 439    `catch`
 440  (\ _ -> return False)
 441
 442 --getModificationTime :: FilePath -> IO ClockTime
 443 getModificationTime name =
 444  getFileStatus name >>= \ st ->
 445  modificationTime st
 446
 447 --getPermissions :: FilePath -> IO Permissions
 448 getPermissions name =
 449   getFileStatus name >>= \ st ->
 450   let
 451    fm = fileMode st
 452    isect v = intersectFileMode v fm == v
 453   in
 454   return (
 455     Permissions {
 456       readable   = isect ownerReadMode,
 457       writeable  = isect ownerWriteMode,
 458       executable = not (isDirectory st)   && isect ownerExecuteMode,
 459       searchable = not (isRegularFile st) && isect ownerExecuteMode
 460     }
 461   )
 462
 463 --setPermissions :: FilePath -> Permissions -> IO ()
 464 setPermissions name (Permissions r w e s) = do
 465     let
 466      read#  = case (if r then ownerReadMode else ``0'') of { W# x# -> x# }
 467      write# = case (if w then ownerWriteMode else ``0'') of { W# x# -> x# }
 468      exec#  = case (if e || s then ownerExecuteMode else ``0'') of { W# x# -> x# }
 469
 470      mode  = I# (word2Int# (read# `or#` write# `or#` exec#))
 471
 472     rc <- _ccall_ chmod name mode
 473     if rc == 0
 474         then return ()
 475         else fail (IOError Nothing SystemError "Directory.setPermissions")
 476
 477 \end{code}
 478
 479
 480 (Sigh)..copied from Posix.Files to avoid dep. on posix library
 481
 482 \begin{code}
 483 type FileStatus = ByteArray Int
 484
 485 getFileStatus :: FilePath -> IO FileStatus
 486 getFileStatus name = do
 487     bytes <- stToIO (newCharArray (0,``sizeof(struct stat)''))
 488     rc <- _casm_ ``%r = stat(%0,(struct stat *)%1);'' name bytes
 489     if rc == 0
 490         then stToIO (unsafeFreezeByteArray bytes)
 491         else fail (IOError Nothing SystemError "Directory.getFileStatus")
 492
 493 modificationTime :: FileStatus -> IO ClockTime
 494 modificationTime stat = do
 495     i1 <- malloc1
 496     _casm_ ``((unsigned long *)%1)[0] = ((struct stat *)%0)->st_mtime;'' stat i1
 497     secs <- cvtUnsigned i1
 498     return (TOD secs 0)
 499   where
 500     malloc1 = IO $ \ s# ->
 501         case newIntArray# 1# s# of
 502           StateAndMutableByteArray# s2# barr# ->
 503                 IOok s2# (MutableByteArray bnds barr#)
 504
 505     bnds = (0,1)
 506     -- The C routine fills in an unsigned word.  We don't have `unsigned2Integer#,'
 507     -- so we freeze the data bits and use them for an MP_INT structure.  Note that
 508     -- zero is still handled specially, although (J# 1# 1# (ptr to 0#)) is probably
 509     -- acceptable to gmp.
 510
 511     cvtUnsigned (MutableByteArray _ arr#) = IO $ \ s# ->
 512         case readIntArray# arr# 0# s# of
 513           StateAndInt# s2# r# ->
 514             if r# ==# 0# then
 515                 IOok s2# 0
 516             else
 517                 case unsafeFreezeByteArray# arr# s2# of
 518                   StateAndByteArray# s3# frozen# ->
 519                         IOok s3# (J# 1# 1# frozen#)
 520
 521 isDirectory :: FileStatus -> Bool
 522 isDirectory stat = unsafePerformIO $ do
 523     rc <- _casm_ ``%r = S_ISDIR(((struct stat *)%0)->st_mode);'' stat
 524     return (rc /= 0)
 525
 526 isRegularFile :: FileStatus -> Bool
 527 isRegularFile stat = unsafePerformIO $ do
 528     rc <- _casm_ ``%r = S_ISREG(((struct stat *)%0)->st_mode);'' stat
 529     return (rc /= 0)
 530 \end{code}
 531
 532 \begin{code}
 533 type FileMode = Word
 534 ownerReadMode :: FileMode
 535 ownerReadMode = ``S_IRUSR''
 536
 537 ownerWriteMode :: FileMode
 538 ownerWriteMode = ``S_IWUSR''
 539
 540 ownerExecuteMode :: FileMode
 541 ownerExecuteMode = ``S_IXUSR''
 542
 543 intersectFileMode :: FileMode -> FileMode -> FileMode
 544 intersectFileMode (W# m1#) (W# m2#) = W# (m1# `and#` m2#)
 545
 546 fileMode :: FileStatus -> FileMode
 547 fileMode stat = unsafePerformIO (
 548         _casm_ ``%r = ((struct stat *)%0)->st_mode;'' stat)
 549
 550 \end{code}