Remove luci.cutil: does not affect performance
[project/luci.git] / libs / core / luasrc / fs.lua
1 --[[
2 LuCI - Filesystem tools
3
4 Description:
5 A module offering often needed filesystem manipulation functions
6
7 FileId:
8 $Id$
9
10 License:
11 Copyright 2008 Steven Barth <steven@midlink.org>
12
13 Licensed under the Apache License, Version 2.0 (the "License");
14 you may not use this file except in compliance with the License.
15 You may obtain a copy of the License at
16
17         http://www.apache.org/licenses/LICENSE-2.0
18
19 Unless required by applicable law or agreed to in writing, software
20 distributed under the License is distributed on an "AS IS" BASIS,
21 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
22 See the License for the specific language governing permissions and
23 limitations under the License.
24
25 ]]--
26
27 local io    = require "io"
28 local os    = require "os"
29 local ltn12 = require "luci.ltn12"
30 local posix = require "posix"
31
32 local type  = type
33
34 --- LuCI filesystem library.
35 module "luci.fs"
36
37 --- Test for file access permission on given path.
38 -- @class               function
39 -- @name                access
40 -- @param str   String value containing the path
41 -- @return              Number containing the return code, 0 on sucess or nil on error
42 -- @return              String containing the error description (if any)
43 -- @return              Number containing the os specific errno (if any)
44 access = posix.access
45
46 --- Evaluate given shell glob pattern and return a table containing all matching
47 -- file and directory entries.
48 -- @class                       function
49 -- @name                        glob
50 -- @param filename      String containing the path of the file to read
51 -- @return                      Table containing file and directory entries or nil if no matches
52 -- @return                      String containing the error description (if no matches)
53 -- @return                      Number containing the os specific errno (if no matches)
54 glob = posix.glob
55
56 --- Checks wheather the given path exists and points to a regular file.
57 -- @param filename      String containing the path of the file to read
58 -- @return                      Boolean indicating wheather given path points to regular file
59 function isfile(filename)
60         return posix.stat(filename, "type") == "regular"
61 end
62
63 --- Read the whole content of the given file into memory.
64 -- @param filename      String containing the path of the file to read
65 -- @return                      String containing the file contents or nil on error
66 -- @return                      String containing the error message on error
67 function readfile(filename)
68         local fp, err = io.open(filename)
69
70         if fp == nil then
71                 return nil, err
72         end
73
74         local data = fp:read("*a")
75         fp:close()
76         return data
77 end
78
79 --- Write the contents of given string to given file.
80 -- @param filename      String containing the path of the file to read
81 -- @param data          String containing the data to write
82 -- @return                      Boolean containing true on success or nil on error
83 -- @return                      String containing the error message on error
84 function writefile(filename, data)
85         local fp, err = io.open(filename, "w")
86
87         if fp == nil then
88                 return nil, err
89         end
90
91         fp:write(data)
92         fp:close()
93
94         return true
95 end
96
97 --- Copies a file.
98 -- @param source        Source file
99 -- @param dest          Destination
100 -- @return                      Boolean containing true on success or nil on error
101 function copy(source, dest)
102         return ltn12.pump.all(
103                 ltn12.source.file(io.open(source)),
104                 ltn12.sink.file(io.open(dest, "w"))
105         )
106 end
107
108 --- Renames a file.
109 -- @param source        Source file
110 -- @param dest          Destination
111 -- @return                      Boolean containing true on success or nil on error
112 function rename(source, dest)
113         local stat, err, code = os.rename(source, dest)
114         if code == 18 then
115                 stat, err, code = copy(source, dest)
116                 if stat then
117                         stat, err, code = unlink(source)
118                 end
119         end
120         return stat, err, code
121 end
122
123 --- Get the last modification time of given file path in Unix epoch format.
124 -- @param path  String containing the path of the file or directory to read
125 -- @return              Number containing the epoch time or nil on error
126 -- @return              String containing the error description (if any)
127 -- @return              Number containing the os specific errno (if any)
128 function mtime(path)
129         return posix.stat(path, "mtime")
130 end
131
132 --- Return the last element - usually the filename - from the given path with
133 -- the directory component stripped.
134 -- @class               function
135 -- @name                basename
136 -- @param path  String containing the path to strip
137 -- @return              String containing the base name of given path
138 -- @see                 dirname
139 basename = posix.basename
140
141 --- Return the directory component of the given path with the last element
142 -- stripped of.
143 -- @class               function
144 -- @name                dirname
145 -- @param path  String containing the path to strip
146 -- @return              String containing the directory component of given path
147 -- @see                 basename
148 dirname = posix.dirname
149
150 --- Return a table containing all entries of the specified directory.
151 -- @class               function
152 -- @name                dir
153 -- @param path  String containing the path of the directory to scan
154 -- @return              Table containing file and directory entries or nil on error
155 -- @return              String containing the error description on error
156 -- @return              Number containing the os specific errno on error
157 dir = posix.dir
158
159 --- Create a new directory, recursively on demand.
160 -- @param path          String with the name or path of the directory to create
161 -- @param recursive     Create multiple directory levels (optional, default is true)
162 -- @return                      Number with the return code, 0 on sucess or nil on error
163 -- @return                      String containing the error description on error
164 -- @return                      Number containing the os specific errno on error
165 function mkdir(path, recursive)
166         if recursive then
167                 local base = "."
168
169                 if path:sub(1,1) == "/" then
170                         base = ""
171                         path = path:gsub("^/+","")
172                 end
173
174                 for elem in path:gmatch("([^/]+)/*") do
175                         base = base .. "/" .. elem
176
177                         local stat = posix.stat( base )
178
179                         if not stat then
180                                 local stat, errmsg, errno = posix.mkdir( base )
181
182                                 if type(stat) ~= "number" or stat ~= 0 then
183                                         return stat, errmsg, errno
184                                 end
185                         else
186                                 if stat.type ~= "directory" then
187                                         return nil, base .. ": File exists", 17
188                                 end
189                         end
190                 end
191
192                 return 0
193         else
194                 return posix.mkdir( path )
195         end
196 end
197
198 --- Remove the given empty directory.
199 -- @class               function
200 -- @name                rmdir
201 -- @param path  String containing the path of the directory to remove
202 -- @return              Number with the return code, 0 on sucess or nil on error
203 -- @return              String containing the error description on error
204 -- @return              Number containing the os specific errno on error
205 rmdir = posix.rmdir
206
207 --- Get information about given file or directory.
208 -- @class               function
209 -- @name                stat
210 -- @param path  String containing the path of the directory to query
211 -- @return              Table containing file or directory properties or nil on error
212 -- @return              String containing the error description on error
213 -- @return              Number containing the os specific errno on error
214 stat = posix.stat
215
216 --- Set permissions on given file or directory.
217 -- @class               function
218 -- @name                chmod
219 -- @param path  String containing the path of the directory
220 -- @param perm  String containing the permissions to set ([ugoa][+-][rwx])
221 -- @return              Number with the return code, 0 on sucess or nil on error
222 -- @return              String containing the error description on error
223 -- @return              Number containing the os specific errno on error
224 chmod = posix.chmod
225
226 --- Create a hard- or symlink from given file (or directory) to specified target
227 -- file (or directory) path.
228 -- @class                       function
229 -- @name                        link
230 -- @param path1         String containing the source path to link
231 -- @param path2         String containing the destination path for the link
232 -- @param symlink       Boolean indicating wheather to create a symlink (optional)
233 -- @return                      Number with the return code, 0 on sucess or nil on error
234 -- @return                      String containing the error description on error
235 -- @return                      Number containing the os specific errno on error
236 link = posix.link
237
238 --- Remove the given file.
239 -- @class               function
240 -- @name                unlink
241 -- @param path  String containing the path of the file to remove
242 -- @return              Number with the return code, 0 on sucess or nil on error
243 -- @return              String containing the error description on error
244 -- @return              Number containing the os specific errno on error
245 unlink = posix.unlink
246
247 --- Retrieve target of given symlink.
248 -- @class               function
249 -- @name                readlink
250 -- @param path  String containing the path of the symlink to read
251 -- @return              String containing the link target or nil on error
252 -- @return              String containing the error description on error
253 -- @return              Number containing the os specific errno on error
254 readlink = posix.readlink