1 % -----------------------------------------------------------------------------
3 % (c) The University of Glasgow, 1994-
5 % The Directory Interface
7 A directory contains a series of entries, each of which is a named
8 reference to a file system object (file, directory etc.). Some
9 entries may be hidden, inaccessible, or have some administrative
10 function (e.g. "." or ".." under POSIX), but in this standard all such
11 entries are considered to form part of the directory contents.
12 Entries in sub-directories are not, however, considered to form part
13 of the directory contents.
15 Each file system object is referenced by a {\em path}. There is
16 normally at least one absolute path to each file system object. In
17 some operating systems, it may also be possible to have paths which
18 are relative to the current directory.
21 {-# OPTIONS -#include "dirUtils.h" #-}
24 Permissions -- instance of (Eq, Ord, Read, Show)
26 , readable -- :: Permissions -> Bool
27 , writable -- :: Permissions -> Bool
28 , executable -- :: Permissions -> Bool
29 , searchable -- :: Permissions -> Bool
32 , createDirectory -- :: FilePath -> IO ()
33 , removeDirectory -- :: FilePath -> IO ()
34 , renameDirectory -- :: FilePath -> FilePath -> IO ()
36 , getDirectoryContents -- :: FilePath -> IO [FilePath]
37 , getCurrentDirectory -- :: IO FilePath
38 , setCurrentDirectory -- :: FilePath -> IO ()
40 , removeFile -- :: FilePath -> IO ()
41 , renameFile -- :: FilePath -> FilePath -> IO ()
43 , doesFileExist -- :: FilePath -> IO Bool
44 , doesDirectoryExist -- :: FilePath -> IO Bool
46 , getPermissions -- :: FilePath -> IO Permissions
47 , setPermissions -- :: FilePath -> Permissions -> IO ()
49 , getModificationTime -- :: FilePath -> IO ClockTime
52 import Prelude -- Just to get it in the dependencies
54 import Time ( ClockTime(..) )
59 import PrelMarshalAlloc
68 -----------------------------------------------------------------------------
71 The @Permissions@ type is used to record whether certain
72 operations are permissible on a file/directory:
73 [to whom? - presumably the "current user"]
79 executable, searchable :: Bool
80 } deriving (Eq, Ord, Read, Show)
83 -----------------------------------------------------------------------------
86 @createDirectory dir@ creates a new directory {\em dir} which is
87 initially empty, or as near to empty as the operating system
90 The operation may fail with:
93 \item @isPermissionError@ / @PermissionDenied@
94 The process has insufficient privileges to perform the operation.
96 \item @isAlreadyExistsError@ / @AlreadyExists@
97 The operand refers to a directory that already exists.
100 A physical I/O error has occurred.
102 \item @InvalidArgument@
103 The operand is not a valid directory name.
104 @[ENAMETOOLONG, ELOOP]@
106 There is no path to the directory.
108 \item @ResourceExhausted@
109 Insufficient resources (virtual memory, process file descriptors,
110 physical disk space, etc.) are available to perform the operation.
111 @[EDQUOT, ENOSPC, ENOMEM, EMLINK]@
112 \item @InappropriateType@
113 The path refers to an existing non-directory object.
118 createDirectory :: FilePath -> IO ()
119 createDirectory path = do
120 withCString path $ \s -> do
121 throwErrnoIfMinus1Retry_ "createDirectory" $
125 @removeDirectory dir@ removes an existing directory {\em dir}. The
126 implementation may specify additional constraints which must be
127 satisfied before a directory can be removed (e.g. the directory has to
128 be empty, or may not be in use by other processes). It is not legal
129 for an implementation to partially remove a directory unless the
130 entire directory is removed. A conformant implementation need not
131 support directory removal in all situations (e.g. removal of the root
134 The operation may fail with:
136 \item @HardwareFault@
137 A physical I/O error has occurred.
139 \item @InvalidArgument@
140 The operand is not a valid directory name.
141 @[ENAMETOOLONG, ELOOP]@
142 \item @isDoesNotExist@ / @NoSuchThing@
143 The directory does not exist.
145 \item @isPermissionError@ / @PermissionDenied@
146 The process has insufficient privileges to perform the operation.
147 @[EROFS, EACCES, EPERM]@
148 \item @UnsatisfiedConstraints@
149 Implementation-dependent constraints are not satisfied.
150 @[EBUSY, ENOTEMPTY, EEXIST]@
151 \item @UnsupportedOperation@
152 The implementation does not support removal in this situation.
154 \item @InappropriateType@
155 The operand refers to an existing non-directory object.
160 removeDirectory :: FilePath -> IO ()
161 removeDirectory path = do
162 withCString path $ \s ->
163 throwErrnoIfMinus1Retry_ "removeDirectory" (rmdir s)
167 @Removefile file@ removes the directory entry for an existing file
168 {\em file}, where {\em file} is not itself a directory. The
169 implementation may specify additional constraints which must be
170 satisfied before a file can be removed (e.g. the file may not be in
171 use by other processes).
173 The operation may fail with:
175 \item @HardwareFault@
176 A physical I/O error has occurred.
178 \item @InvalidArgument@
179 The operand is not a valid file name.
180 @[ENAMETOOLONG, ELOOP]@
181 \item @isDoesNotExist@ / @NoSuchThing@
182 The file does not exist.
184 \item @isPermissionError@ / @PermissionDenied@
185 The process has insufficient privileges to perform the operation.
186 @[EROFS, EACCES, EPERM]@
187 \item @UnsatisfiedConstraints@
188 Implementation-dependent constraints are not satisfied.
190 \item @InappropriateType@
191 The operand refers to an existing directory.
196 removeFile :: FilePath -> IO ()
198 withCString path $ \s ->
199 throwErrnoIfMinus1Retry_ "removeFile" (unlink s)
203 @renameDirectory@ {\em old} {\em new} changes the name of an existing
204 directory from {\em old} to {\em new}. If the {\em new} directory
205 already exists, it is atomically replaced by the {\em old} directory.
206 If the {\em new} directory is neither the {\em old} directory nor an
207 alias of the {\em old} directory, it is removed as if by
208 $removeDirectory$. A conformant implementation need not support
209 renaming directories in all situations (e.g. renaming to an existing
210 directory, or across different physical devices), but the constraints
213 The operation may fail with:
215 \item @HardwareFault@
216 A physical I/O error has occurred.
218 \item @InvalidArgument@
219 Either operand is not a valid directory name.
220 @[ENAMETOOLONG, ELOOP]@
221 \item @isDoesNotExistError@ / @NoSuchThing@
222 The original directory does not exist, or there is no path to the target.
224 \item @isPermissionError@ / @PermissionDenied@
225 The process has insufficient privileges to perform the operation.
226 @[EROFS, EACCES, EPERM]@
227 \item @ResourceExhausted@
228 Insufficient resources are available to perform the operation.
229 @[EDQUOT, ENOSPC, ENOMEM, EMLINK]@
230 \item @UnsatisfiedConstraints@
231 Implementation-dependent constraints are not satisfied.
232 @[EBUSY, ENOTEMPTY, EEXIST]@
233 \item @UnsupportedOperation@
234 The implementation does not support renaming in this situation.
236 \item @InappropriateType@
237 Either path refers to an existing non-directory object.
242 renameDirectory :: FilePath -> FilePath -> IO ()
243 renameDirectory opath npath =
244 withFileStatus opath $ \st -> do
245 is_dir <- isDirectory st
247 then ioException (IOError Nothing InappropriateType "renameDirectory"
248 ("not a directory") (Just opath))
251 withCString opath $ \s1 ->
252 withCString npath $ \s2 ->
253 throwErrnoIfMinus1Retry_ "renameDirectory" (rename s1 s2)
257 @renameFile@ {\em old} {\em new} changes the name of an existing file system
258 object from {\em old} to {\em new}. If the {\em new} object already
259 exists, it is atomically replaced by the {\em old} object. Neither
260 path may refer to an existing directory. A conformant implementation
261 need not support renaming files in all situations (e.g. renaming
262 across different physical devices), but the constraints must be
265 The operation may fail with:
267 \item @HardwareFault@
268 A physical I/O error has occurred.
270 \item @InvalidArgument@
271 Either operand is not a valid file name.
272 @[ENAMETOOLONG, ELOOP]@
273 \item @isDoesNotExistError@ / @NoSuchThing@
274 The original file does not exist, or there is no path to the target.
276 \item @isPermissionError@ / @PermissionDenied@
277 The process has insufficient privileges to perform the operation.
278 @[EROFS, EACCES, EPERM]@
279 \item @ResourceExhausted@
280 Insufficient resources are available to perform the operation.
281 @[EDQUOT, ENOSPC, ENOMEM, EMLINK]@
282 \item @UnsatisfiedConstraints@
283 Implementation-dependent constraints are not satisfied.
285 \item @UnsupportedOperation@
286 The implementation does not support renaming in this situation.
288 \item @InappropriateType@
289 Either path refers to an existing directory.
290 @[ENOTDIR, EISDIR, EINVAL, EEXIST, ENOTEMPTY]@
294 renameFile :: FilePath -> FilePath -> IO ()
295 renameFile opath npath =
296 withFileOrSymlinkStatus opath $ \st -> do
297 is_dir <- isDirectory st
299 then ioException (IOError Nothing InappropriateType "renameFile"
300 "is a directory" (Just opath))
303 withCString opath $ \s1 ->
304 withCString npath $ \s2 ->
305 throwErrnoIfMinus1Retry_ "renameFile" (rename s1 s2)
309 @getDirectoryContents dir@ returns a list of {\em all} entries
312 The operation may fail with:
314 \item @HardwareFault@
315 A physical I/O error has occurred.
317 \item @InvalidArgument@
318 The operand is not a valid directory name.
319 @[ENAMETOOLONG, ELOOP]@
320 \item @isDoesNotExistError@ / @NoSuchThing@
321 The directory does not exist.
323 \item @isPermissionError@ / @PermissionDenied@
324 The process has insufficient privileges to perform the operation.
326 \item @ResourceExhausted@
327 Insufficient resources are available to perform the operation.
329 \item @InappropriateType@
330 The path refers to an existing non-directory object.
335 getDirectoryContents :: FilePath -> IO [FilePath]
336 getDirectoryContents path = do
337 p <- withCString path $ \s ->
338 throwErrnoIfNullRetry "getDirectoryContents" (opendir s)
341 loop :: Ptr CDir -> IO [String]
347 entry <- (d_name p >>= peekCString)
349 return (entry:entries)
350 else do errno <- getErrno
351 if (errno == eINTR) then loop dir else do
352 throwErrnoIfMinus1_ "getDirectoryContents" $ closedir dir
353 let (Errno eo) = errno
354 if (eo == end_of_dir)
356 else throwErrno "getDirectoryContents"
358 foreign import ccall "prel_end_of_dir" unsafe end_of_dir :: CInt
359 foreign import ccall "prel_d_name" unsafe d_name :: Ptr CDirent -> IO CString
363 If the operating system has a notion of current directories,
364 @getCurrentDirectory@ returns an absolute path to the
365 current directory of the calling process.
367 The operation may fail with:
369 \item @HardwareFault@
370 A physical I/O error has occurred.
372 \item @isDoesNotExistError@ / @NoSuchThing@
373 There is no path referring to the current directory.
374 @[EPERM, ENOENT, ESTALE...]@
375 \item @isPermissionError@ / @PermissionDenied@
376 The process has insufficient privileges to perform the operation.
378 \item @ResourceExhausted@
379 Insufficient resources are available to perform the operation.
380 \item @UnsupportedOperation@
381 The operating system has no notion of current directory.
385 getCurrentDirectory :: IO FilePath
386 getCurrentDirectory = do
387 p <- mallocBytes path_max
389 where go p bytes = do
390 p' <- getcwd p (fromIntegral bytes)
392 then do s <- peekCString p'
395 else do errno <- getErrno
397 then do let bytes' = bytes * 2
398 p' <- reallocBytes p bytes'
400 else throwErrno "getCurrentDirectory"
402 foreign import ccall "prel_path_max" unsafe path_max :: Int
406 If the operating system has a notion of current directories,
407 @setCurrentDirectory dir@ changes the current
408 directory of the calling process to {\em dir}.
410 The operation may fail with:
412 \item @HardwareFault@
413 A physical I/O error has occurred.
415 \item @InvalidArgument@
416 The operand is not a valid directory name.
417 @[ENAMETOOLONG, ELOOP]@
418 \item @isDoesNotExistError@ / @NoSuchThing@
419 The directory does not exist.
421 \item @isPermissionError@ / @PermissionDenied@
422 The process has insufficient privileges to perform the operation.
424 \item @UnsupportedOperation@
425 The operating system has no notion of current directory, or the
426 current directory cannot be dynamically changed.
427 \item @InappropriateType@
428 The path refers to an existing non-directory object.
433 setCurrentDirectory :: FilePath -> IO ()
434 setCurrentDirectory path = do
435 withCString path $ \s ->
436 throwErrnoIfMinus1Retry_ "setCurrentDirectory" (chdir s)
437 -- ToDo: add path to error
441 To clarify, @doesDirectoryExist@ returns True if a file system object
442 exist, and it's a directory. @doesFileExist@ returns True if the file
443 system object exist, but it's not a directory (i.e., for every other
444 file system object that is not a directory.)
447 doesDirectoryExist :: FilePath -> IO Bool
448 doesDirectoryExist name =
450 (withFileStatus name $ \st -> isDirectory st)
451 (\ _ -> return False)
453 doesFileExist :: FilePath -> IO Bool
454 doesFileExist name = do
456 (withFileStatus name $ \st -> do b <- isDirectory st; return (not b))
457 (\ _ -> return False)
459 getModificationTime :: FilePath -> IO ClockTime
460 getModificationTime name =
461 withFileStatus name $ \ st ->
464 getPermissions :: FilePath -> IO Permissions
465 getPermissions name = do
466 withCString name $ \s -> do
467 read <- access s r_OK
468 write <- access s w_OK
469 exec <- access s x_OK
470 withFileStatus name $ \st -> do
471 is_dir <- isDirectory st
472 is_reg <- isRegularFile st
475 readable = read == 0,
476 writable = write == 0,
477 executable = not is_dir && exec == 0,
478 searchable = not is_reg && exec == 0
482 foreign import ccall "prel_R_OK" unsafe r_OK :: CMode
483 foreign import ccall "prel_W_OK" unsafe w_OK :: CMode
484 foreign import ccall "prel_X_OK" unsafe x_OK :: CMode
486 setPermissions :: FilePath -> Permissions -> IO ()
487 setPermissions name (Permissions r w e s) = do
489 read = if r then s_IRUSR else emptyCMode
490 write = if w then s_IWUSR else emptyCMode
491 exec = if e || s then s_IXUSR else emptyCMode
493 mode = read `unionCMode` (write `unionCMode` exec)
495 withCString name $ \s ->
496 throwErrnoIfMinus1_ "setPermissions" $ chmod s mode
498 foreign import ccall "prel_S_IRUSR" unsafe s_IRUSR :: CMode
499 foreign import ccall "prel_S_IWUSR" unsafe s_IWUSR :: CMode
500 foreign import ccall "prel_S_IXUSR" unsafe s_IXUSR :: CMode
502 withFileStatus :: FilePath -> (Ptr CStat -> IO a) -> IO a
503 withFileStatus name f = do
504 allocaBytes sizeof_stat $ \p ->
505 withCString name $ \s -> do
506 throwErrnoIfMinus1Retry_ "withFileStatus" (stat s p)
509 withFileOrSymlinkStatus :: FilePath -> (Ptr CStat -> IO a) -> IO a
510 withFileOrSymlinkStatus name f = do
511 allocaBytes sizeof_stat $ \p ->
512 withCString name $ \s -> do
513 throwErrnoIfMinus1Retry_ "withFileOrSymlinkStatus" (lstat s p)
516 foreign import ccall "prel_sz_stat" unsafe sizeof_stat :: Int
518 modificationTime :: Ptr CStat -> IO ClockTime
519 modificationTime stat = do
520 mtime <- st_mtime stat
521 return (TOD (toInteger (mtime :: CTime)) 0)
523 foreign import ccall "prel_st_mtime" unsafe st_mtime :: Ptr CStat -> IO CTime
524 foreign import ccall "prel_st_mode" unsafe st_mode :: Ptr CStat -> IO CMode
526 isDirectory :: Ptr CStat -> IO Bool
527 isDirectory stat = do
529 return (s_ISDIR mode /= 0)
531 isRegularFile :: Ptr CStat -> IO Bool
532 isRegularFile stat = do
534 return (s_ISREG mode /= 0)
536 foreign import ccall "prel_s_ISDIR" unsafe s_ISDIR :: CMode -> Int
537 foreign import ccall "prel_s_ISREG" unsafe s_ISREG :: CMode -> Int
542 unionCMode :: CMode -> CMode -> CMode
545 foreign import ccall "prel_mkdir" unsafe mkdir :: CString -> CInt -> IO CInt
547 foreign import ccall unsafe chmod :: CString -> CMode -> IO CInt
548 foreign import ccall unsafe access :: CString -> CMode -> IO CInt
549 foreign import ccall unsafe rmdir :: CString -> IO CInt
550 foreign import ccall unsafe chdir :: CString -> IO CInt
551 foreign import ccall unsafe getcwd :: Ptr CChar -> CInt -> IO (Ptr CChar)
552 foreign import ccall unsafe unlink :: CString -> IO CInt
553 foreign import ccall unsafe rename :: CString -> CString -> IO CInt
555 foreign import ccall unsafe opendir :: CString -> IO (Ptr CDir)
556 foreign import ccall unsafe readdir :: Ptr CDir -> IO (Ptr CDirent)
557 foreign import ccall unsafe closedir :: Ptr CDir -> IO CInt
559 foreign import ccall unsafe stat :: CString -> Ptr CStat -> IO CInt
561 foreign import ccall "prel_lstat" unsafe lstat :: CString -> Ptr CStat -> IO CInt