f4acda3fee0254d6f208877fa87255632f4b26cf
[haskell-report.git] / report / directory.verb
1 %**<title>The Haskell 98 Library Report: Directory functions</title>
2 %**~header
3
4 %% Other useful functions from SML 96 include modification time
5 %% and path-testing (is this a full path/real path).
6
7 \section{Directory Functions}
8 \index{directories}
9 \index{the file system}
10
11 \outline{
12 \inputHS{lib-hdrs/Directory}
13 }
14 \indextt{createDirectory}\indextt{removeDirectory}\indextt{removeFile}
15 \indextt{renameDirectory}\indextt{renameFile}
16 \indextt{getDirectoryContents}\indextt{getCurrentDirectory}
17 \indextt{setCurrentDirectory}
18
19 These functions operate on directories in the file system.  
20
21 Any @Directory@ operation could raise an @isIllegalOperation@, as
22 described in Section~\ref{IOError}; all other permissible errors are
23 described below.  Note that, in particular, if an implementation does
24 not support an operation it should raise an @isIllegalOperation@.
25 A directory contains a series of entries, each of which is a named
26 reference to a file system object (file, directory etc.).  Some
27 entries may be hidden, inaccessible, or have some administrative
28 function (for instance, ``.'' or ``..'' under POSIX), but all such
29 entries are considered to form part of the directory contents.
30 Entries in sub-directories are not, however, considered to form part
31 of the directory contents.  Although there may be
32 file system objects other than files and directories, this library
33 does not distinguish between physical files and other non-directory
34 objects.  All such objects should therefore be treated as if they are files.
35
36 Each file system object is referenced by a {\it path}\index{path}.  There is
37 normally at least one absolute path to each file system object.  In
38 some operating systems, it may also be possible to have paths which
39 are relative to the current directory.
40
41 Computation @createDirectory@~"dir" creates a new directory "dir" which is
42 initially empty, or as near to empty as the operating system allows.
43 \index{making directories}
44
45 {\em Error~reporting}.
46 The @createDirectory@ computation may fail with:
47 @isPermissionError@ if the user is not permitted to create the directory;
48 @isAlreadyExistsError@ if the directory already exists; or @isDoesNotExistError@ if
49 the new directory's parent does not exist.
50
51 Computation @removeDirectory@~"dir" removes an existing directory
52 "dir"\index{deleting directories}\index{removing directories}.  The
53 implementation may specify additional constraints which must be
54 satisfied before a directory can be removed (for instance, the directory has to
55 be empty, or may not be in use by other processes).  It is not legal
56 for an implementation to partially remove a directory unless the
57 entire directory is removed. A conformant implementation need not
58 support directory removal in all situations (for instance, removal of the root
59 directory).
60
61 Computation @removeFile@~"file" removes the directory entry for an existing
62 file "file", where "file" is not itself a directory\index{deleting
63 files}\index{removing files}. The implementation may specify additional
64 constraints which must be satisfied before a file can be removed (for instance, the
65 file may not be in use by other processes).
66
67 {\em Error~reporting}.
68 The @removeDirectory@ and @removeFile@ computations may fail with:
69 @isPermissionError@ if the user is not permitted to remove the file/directory;
70 or @isDoesNotExistError@ if the file/directory does not exist.
71
72 Computation @renameDirectory@~"old"~"new" changes the name of an existing
73 directory from "old" to "new"\index{renaming directories}\index{moving
74 directories}.  If the "new" directory already exists, it is atomically
75 replaced by the "old" directory.  If the "new" directory is neither
76 the "old" directory nor an alias of the "old" directory, it is removed
77 as if by @removeDirectory@.  A conformant implementation need not
78 support renaming directories in all situations (for instance, renaming to an
79 existing directory, or across different physical devices), but the
80 constraints must be documented.
81
82 Computation @renameFile@~"old"~"new" changes the name of an existing file
83 system object from "old" to "new"\index{renaming files}\index{moving files}.
84 If the "new" object already exists, it is atomically replaced by the "old"
85 object.  Neither path may refer to an existing directory.  A conformant
86 implementation need not support renaming files in all situations
87 (for instance, renaming across different physical devices), but the constraints must be
88 documented.
89
90 {\em Error~reporting}.
91 The @renameDirectory@ and @renameFile@ computations may fail with:
92 @isPermissionError@ if the user is not permitted to rename the file/directory,
93 or if either argument to @renameFile@ is a directory;
94 or @isDoesNotExistError@ if the file/directory does not exist.
95
96 Computation @getDirectoryContents@~"dir" returns a list of {\em all} entries
97 in "dir"\index{reading a directory}.
98 Each entry in the returned list is named relative to the directory "dir", not as an absolute path.
99
100 If the operating system has a notion of current directories,
101 @getCurrentDirectory@ returns an absolute path to the
102 current directory of the calling process\index{current directory}.
103
104 {\em Error~reporting}.
105 The @getDirectoryContents@ and @getCurrentDirectory@ computations may fail with:
106 @isPermissionError@ if the user is not permitted to access the directory;
107 or @isDoesNotExistError@ if the directory does not exist.
108
109 If the operating system has a notion of current directories,
110 @setCurrentDirectory@~"dir" changes the current directory of the
111 calling process to "dir"\index{changing the directory}\index{setting the directory}.
112
113 {\em Error~reporting}.
114 @setCurrentDirectory@ may fail with:
115 @isPermissionError@ if the user is not permitted to change directory
116 to that specified;
117 or @isDoesNotExistError@ if the directory does not exist.
118
119 The @Permissions@ type is used to record whether certain operations are
120 permissible on a file/directory.  @getPermissions@ and
121 @setPermissions@ get and set these permissions, respectively.  
122 Permissions apply both to files and directories.  For
123 directories, the @executable@ field will be @False@, and for files the
124 @searchable@ field will be @False@.  Note that directories may be
125 searchable without being readable, if permission has been given to use
126 them as part of a path, but not to examine the directory contents.
127
128 Note that to change
129 some, but not all permissions, a construct on the following lines must
130 be used.  
131 \bprog
132 @
133 makeReadable f = do
134                     p <- getPermissions f
135                     setPermissions f (p {readable = True})
136 @
137 \eprog
138 The operation @doesDirectoryExist@ returns @True@ if the argument file
139 exists and is a directory, and @False@ otherwise. The operation @doesFileExist@ returns @True@
140 if the argument file exists and is not a directory, and @False@ otherwise.
141
142 The @getModificationTime@ operation returns the
143 clock time at which the file/directory was last modified.
144
145 {\em Error~reporting}.
146 @get(set)Permissions@,
147 @doesFile(Directory)Exist@,
148 and @getModificationTime@
149 may fail with:
150 @isPermissionError@ if the user is not permitted to access
151 the appropriate information;
152 or @isDoesNotExistError@ if the file/directory does not exist.
153 The @setPermissions@
154 computation may also fail with:
155 @isPermissionError@ if the user is not permitted to change
156 the permission for the specified file or directory;
157 or @isDoesNotExistError@ if the file/directory does not exist.
158 % Duplicates the first case above, and would require
159 % extensive consistency checking throughout. KH
160 % The @doesFileExist@ and @doesDirectoryExist@ computations
161 % may also fail with @isPermissionError@ if some part of the path
162 % to the file/directory cannot be searched.
163
164 %**~footer
165