2 % (c) The AQUA Project, Glasgow University, 1994-1997
4 \section[Directory]{Directory interface}
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.
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.
20 {-# OPTIONS -#include <sys/stat.h> -#include <dirent.h> -#include "cbits/stgio.h" #-}
23 Permissions(Permissions),
46 import PrelPack ( unpackNBytesST )
47 import PrelForeign ( Word(..) )
49 import Time ( ClockTime(..) )
53 %*********************************************************
55 \subsection{Signatures}
57 %*********************************************************
60 createDirectory :: FilePath -> IO ()
61 removeDirectory :: FilePath -> IO ()
62 removeFile :: FilePath -> IO ()
63 renameDirectory :: FilePath -> FilePath -> IO ()
64 renameFile :: FilePath -> FilePath -> IO ()
65 getDirectoryContents :: FilePath -> IO [FilePath]
66 getCurrentDirectory :: IO FilePath
67 setCurrentDirectory :: FilePath -> IO ()
68 doesFileExist :: FilePath -> IO Bool
69 doesDirectoryExist :: FilePath -> IO Bool
70 getPermissions :: FilePath -> IO Permissions
71 setPermissions :: FilePath -> Permissions -> IO ()
72 getModificationTime :: FilePath -> IO ClockTime
76 %*********************************************************
78 \subsection{Permissions}
80 %*********************************************************
82 The @Permissions@ type is used to record whether certain
83 operations are permissible on a file/directory:
84 [to whom? - owner/group/world - the Report don't say much]
90 executable, searchable :: Bool
91 } deriving (Eq, Ord, Read, Show)
94 %*********************************************************
96 \subsection{Implementation}
98 %*********************************************************
100 @createDirectory dir@ creates a new directory {\em dir} which is
101 initially empty, or as near to empty as the operating system
104 The operation may fail with:
107 \item @isPermissionError@ / @PermissionDenied@
108 The process has insufficient privileges to perform the operation.
110 \item @isAlreadyExistsError@ / @AlreadyExists@
111 The operand refers to a directory that already exists.
113 \item @HardwareFault@
114 A physical I/O error has occurred.
116 \item @InvalidArgument@
117 The operand is not a valid directory name.
118 @[ENAMETOOLONG, ELOOP]@
120 There is no path to the directory.
122 \item @ResourceExhausted@
123 Insufficient resources (virtual memory, process file descriptors,
124 physical disk space, etc.) are available to perform the operation.
125 @[EDQUOT, ENOSPC, ENOMEM, EMLINK]@
126 \item @InappropriateType@
127 The path refers to an existing non-directory object.
132 createDirectory path = do
133 rc <- _ccall_ createDirectory path
134 if rc == 0 then return () else
135 constructErrorAndFailWithInfo "createDirectory" path
138 @removeDirectory dir@ removes an existing directory {\em dir}. The
139 implementation may specify additional constraints which must be
140 satisfied before a directory can be removed (e.g. the directory has to
141 be empty, or may not be in use by other processes). It is not legal
142 for an implementation to partially remove a directory unless the
143 entire directory is removed. A conformant implementation need not
144 support directory removal in all situations (e.g. removal of the root
147 The operation may fail with:
149 \item @HardwareFault@
150 A physical I/O error has occurred.
152 \item @InvalidArgument@
153 The operand is not a valid directory name.
154 @[ENAMETOOLONG, ELOOP]@
155 \item @isDoesNotExist@ / @NoSuchThing@
156 The directory does not exist.
158 \item @isPermissionError@ / @PermissionDenied@
159 The process has insufficient privileges to perform the operation.
160 @[EROFS, EACCES, EPERM]@
161 \item @UnsatisfiedConstraints@
162 Implementation-dependent constraints are not satisfied.
163 @[EBUSY, ENOTEMPTY, EEXIST]@
164 \item @UnsupportedOperation@
165 The implementation does not support removal in this situation.
167 \item @InappropriateType@
168 The operand refers to an existing non-directory object.
173 removeDirectory path = do
174 rc <- _ccall_ removeDirectory path
178 constructErrorAndFailWithInfo "removeDirectory" path
181 @removeFile file@ removes the directory entry for an existing file
182 {\em file}, where {\em file} is not itself a directory. The
183 implementation may specify additional constraints which must be
184 satisfied before a file can be removed (e.g. the file may not be in
185 use by other processes).
187 The operation may fail with:
189 \item @HardwareFault@
190 A physical I/O error has occurred.
192 \item @InvalidArgument@
193 The operand is not a valid file name.
194 @[ENAMETOOLONG, ELOOP]@
195 \item @isDoesNotExist@ / @NoSuchThing@
196 The file does not exist.
198 \item @isPermissionError@ / @PermissionDenied@
199 The process has insufficient privileges to perform the operation.
200 @[EROFS, EACCES, EPERM]@
201 \item @UnsatisfiedConstraints@
202 Implementation-dependent constraints are not satisfied.
204 \item @InappropriateType@
205 The operand refers to an existing directory.
211 rc <- _ccall_ removeFile path
215 constructErrorAndFailWithInfo "removeFile" path
218 @renameDirectory old@ {\em new} changes the name of an existing
219 directory from {\em old} to {\em new}. If the {\em new} directory
220 already exists, it is atomically replaced by the {\em old} directory.
221 If the {\em new} directory is neither the {\em old} directory nor an
222 alias of the {\em old} directory, it is removed as if by
223 $removeDirectory$. A conformant implementation need not support
224 renaming directories in all situations (e.g. renaming to an existing
225 directory, or across different physical devices), but the constraints
228 The operation may fail with:
230 \item @HardwareFault@
231 A physical I/O error has occurred.
233 \item @InvalidArgument@
234 Either operand is not a valid directory name.
235 @[ENAMETOOLONG, ELOOP]@
236 \item @isDoesNotExistError@ / @NoSuchThing@
237 The original directory does not exist, or there is no path to the target.
239 \item @isPermissionError@ / @PermissionDenied@
240 The process has insufficient privileges to perform the operation.
241 @[EROFS, EACCES, EPERM]@
242 \item @ResourceExhausted@
243 Insufficient resources are available to perform the operation.
244 @[EDQUOT, ENOSPC, ENOMEM, EMLINK]@
245 \item @UnsatisfiedConstraints@
246 Implementation-dependent constraints are not satisfied.
247 @[EBUSY, ENOTEMPTY, EEXIST]@
248 \item @UnsupportedOperation@
249 The implementation does not support renaming in this situation.
251 \item @InappropriateType@
252 Either path refers to an existing non-directory object.
257 renameDirectory opath npath = do
258 rc <- _ccall_ renameDirectory opath npath
262 constructErrorAndFailWithInfo "renameDirectory" opath
265 @renameFile old@ {\em new} changes the name of an existing file system
266 object from {\em old} to {\em new}. If the {\em new} object already
267 exists, it is atomically replaced by the {\em old} object. Neither
268 path may refer to an existing directory. A conformant implementation
269 need not support renaming files in all situations (e.g. renaming
270 across different physical devices), but the constraints must be
273 The operation may fail with:
275 \item @HardwareFault@
276 A physical I/O error has occurred.
278 \item @InvalidArgument@
279 Either operand is not a valid file name.
280 @[ENAMETOOLONG, ELOOP]@
281 \item @isDoesNotExistError@ / @NoSuchThing@
282 The original file does not exist, or there is no path to the target.
284 \item @isPermissionError@ / @PermissionDenied@
285 The process has insufficient privileges to perform the operation.
286 @[EROFS, EACCES, EPERM]@
287 \item @ResourceExhausted@
288 Insufficient resources are available to perform the operation.
289 @[EDQUOT, ENOSPC, ENOMEM, EMLINK]@
290 \item @UnsatisfiedConstraints@
291 Implementation-dependent constraints are not satisfied.
293 \item @UnsupportedOperation@
294 The implementation does not support renaming in this situation.
296 \item @InappropriateType@
297 Either path refers to an existing directory.
298 @[ENOTDIR, EISDIR, EINVAL, EEXIST, ENOTEMPTY]@
302 renameFile opath npath = do
303 rc <- _ccall_ renameFile opath npath
307 constructErrorAndFailWithInfo "renameFile" opath
310 @getDirectoryContents dir@ returns a list of {\em all} entries
313 The operation may fail with:
315 \item @HardwareFault@
316 A physical I/O error has occurred.
318 \item @InvalidArgument@
319 The operand is not a valid directory name.
320 @[ENAMETOOLONG, ELOOP]@
321 \item @isDoesNotExistError@ / @NoSuchThing@
322 The directory does not exist.
324 \item @isPermissionError@ / @PermissionDenied@
325 The process has insufficient privileges to perform the operation.
327 \item @ResourceExhausted@
328 Insufficient resources are available to perform the operation.
330 \item @InappropriateType@
331 The path refers to an existing non-directory object.
336 --getDirectoryContents :: FilePath -> IO [FilePath]
337 getDirectoryContents path = do
338 dir <- _ccall_ openDir__ path
340 then constructErrorAndFailWithInfo "getDirectoryContents" path
343 loop :: Addr -> IO [String]
345 dirent_ptr <- _ccall_ readDir__ dir
346 if (dirent_ptr::Addr) == ``NULL''
348 -- readDir__ implicitly performs closedir() when the
352 str <- _casm_ `` %r=(char*)((struct dirent*)%0)->d_name; '' dirent_ptr
353 -- not using the unpackCString function here, since we have to force
354 -- the unmarshalling of the directory entry right here as subsequent
355 -- calls to readdir() may overwrite it.
356 len <- _ccall_ strlen str
357 entry <- stToIO (unpackNBytesST str len)
359 return (entry:entries)
362 If the operating system has a notion of current directories,
363 @getCurrentDirectory@ returns an absolute path to the
364 current directory of the calling process.
366 The operation may fail with:
368 \item @HardwareFault@
369 A physical I/O error has occurred.
371 \item @isDoesNotExistError@ / @NoSuchThing@
372 There is no path referring to the current directory.
373 @[EPERM, ENOENT, ESTALE...]@
374 \item @isPermissionError@ / @PermissionDenied@
375 The process has insufficient privileges to perform the operation.
377 \item @ResourceExhausted@
378 Insufficient resources are available to perform the operation.
379 \item @UnsupportedOperation@
380 The operating system has no notion of current directory.
384 getCurrentDirectory = do
385 str <- _ccall_ getCurrentDirectory
388 len <- _ccall_ strlen str
389 pwd <- stToIO (unpackNBytesST str len)
393 constructErrorAndFail "getCurrentDirectory"
396 If the operating system has a notion of current directories,
397 @setCurrentDirectory dir@ changes the current
398 directory of the calling process to {\em dir}.
400 The operation may fail with:
402 \item @HardwareFault@
403 A physical I/O error has occurred.
405 \item @InvalidArgument@
406 The operand is not a valid directory name.
407 @[ENAMETOOLONG, ELOOP]@
408 \item @isDoesNotExistError@ / @NoSuchThing@
409 The directory does not exist.
411 \item @isPermissionError@ / @PermissionDenied@
412 The process has insufficient privileges to perform the operation.
414 \item @UnsupportedOperation@
415 The operating system has no notion of current directory, or the
416 current directory cannot be dynamically changed.
417 \item @InappropriateType@
418 The path refers to an existing non-directory object.
423 setCurrentDirectory path = do
424 rc <- _ccall_ setCurrentDirectory path
427 else constructErrorAndFailWithInfo "setCurrentDirectory" path
432 --doesFileExist :: FilePath -> IO Bool
433 doesFileExist name = do
434 rc <- _ccall_ access name (``F_OK''::Int)
437 --doesDirectoryExist :: FilePath -> IO Bool
438 doesDirectoryExist name =
439 (getFileStatus name >>= \ st -> return (isDirectory st))
441 (\ _ -> return False)
443 --getModificationTime :: FilePath -> IO ClockTime
444 getModificationTime name =
445 getFileStatus name >>= \ st ->
448 --getPermissions :: FilePath -> IO Permissions
449 getPermissions name =
450 getFileStatus name >>= \ st ->
453 isect v = intersectFileMode v fm == v
457 readable = isect ownerReadMode,
458 writeable = isect ownerWriteMode,
459 executable = not (isDirectory st) && isect ownerExecuteMode,
460 searchable = not (isRegularFile st) && isect ownerExecuteMode
464 --setPermissions :: FilePath -> Permissions -> IO ()
465 setPermissions name (Permissions r w e s) = do
467 read# = case (if r then ownerReadMode else ``0'') of { W# x# -> x# }
468 write# = case (if w then ownerWriteMode else ``0'') of { W# x# -> x# }
469 exec# = case (if e || s then ownerExecuteMode else ``0'') of { W# x# -> x# }
471 mode = I# (word2Int# (read# `or#` write# `or#` exec#))
473 rc <- _ccall_ chmod name mode
476 else fail (IOError Nothing SystemError "Directory.setPermissions")
481 (Sigh)..copied from Posix.Files to avoid dep. on posix library
484 type FileStatus = ByteArray Int
486 getFileStatus :: FilePath -> IO FileStatus
487 getFileStatus name = do
488 bytes <- stToIO (newCharArray (0,``sizeof(struct stat)''))
489 rc <- _casm_ ``%r = stat(%0,(struct stat *)%1);'' name bytes
491 then stToIO (unsafeFreezeByteArray bytes)
492 else fail (IOError Nothing SystemError "Directory.getFileStatus")
494 modificationTime :: FileStatus -> IO ClockTime
495 modificationTime stat = do
497 _casm_ ``((unsigned long *)%1)[0] = ((struct stat *)%0)->st_mtime;'' stat i1
498 secs <- cvtUnsigned i1
501 malloc1 = IO $ \ s# ->
502 case newIntArray# 1# s# of
503 StateAndMutableByteArray# s2# barr# ->
504 IOok s2# (MutableByteArray bnds barr#)
507 -- The C routine fills in an unsigned word. We don't have `unsigned2Integer#,'
508 -- so we freeze the data bits and use them for an MP_INT structure. Note that
509 -- zero is still handled specially, although (J# 1# 1# (ptr to 0#)) is probably
510 -- acceptable to gmp.
512 cvtUnsigned (MutableByteArray _ arr#) = IO $ \ s# ->
513 case readIntArray# arr# 0# s# of
514 StateAndInt# s2# r# ->
518 case unsafeFreezeByteArray# arr# s2# of
519 StateAndByteArray# s3# frozen# ->
520 IOok s3# (J# 1# 1# frozen#)
522 isDirectory :: FileStatus -> Bool
523 isDirectory stat = unsafePerformIO $ do
524 rc <- _casm_ ``%r = S_ISDIR(((struct stat *)%0)->st_mode);'' stat
527 isRegularFile :: FileStatus -> Bool
528 isRegularFile stat = unsafePerformIO $ do
529 rc <- _casm_ ``%r = S_ISREG(((struct stat *)%0)->st_mode);'' stat
535 ownerReadMode :: FileMode
536 ownerReadMode = ``S_IRUSR''
538 ownerWriteMode :: FileMode
539 ownerWriteMode = ``S_IWUSR''
541 ownerExecuteMode :: FileMode
542 ownerExecuteMode = ``S_IXUSR''
544 intersectFileMode :: FileMode -> FileMode -> FileMode
545 intersectFileMode (W# m1#) (W# m2#) = W# (m1# `and#` m2#)
547 fileMode :: FileStatus -> FileMode
548 fileMode stat = unsafePerformIO (
549 _casm_ ``%r = ((struct stat *)%0)->st_mode;'' stat)