nixio.fs.lua 7.7 KB

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