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 --- LuCI filesystem library.
28 module("luci.fs", package.seeall)
32 --- Test for file access permission on given path.
35 -- @param str String value containing the path
36 -- @return Number containing the return code, 0 on sucess or nil on error
37 -- @return String containing the error description (if any)
38 -- @return Number containing the os specific errno (if any)
41 --- Evaluate given shell glob pattern and return a table containing all matching
42 -- file and directory entries.
45 -- @param filename String containing the path of the file to read
46 -- @return Table containing file and directory entries or nil if no matches
47 -- @return String containing the error description (if no matches)
48 -- @return Number containing the os specific errno (if no matches)
51 --- Checks wheather the given path exists and points to a regular file.
52 -- @param filename String containing the path of the file to read
53 -- @return Boolean indicating wheather given path points to regular file
54 function isfile(filename)
55 return posix.stat(filename, "type") == "regular"
58 --- Read the whole content of the given file into memory.
59 -- @param filename String containing the path of the file to read
60 -- @return String containing the file contents or nil on error
61 -- @return String containing the error message on error
62 function readfile(filename)
63 local fp, err = io.open(filename)
69 local data = fp:read("*a")
74 --- Write the contents of given string to given file.
75 -- @param filename String containing the path of the file to read
76 -- @param data String containing the data to write
77 -- @return Boolean containing true on success or nil on error
78 -- @return String containing the error message on error
79 function writefile(filename, data)
80 local fp, err = io.open(filename, "w")
92 --- Get the last modification time of given file path in Unix epoch format.
93 -- @param path String containing the path of the file or directory to read
94 -- @return Number containing the epoch time or nil on error
95 -- @return String containing the error description (if any)
96 -- @return Number containing the os specific errno (if any)
98 return posix.stat(path, "mtime")
101 --- Return the last element - usually the filename - from the given path with
102 -- the directory component stripped.
105 -- @param path String containing the path to strip
106 -- @return String containing the base name of given path
108 basename = posix.basename
110 --- Return the directory component of the given path with the last element
114 -- @param path String containing the path to strip
115 -- @return String containing the directory component of given path
117 dirname = posix.dirname
119 --- Return a table containing all entries of the specified directory.
122 -- @param path String containing the path of the directory to scan
123 -- @return Table containing file and directory entries or nil on error
124 -- @return String containing the error description on error
125 -- @return Number containing the os specific errno on error
128 --- Create a new directory, recursively on demand.
129 -- @param path String with the name or path of the directory to create
130 -- @param recursive Create multiple directory levels (optional, default is true)
131 -- @return Number with the return code, 0 on sucess or nil on error
132 -- @return String containing the error description on error
133 -- @return Number containing the os specific errno on error
134 function mkdir(path, recursive)
138 if path:sub(1,1) == "/" then
140 path = path:gsub("^/+","")
143 for elem in path:gmatch("([^/]+)/*") do
144 base = base .. "/" .. elem
146 local stat = posix.stat( base )
149 local stat, errmsg, errno = posix.mkdir( base )
151 if type(stat) ~= "number" or stat ~= 0 then
152 return stat, errmsg, errno
155 if stat.type ~= "directory" then
156 return nil, base .. ": File exists", 17
163 return posix.mkdir( path )
167 --- Remove the given empty directory.
170 -- @param path String containing the path of the directory to remove
171 -- @return Number with the return code, 0 on sucess or nil on error
172 -- @return String containing the error description on error
173 -- @return Number containing the os specific errno on error
176 --- Get information about given file or directory.
179 -- @param path String containing the path of the directory to query
180 -- @return Table containing file or directory properties or nil on error
181 -- @return String containing the error description on error
182 -- @return Number containing the os specific errno on error
185 --- Set permissions on given file or directory.
188 -- @param path String containing the path of the directory
189 -- @param perm String containing the permissions to set ([ugoa][+-][rwx])
190 -- @return Number with the return code, 0 on sucess or nil on error
191 -- @return String containing the error description on error
192 -- @return Number containing the os specific errno on error
195 --- Create a hardlink from given file to specified target file path.
198 -- @param path1 String containing the source path of a file to hardlink
199 -- @param path2 String containing the destination path for the link
200 -- @return Number with the return code, 0 on sucess or nil on error
201 -- @return String containing the error description on error
202 -- @return Number containing the os specific errno on error
205 --- Remove the given file.
208 -- @param path String containing the path of the file 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
212 unlink = posix.unlink