2 % (c) The AQUA Project, Glasgow University, 1994-1996
5 \section[Directory]{Module @Directory@}
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.
22 createDirectory, removeDirectory, removeFile,
23 renameDirectory, renameFile, getDirectoryContents,
24 getCurrentDirectory, setCurrentDirectory
29 import STBase ( PrimIO )
30 import PackedString ( packCBytesST, unpackPS )
33 %*********************************************************
35 \subsection{Signatures}
37 %*********************************************************
40 createDirectory :: FilePath -> IO ()
41 removeDirectory :: FilePath -> IO ()
42 removeFile :: FilePath -> IO ()
43 renameDirectory :: FilePath -> FilePath -> IO ()
44 renameFile :: FilePath -> FilePath -> IO ()
45 getDirectoryContents :: FilePath -> IO [FilePath]
46 getCurrentDirectory :: IO FilePath
47 setCurrentDirectory :: FilePath -> IO ()
51 %*********************************************************
53 \subsection{Signatures}
55 %*********************************************************
57 $createDirectory dir$ creates a new directory
58 {\em dir} which is initially empty, or as near to empty as the
59 operating system allows.
61 The operation may fail with:
64 The operand refers to a directory that already exists.
67 A physical I/O error has occurred.
69 \item $InvalidArgument$
70 The operand is not a valid directory name.
71 [$ENAMETOOLONG$, $ELOOP$]
73 There is no path to the directory.
75 \item $PermissionDenied$
76 The process has insufficient privileges to perform the operation.
78 \item $ResourceExhausted$
79 Insufficient resources (virtual memory, process file descriptors,
80 physical disk space, etc.) are available to perform the operation.
81 [$EDQUOT$, $ENOSPC$, $ENOMEM$,
83 \item $InappropriateType$
84 The path refers to an existing non-directory object.
89 createDirectory path =
90 _ccall_ createDirectory path `thenIO_Prim` \ rc ->
94 constructErrorAndFail "createDirectory"
97 $removeDirectory dir$ removes an existing directory {\em dir}. The
98 implementation may specify additional constraints which must be
99 satisfied before a directory can be removed (e.g. the directory has to
100 be empty, or may not be in use by other processes). It is not legal
101 for an implementation to partially remove a directory unless the
102 entire directory is removed. A conformant implementation need not
103 support directory removal in all situations (e.g. removal of the root
106 The operation may fail with:
108 \item $HardwareFault$
109 A physical I/O error has occurred.
111 \item $InvalidArgument$
112 The operand is not a valid directory name.
113 [$ENAMETOOLONG$, $ELOOP$]
115 The directory does not exist.
116 [$ENOENT$, $ENOTDIR$]
117 \item $PermissionDenied$
118 The process has insufficient privileges to perform the operation.
119 [$EROFS$, $EACCES$, $EPERM$]
120 \item $UnsatisfiedConstraints$
121 Implementation-dependent constraints are not satisfied.
122 [$EBUSY$, $ENOTEMPTY$, $EEXIST$]
123 \item $UnsupportedOperation$
124 The implementation does not support removal in this situation.
126 \item $InappropriateType$
127 The operand refers to an existing non-directory object.
132 removeDirectory path =
133 _ccall_ removeDirectory path `thenIO_Prim` \ rc ->
137 constructErrorAndFail "removeDirectory"
140 $removeFile file$ removes the directory entry for an existing file
141 {\em file}, where {\em file} is not itself a directory. The
142 implementation may specify additional constraints which must be
143 satisfied before a file can be removed (e.g. the file may not be in
144 use by other processes).
146 The operation may fail with:
148 \item $HardwareFault$
149 A physical I/O error has occurred.
151 \item $InvalidArgument$
152 The operand is not a valid file name.
153 [$ENAMETOOLONG$, $ELOOP$]
155 The file does not exist.
156 [$ENOENT$, $ENOTDIR$]
157 \item $PermissionDenied$
158 The process has insufficient privileges to perform the operation.
159 [$EROFS$, $EACCES$, $EPERM$]
160 \item $UnsatisfiedConstraints$
161 Implementation-dependent constraints are not satisfied.
163 \item $InappropriateType$
164 The operand refers to an existing directory.
170 _ccall_ removeFile path `thenIO_Prim` \ rc ->
174 constructErrorAndFail "removeFile"
177 $renameDirectory old$ {\em new} changes the name of an existing
178 directory from {\em old} to {\em new}. If the {\em new} directory
179 already exists, it is atomically replaced by the {\em old} directory.
180 If the {\em new} directory is neither the {\em old} directory nor an
181 alias of the {\em old} directory, it is removed as if by
182 $removeDirectory$. A conformant implementation need not support
183 renaming directories in all situations (e.g. renaming to an existing
184 directory, or across different physical devices), but the constraints
187 The operation may fail with:
189 \item $HardwareFault$
190 A physical I/O error has occurred.
192 \item $InvalidArgument$
193 Either operand is not a valid directory name.
194 [$ENAMETOOLONG$, $ELOOP$]
196 The original directory does not exist, or there is no path to the target.
197 [$ENOENT$, $ENOTDIR$]
198 \item $PermissionDenied$
199 The process has insufficient privileges to perform the operation.
200 [$EROFS$, $EACCES$, $EPERM$]
201 \item $ResourceExhausted$
202 Insufficient resources are available to perform the operation.
203 [$EDQUOT$, $ENOSPC$, $ENOMEM$,
205 \item $UnsatisfiedConstraints$
206 Implementation-dependent constraints are not satisfied.
207 [$EBUSY$, $ENOTEMPTY$, $EEXIST$]
208 \item $UnsupportedOperation$
209 The implementation does not support renaming in this situation.
211 \item $InappropriateType$
212 Either path refers to an existing non-directory object.
213 [$ENOTDIR$, $EISDIR$]
217 renameDirectory opath npath =
218 _ccall_ renameDirectory opath npath `thenIO_Prim` \ rc ->
222 constructErrorAndFail "renameDirectory"
225 $renameFile old$ {\em new} changes the name of an existing file system
226 object from {\em old} to {\em new}. If the {\em new} object already
227 exists, it is atomically replaced by the {\em old} object. Neither
228 path may refer to an existing directory. A conformant implementation
229 need not support renaming files in all situations (e.g. renaming
230 across different physical devices), but the constraints must be
233 The operation may fail with:
235 \item $HardwareFault$
236 A physical I/O error has occurred.
238 \item $InvalidArgument$
239 Either operand is not a valid file name.
240 [$ENAMETOOLONG$, $ELOOP$]
242 The original file does not exist, or there is no path to the target.
243 [$ENOENT$, $ENOTDIR$]
244 \item $PermissionDenied$
245 The process has insufficient privileges to perform the operation.
246 [$EROFS$, $EACCES$, $EPERM$]
247 \item $ResourceExhausted$
248 Insufficient resources are available to perform the operation.
249 [$EDQUOT$, $ENOSPC$, $ENOMEM$,
251 \item $UnsatisfiedConstraints$
252 Implementation-dependent constraints are not satisfied.
254 \item $UnsupportedOperation$
255 The implementation does not support renaming in this situation.
257 \item $InappropriateType$
258 Either path refers to an existing directory.
259 [$ENOTDIR$, $EISDIR$, $EINVAL$,
260 $EEXIST$, $ENOTEMPTY$]
264 renameFile opath npath =
265 _ccall_ renameFile opath npath `thenIO_Prim` \ rc ->
269 constructErrorAndFail "renameFile"
272 $getDirectoryContents dir$ returns a list of
273 <i>all</i> entries in {\em dir}.
275 The operation may fail with:
277 \item $HardwareFault$
278 A physical I/O error has occurred.
280 \item $InvalidArgument$
281 The operand is not a valid directory name.
282 [$ENAMETOOLONG$, $ELOOP$]
284 The directory does not exist.
285 [$ENOENT$, $ENOTDIR$]
286 \item $PermissionDenied$
287 The process has insufficient privileges to perform the operation.
289 \item $ResourceExhausted$
290 Insufficient resources are available to perform the operation.
292 \item $InappropriateType$
293 The path refers to an existing non-directory object.
298 getDirectoryContents path =
299 _ccall_ getDirectoryContents path `thenIO_Prim` \ ptr ->
300 if ptr == ``NULL'' then
301 constructErrorAndFail "getDirectoryContents"
303 stToIO (getEntries ptr 0) >>= \ entries ->
304 _ccall_ free ptr `thenIO_Prim` \ () ->
307 getEntries :: Addr -> Int -> PrimIO [FilePath]
309 _casm_ ``%r = ((char **)%0)[%1];'' ptr n >>= \ str ->
310 if str == ``NULL'' then
313 _ccall_ strlen str >>= \ len ->
314 packCBytesST len str >>= \ entry ->
315 _ccall_ free str >>= \ () ->
316 getEntries ptr (n+1) >>= \ entries ->
317 return (unpackPS entry : entries)
320 If the operating system has a notion of current directories,
321 $getCurrentDirectory$ returns an absolute path to the
322 current directory of the calling process.
324 The operation may fail with:
326 \item $HardwareFault$
327 A physical I/O error has occurred.
330 There is no path referring to the current directory.
331 [$EPERM$, $ENOENT$, $ESTALE$...]
332 \item $PermissionDenied$
333 The process has insufficient privileges to perform the operation.
335 \item $ResourceExhausted$
336 Insufficient resources are available to perform the operation.
337 \item $UnsupportedOperation$
338 The operating system has no notion of current directory.
342 getCurrentDirectory =
343 _ccall_ getCurrentDirectory `thenIO_Prim` \ str ->
344 if str /= ``NULL'' then
345 _ccall_ strlen str `thenIO_Prim` \ len ->
346 stToIO (packCBytesST len str) >>= \ pwd ->
347 _ccall_ free str `thenIO_Prim` \ () ->
348 return (unpackPS pwd)
350 constructErrorAndFail "getCurrentDirectory"
353 If the operating system has a notion of current directories,
354 $setCurrentDirectory dir$ changes the current
355 directory of the calling process to {\em dir}.
357 The operation may fail with:
359 \item $HardwareFault$
360 A physical I/O error has occurred.
362 \item $InvalidArgument$
363 The operand is not a valid directory name.
364 [$ENAMETOOLONG$, $ELOOP$]
366 The directory does not exist.
367 [$ENOENT$, $ENOTDIR$]
368 \item $PermissionDenied$
369 The process has insufficient privileges to perform the operation.
371 \item $UnsupportedOperation$
372 The operating system has no notion of current directory, or the
373 current directory cannot be dynamically changed.
374 \item $InappropriateType$
375 The path refers to an existing non-directory object.
380 setCurrentDirectory path =
381 _ccall_ setCurrentDirectory path `thenIO_Prim` \ rc ->
385 constructErrorAndFail "setCurrentDirectory"