2 LuCI - Filesystem tools
5 A module offering often needed filesystem manipulation functions
11 Copyright 2008 Steven Barth <steven@midlink.org>
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
17 http://www.apache.org/licenses/LICENSE-2.0
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.
27 local io = require "io"
28 local os = require "os"
29 local ltn12 = require "luci.ltn12"
30 local posix = require "posix"
34 --- LuCI filesystem library.
37 --- Test for file access permission on given path.
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)
46 --- Evaluate given shell glob pattern and return a table containing all matching
47 -- file and directory entries.
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)
56 --- Checks wheather the given path exists and points to a regular file.
57 -- @param filename String containing the path of the file to test
58 -- @return Boolean indicating wheather given path points to regular file
59 function isfile(filename)
60 return posix.stat(filename, "type") == "regular"
63 --- Checks wheather the given path exists and points to a directory.
64 -- @param dirname String containing the path of the directory to test
65 -- @return Boolean indicating wheather given path points to directory
66 function isdirectory(dirname)
67 return posix.stat(dirname, "type") == "directory"
70 --- Read the whole content of the given file into memory.
71 -- @param filename String containing the path of the file to read
72 -- @return String containing the file contents or nil on error
73 -- @return String containing the error message on error
74 function readfile(filename)
75 local fp, err = io.open(filename)
81 local data = fp:read("*a")
86 --- Write the contents of given string to given file.
87 -- @param filename String containing the path of the file to read
88 -- @param data String containing the data to write
89 -- @return Boolean containing true on success or nil on error
90 -- @return String containing the error message on error
91 function writefile(filename, data)
92 local fp, err = io.open(filename, "w")
105 -- @param source Source file
106 -- @param dest Destination
107 -- @return Boolean containing true on success or nil on error
108 function copy(source, dest)
109 return ltn12.pump.all(
110 ltn12.source.file(io.open(source)),
111 ltn12.sink.file(io.open(dest, "w"))
116 -- @param source Source file
117 -- @param dest Destination
118 -- @return Boolean containing true on success or nil on error
119 function rename(source, dest)
120 local stat, err, code = os.rename(source, dest)
122 stat, err, code = copy(source, dest)
124 stat, err, code = unlink(source)
127 return stat, err, code
130 --- Get the last modification time of given file path in Unix epoch format.
131 -- @param path String containing the path of the file or directory to read
132 -- @return Number containing the epoch time or nil on error
133 -- @return String containing the error description (if any)
134 -- @return Number containing the os specific errno (if any)
136 return posix.stat(path, "mtime")
139 --- Return the last element - usually the filename - from the given path with
140 -- the directory component stripped.
143 -- @param path String containing the path to strip
144 -- @return String containing the base name of given path
146 basename = posix.basename
148 --- Return the directory component of the given path with the last element
152 -- @param path String containing the path to strip
153 -- @return String containing the directory component of given path
155 dirname = posix.dirname
157 --- Return a table containing all entries of the specified directory.
160 -- @param path String containing the path of the directory to scan
161 -- @return Table containing file and directory entries or nil on error
162 -- @return String containing the error description on error
163 -- @return Number containing the os specific errno on error
166 --- Create a new directory, recursively on demand.
167 -- @param path String with the name or path of the directory to create
168 -- @param recursive Create multiple directory levels (optional, default is true)
169 -- @return Number with the return code, 0 on sucess or nil on error
170 -- @return String containing the error description on error
171 -- @return Number containing the os specific errno on error
172 function mkdir(path, recursive)
176 if path:sub(1,1) == "/" then
178 path = path:gsub("^/+","")
181 for elem in path:gmatch("([^/]+)/*") do
182 base = base .. "/" .. elem
184 local stat = posix.stat( base )
187 local stat, errmsg, errno = posix.mkdir( base )
189 if type(stat) ~= "number" or stat ~= 0 then
190 return stat, errmsg, errno
193 if stat.type ~= "directory" then
194 return nil, base .. ": File exists", 17
201 return posix.mkdir( path )
205 --- Remove the given empty directory.
208 -- @param path String containing the path of the directory to remove
209 -- @return Number with the return code, 0 on sucess or nil on error
210 -- @return String containing the error description on error
211 -- @return Number containing the os specific errno on error
214 --- Get information about given file or directory.
217 -- @param path String containing the path of the directory to query
218 -- @return Table containing file or directory properties or nil on error
219 -- @return String containing the error description on error
220 -- @return Number containing the os specific errno on error
223 --- Set permissions on given file or directory.
226 -- @param path String containing the path of the directory
227 -- @param perm String containing the permissions to set ([ugoa][+-][rwx])
228 -- @return Number with the return code, 0 on sucess or nil on error
229 -- @return String containing the error description on error
230 -- @return Number containing the os specific errno on error
233 --- Create a hard- or symlink from given file (or directory) to specified target
234 -- file (or directory) path.
237 -- @param path1 String containing the source path to link
238 -- @param path2 String containing the destination path for the link
239 -- @param symlink Boolean indicating wheather to create a symlink (optional)
240 -- @return Number with the return code, 0 on sucess or nil on error
241 -- @return String containing the error description on error
242 -- @return Number containing the os specific errno on error
245 --- Remove the given file.
248 -- @param path String containing the path of the file to remove
249 -- @return Number with the return code, 0 on sucess or nil on error
250 -- @return String containing the error description on error
251 -- @return Number containing the os specific errno on error
252 unlink = posix.unlink
254 --- Retrieve target of given symlink.
257 -- @param path String containing the path of the symlink to read
258 -- @return String containing the link target or nil on error
259 -- @return String containing the error description on error
260 -- @return Number containing the os specific errno on error
261 readlink = posix.readlink