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 read
58 -- @return Boolean indicating wheather given path points to regular file
59 function isfile(filename)
60 return posix.stat(filename, "type") == "regular"
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)
74 local data = fp:read("*a")
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")
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"))
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)
115 stat, err, code = copy(source, dest)
117 stat, err, code = unlink(source)
120 return stat, err, code
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)
129 return posix.stat(path, "mtime")
132 --- Return the last element - usually the filename - from the given path with
133 -- the directory component stripped.
136 -- @param path String containing the path to strip
137 -- @return String containing the base name of given path
139 basename = posix.basename
141 --- Return the directory component of the given path with the last element
145 -- @param path String containing the path to strip
146 -- @return String containing the directory component of given path
148 dirname = posix.dirname
150 --- Return a table containing all entries of the specified directory.
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
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)
169 if path:sub(1,1) == "/" then
171 path = path:gsub("^/+","")
174 for elem in path:gmatch("([^/]+)/*") do
175 base = base .. "/" .. elem
177 local stat = posix.stat( base )
180 local stat, errmsg, errno = posix.mkdir( base )
182 if type(stat) ~= "number" or stat ~= 0 then
183 return stat, errmsg, errno
186 if stat.type ~= "directory" then
187 return nil, base .. ": File exists", 17
194 return posix.mkdir( path )
198 --- Remove the given empty directory.
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
207 --- Get information about given file or directory.
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
216 --- Set permissions on given file or directory.
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
226 --- Create a hard- or symlink from given file (or directory) to specified target
227 -- file (or directory) path.
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
238 --- Remove the given file.
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
247 --- Retrieve target of given symlink.
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