libs/luci-lib-nixio/docsrc/nixio.fs.lua

   1 --- Low-level and high-level filesystem manipulation library.
   2 module "nixio.fs"
   3
   4
   5 --- Check user's permission on a file.
   6 -- @class function
   7 -- @name nixio.fs.access
   8 -- @param path          Path
   9 -- @param mode1         First Mode to check ["f", "r", "w", "x"]
  10 -- @param ...           More Modes to check     [-"-]
  11 -- @return      true
  12
  13 --- Strip the directory part from a path.
  14 -- @class function
  15 -- @name nixio.fs.basename
  16 -- @usage       This function cannot fail and will never return nil.
  17 -- @param       path Path
  18 -- @return      basename
  19
  20 --- Strip the base from a path.
  21 -- @class function
  22 -- @name nixio.fs.dirname
  23 -- @usage       This function cannot fail and will never return nil.
  24 -- @param       path Path
  25 -- @return      dirname
  26
  27 --- Return the cannonicalized absolute pathname.
  28 -- @class function
  29 -- @name nixio.fs.realpath
  30 -- @param       path Path
  31 -- @return      absolute path
  32
  33 --- Remove a file or directory.
  34 -- @class function
  35 -- @name nixio.fs.remove
  36 -- @param       path Path
  37 -- @return      true
  38
  39 --- Delete a name and - if no links are left - the associated file.
  40 -- @class function
  41 -- @name nixio.fs.unlink
  42 -- @param       path Path
  43 -- @return      true
  44
  45 --- Renames a file or directory.
  46 -- @class function
  47 -- @name nixio.fs.rename
  48 -- @param       src     Source path
  49 -- @param       dest Destination path
  50 -- @usage       It is normally not possible to rename files accross filesystems.
  51 -- @return      true
  52
  53 --- Remove an empty directory.
  54 -- @class function
  55 -- @name nixio.fs.rmdir
  56 -- @param       path Path
  57 -- @return      true
  58
  59 --- Create a new directory.
  60 -- @class function
  61 -- @name nixio.fs.mkdir
  62 -- @param       path Path
  63 -- @param       mode File mode (optional, see chmod and umask)
  64 -- @see nixio.fs.chmod
  65 -- @see nixio.umask
  66 -- @return      true
  67
  68 --- Change the file mode.
  69 -- @class function
  70 -- @name        nixio.fs.chmod
  71 -- @usage       Windows only supports setting the write-protection through the
  72 -- "Writable to others" bit.
  73 -- @usage       <strong>Notice:</strong> The mode-flag for the functions
  74 -- open, mkdir, mkfifo are affected by the umask.
  75 -- @param       path Path
  76 -- @param       mode File mode
  77 -- [decimal mode number, "[-r][-w][-xsS][-r][-w][-xsS][-r][-w][-xtT]"]
  78 -- @see nixio.umask
  79 -- @return true
  80
  81 --- Iterate over the entries of a directory.
  82 -- @class function
  83 -- @name nixio.fs.dir
  84 -- @usage       The special entries "." and ".." are omitted.
  85 -- @param       path Path
  86 -- @return      directory iterator returning one entry per call
  87
  88 --- Create a hard link.
  89 -- @class function
  90 -- @name nixio.fs.link
  91 -- @usage This function calls link() on POSIX and CreateHardLink() on Windows.
  92 -- @param       oldpath Path
  93 -- @param       newpath Path
  94 -- @return      true
  95
  96 --- Change file last access and last modification time.
  97 -- @class function
  98 -- @name nixio.fs.utimes
  99 -- @param       path Path
 100 -- @param       actime Last access timestamp    (optional, default: current time)
 101 -- @param       mtime Last modification timestamp (optional, default: actime)
 102 -- @return      true
 103
 104 --- Get file status and attributes.
 105 -- @class function
 106 -- @name nixio.fs.stat
 107 -- @param       path    Path
 108 -- @param       field   Only return a specific field, not the whole table (optional)
 109 -- @return      Table containing: <ul>
 110 -- <li>atime = Last access timestamp</li>
 111 -- <li>blksize = Blocksize (POSIX only)</li>
 112 -- <li>blocks = Blocks used (POSIX only)</li>
 113 -- <li>ctime = Creation timestamp</li>
 114 -- <li>dev = Device ID</li>
 115 -- <li>gid = Group ID</li>
 116 -- <li>ino = Inode</li>
 117 -- <li>modedec = Mode converted into a decimal number</li>
 118 -- <li>modestr = Mode as string as returned by `ls -l`</li>
 119 -- <li>mtime = Last modification timestamp</li>
 120 -- <li>nlink = Number of links</li>
 121 -- <li>rdev = Device ID (if special file)</li>
 122 -- <li>size = Size in bytes</li>
 123 -- <li>type = ["reg", "dir", "chr", "blk", "fifo", "lnk", "sock"]</li>
 124 -- <li>uid = User ID</li>
 125 -- </ul>
 126
 127 --- Get file status and attributes and do not resolve if target is a symlink.
 128 -- @class function
 129 -- @name nixio.fs.lstat
 130 -- @param       path    Path
 131 -- @param       field   Only return a specific field, not the whole table (optional)
 132 -- @see nixio.fs.stat
 133 -- @return Table containing attributes (see stat for a detailed description)
 134
 135 --- (POSIX) Change owner and group of a file.
 136 -- @class function
 137 -- @name nixio.fs.chown
 138 -- @param       path    Path
 139 -- @param       user    User ID or Username             (optional)
 140 -- @param       group   Group ID or Groupname   (optional)
 141 -- @return true
 142
 143 --- (POSIX) Change owner and group of a file and do not resolve
 144 -- if target is a symlink.
 145 -- @class function
 146 -- @name nixio.fs.lchown
 147 -- @param       path    Path
 148 -- @param       user    User ID or Username             (optional)
 149 -- @param       group   Group ID or Groupname   (optional)
 150 -- @return true
 151
 152 --- (POSIX) Create a FIFO (named pipe).
 153 -- @class function
 154 -- @name nixio.fs.mkfifo
 155 -- @param       path Path
 156 -- @param       mode File mode (optional, see chmod and umask)
 157 -- @see nixio.fs.chmod
 158 -- @see nixio.umask
 159 -- @return      true
 160
 161 --- (POSIX) Create a symbolic link.
 162 -- @class function
 163 -- @name nixio.fs.symlink
 164 -- @param       oldpath Path
 165 -- @param       newpath Path
 166 -- @return      true
 167
 168 --- (POSIX) Read the target of a symbolic link.
 169 -- @class function
 170 -- @name nixio.fs.readlink
 171 -- @param       path Path
 172 -- @return      target path
 173
 174 --- (POSIX) Find pathnames matching a pattern.
 175 -- @class function
 176 -- @name nixio.fs.glob
 177 -- @param       pattern Pattern
 178 -- @return      path iterator
 179 -- @return      number of matches
 180
 181 --- (POSIX) Get filesystem statistics.
 182 -- @class function
 183 -- @name nixio.fs.statvfs
 184 -- @param       path Path to any file within the filesystem.
 185 -- @return      Table containing: <ul>
 186 -- <li>bavail = available blocks</li>
 187 -- <li>bfree = free blocks</li>
 188 -- <li>blocks = number of fragments</li>
 189 -- <li>frsize = fragment size</li>
 190 -- <li>favail = available inodes</li>
 191 -- <li>ffree = free inodes</li>
 192 -- <li>files = inodes</li>
 193 -- <li>flag = flags</li>
 194 -- <li>fsid = filesystem ID</li>
 195 -- <li>namemax = maximum filename length</li>
 196 -- </ul>
 197
 198 --- Read the contents of a file into a buffer.
 199 -- @class function
 200 -- @name nixio.fs.readfile
 201 -- @param       path Path
 202 -- @param       limit   Maximum bytes to read (optional)
 203 -- @return      file contents
 204
 205 --- Write a buffer into a file truncating the file first.
 206 -- @class function
 207 -- @name nixio.fs.writefile
 208 -- @param       path Path
 209 -- @param       data Data to write
 210 -- @return      true
 211
 212 --- Copy data between files.
 213 -- @class function
 214 -- @name nixio.fs.datacopy
 215 -- @param       src     Source file path
 216 -- @param       dest Destination file path
 217 -- @param       limit   Maximum bytes to copy (optional)
 218 -- @return      true
 219
 220 --- Copy a file, directory or symlink non-recursively preserving file mode,
 221 -- timestamps, owner and group.
 222 -- @class function
 223 -- @name nixio.fs.copy
 224 -- @usage       The destination must always be a full destination path e.g. do not
 225 -- omit the basename even if source and destination basename are equal.
 226 -- @param       src     Source path
 227 -- @param       dest Destination path
 228 -- @return      true
 229
 230 --- Rename a file, directory or symlink non-recursively across filesystems.
 231 -- @class function
 232 -- @name nixio.fs.move
 233 -- @usage       The destination must always be a full destination path e.g. do not
 234 -- omit the basename even if source and destination basename are equal.
 235 -- @param       src     Source path
 236 -- @param       dest Destination path
 237 -- @return      true
 238
 239 --- Create a directory and all needed parent directories recursively.
 240 -- @class function
 241 -- @name nixio.fs.mkdirr
 242 -- @param       dest Destination path
 243 -- @param       mode File mode (optional, see chmod and umask)
 244 -- @see nixio.fs.chmod
 245 -- @see nixio.umask
 246 -- @return      true
 247
 248 --- Rename a file, directory or symlink recursively across filesystems.
 249 -- @class function
 250 -- @name nixio.fs.mover
 251 -- @usage       The destination must always be a full destination path e.g. do not
 252 -- omit the basename even if source and destination basename are equal.
 253 -- @param       src     Source path
 254 -- @param       dest Destination path
 255 -- @return      true
 256
 257 --- Copy a file, directory or symlink recursively preserving file mode,
 258 -- timestamps, owner and group.
 259 -- @class function
 260 -- @name nixio.fs.copyr
 261 -- @usage       The destination must always be a full destination path e.g. do not
 262 -- omit the basename even if source and destination basename are equal.
 263 -- @param       src     Source path
 264 -- @param       dest Destination path
 265 -- @return      true