1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
<title>The Haskell 98 Library Report: Directory functions</title>
<body bgcolor="#ffffff"> <i>The Haskell 98 Library Report</i><br> <a href="index.html">top</a> | <a href="io.html">back</a> | <a href="system.html">next</a> | <a href="libindex.html">contents</a> <br><hr>
<p>
<a name="sect12"></a>
<h2>12<tt> </tt>Directory Functions</h2><p>
<table border=2 cellpadding=3>
<tr><td>
<tt><br>
module Directory ( <br>
Permissions,<br>
readable, writable, executable, searchable, <br>
createDirectory, removeDirectory, removeFile, <br>
renameDirectory, renameFile, getDirectoryContents,<br>
getCurrentDirectory, setCurrentDirectory,<br>
doesFileExist, doesDirectoryExist,<br>
getPermissions, setPermissions,<br>
getModificationTime ) where<br>
<br>
import Time ( ClockTime )<br>
<br>
data Permissions = ... -- Abstract<br>
<br>
instance Eq Permissions where ...<br>
instance Ord Permissions where ...<br>
instance Read Permissions where ...<br>
instance Show Permissions where ...<br>
<br>
readable, writable, executable, searchable :: Permissions -> Bool<br>
<br>
createDirectory :: FilePath -> IO ()<br>
removeDirectory :: FilePath -> IO ()<br>
removeFile :: FilePath -> IO ()<br>
renameDirectory :: FilePath -> FilePath -> IO ()<br>
renameFile :: FilePath -> FilePath -> IO ()<br>
<br>
getDirectoryContents :: FilePath -> IO [FilePath]<br>
getCurrentDirectory :: IO FilePath<br>
setCurrentDirectory :: FilePath -> IO ()<br>
<br>
doesFileExist :: FilePath -> IO Bool<br>
doesDirectoryExist :: FilePath -> IO Bool<br>
<br>
getPermissions :: FilePath -> IO Permissions<br>
setPermissions :: FilePath -> Permissions -> IO ()<br>
<br>
getModificationTime :: FilePath -> IO ClockTime<br>
<br>
</tt></td></tr></table>
<p>
These functions operate on directories in the file system. <p>
Any <tt>Directory</tt> operation could raise an <tt>isIllegalOperationError</tt>, as
described in Section <a href="io.html#IOError">11.1</a>; all other permissible errors are
described below. Note that, in particular, if an implementation does
not support an operation it should raise an <tt>isIllegalOperationError</tt>.<p>
A directory contains a series of entries, each of which is a named
reference to a file system object (file, directory etc.). Some
entries may be hidden, inaccessible, or have some administrative
function (for instance, "." or ".." under POSIX), but all such
entries are considered to form part of the directory contents.
Entries in sub-directories are not, however, considered to form part
of the directory contents. Although there may be
file system objects other than files and directories, this library
does not distinguish between physical files and other non-directory
objects. All such objects should therefore be treated as if they are files.<p>
Each file system object is referenced by a <I>path</I>. There is
normally at least one absolute path to each file system object. In
some operating systems, it may also be possible to have paths which
are relative to the current directory.<p>
Computation <tt>createDirectory</tt> <I>dir</I> creates a new directory <I>dir</I> which is
initially empty, or as near to empty as the operating system allows.<p>
<I>Error reporting</I>:
the <tt>createDirectory</tt> computation may fail with:
<tt>isPermissionError</tt> if the user is not permitted to create the directory;
<tt>isAlreadyExistsError</tt> if the directory already exists.<p>
Computation <tt>removeDirectory</tt> <I>dir</I> removes an existing directory
<I>dir</I>. The
implementation may specify additional constraints which must be
satisfied before a directory can be removed (for instance, the directory has to
be empty, or may not be in use by other processes). It is not legal
for an implementation to partially remove a directory unless the
entire directory is removed. A conformant implementation need not
support directory removal in all situations (for instance, removal of the root
directory).<p>
Computation <tt>removeFile</tt> <I>file</I> removes the directory entry for an existing
file <I>file</I>, where <I>file</I> is not itself a directory. The implementation may specify additional
constraints which must be satisfied before a file can be removed (for instance, the
file may not be in use by other processes).<p>
<I>Error reporting</I>:
the <tt>removeDirectory</tt> and <tt>removeFile</tt> computations may fail with:
<tt>isPermissionError</tt> if the user is not permitted to remove the file/directory;
or <tt>isDoesNot</tt>-<tt>ExistError</tt> if the file/directory does not exist.<p>
Computation <tt>renameDirectory</tt> <I>old</I> <I>new</I> changes the name of an existing
directory from <I>old</I> to <I>new</I>. If the <I>new</I> directory already exists, it is atomically
replaced by the <I>old</I> directory. If the <I>new</I> directory is neither
the <I>old</I> directory nor an alias of the <I>old</I> directory, it is removed
as if by <tt>removeDirectory</tt>. A conformant implementation need not
support renaming directories in all situations (for instance, renaming to an
existing directory, or across different physical devices), but the
constraints must be documented.<p>
Computation <tt>renameFile</tt> <I>old</I> <I>new</I> changes the name of an existing file
system object from <I>old</I> to <I>new</I>.
If the <I>new</I> object already exists, it is atomically replaced by the <I>old
</I>object. Neither path may refer to an existing directory. A conformant
implementation need not support renaming files in all situations
(for instance, renaming across different physical devices), but the constraints must be
documented.<p>
<I>Error reporting</I>:
the <tt>renameDirectory</tt> and <tt>renameFile</tt> computations may fail with:
<tt>isPermissionError</tt> if the user is not permitted to rename the file/directory,
or if either argument to <tt>renameFile</tt> is a directory;
or <tt>isDoesNotExistError</tt> if the file/directory does not exist.<p>
Computation <tt>getDirectoryContents</tt> <I>dir</I> returns a list of <I>all</I> entries
in <I>dir</I>.<p>
If the operating system has a notion of current directories,
<tt>getCurrentDirectory</tt> returns an absolute path to the
current directory of the calling process.<p>
<I>Error reporting</I>:
the <tt>getDirectoryContents</tt> and <tt>getCurrentDirectory</tt> computations may fail with:
<tt>isPermissionError</tt> if the user is not permitted to access the directory;
or <tt>isDoesNotExistError</tt> if the directory does not exist.<p>
If the operating system has a notion of current directories,
<tt>setCurrentDirectory</tt> <I>dir</I> changes the current directory of the
calling process to <I>dir</I>.<p>
<I>Error reporting</I>:
the <tt>setCurrentDirectory</tt> computation may fail with:
<tt>isPermission</tt>-<tt>Error</tt> if the user is not permitted to change directory
to that specified;
or <tt>isDoesNotExist</tt>-<tt>Error</tt> if the directory does not exist.<p>
The <tt>Permissions</tt> type is used to record whether certain operations are
permissible on a file/directory. <tt>getPermissions</tt> and
<tt>setPermissions</tt> get and set these permissions, respectively.
Permissions apply both to files and directories. For
directories, the <tt>executable</tt> field will be <tt>False</tt>, and for files the
<tt>searchable</tt> field will be <tt>False</tt>. Note that directories may be
searchable without being readable, if permission has been given to use
them as part of a path, but not to examine the directory contents.<p>
Note that to change
some, but not all permissions, a construct on the following lines must
be used.
<tt><br>
<br>
makeReadable f = do<br>
p <- getPermissions f<br>
setPermissions f (p {readable = True})<br>
<br>
</tt>The operation <tt>doesDirectoryExist</tt> returns <tt>True</tt> if the argument file
exists and is a directory, and <tt>False</tt> otherwise. The operation <tt>doesFileExist</tt> returns <tt>True
</tt>if the argument file exists and is not a directory, and <tt>False</tt> otherwise.<p>
The <tt>getModificationTime</tt> operation returns the
clock time at which the file/directory was last modified.<p>
<I>Error reporting</I>:
the <tt>get(set)Permissions</tt>,
<tt>doesFile(Directory)Exist</tt>,
and <tt>getMod</tt>-<tt>ificationTime
</tt>computations may fail with:
<tt>isPermissionError</tt> if the user is not permitted to access
the appropriate information;
or <tt>isDoesNotExistError</tt> if the file/directory does not exist.
The <tt>setPermissions
</tt>computation may also fail with:
<tt>isPermissionError</tt> if the user is not permitted to change
the permission for the specified file or directory;
or <tt>isDoesNotExistError</tt> if the file/directory does not exist.<p>
<hr><i>The Haskell 98 Library Report</i><br><a href="index.html">top</a> | <a href="io.html">back</a> | <a href="system.html">next</a> | <a href="libindex.html">contents</a> <br><font size=2>1 February, 1999</font>
<p>
|
