nixio.File.lua 4.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109
  1. --- Large File Object.
  2. -- Large file operations are supported up to 52 bits if the Lua number type is
  3. -- double (default).
  4. -- @cstyle instance
  5. module "nixio.File"
  6. --- Write to the file descriptor.
  7. -- @class function
  8. -- @name File.write
  9. -- @usage <strong>Warning:</strong> It is not guaranteed that all data
  10. -- in the buffer is written at once especially when dealing with pipes.
  11. -- You have to check the return value - the number of bytes actually written -
  12. -- or use the safe IO functions in the high-level IO utility module.
  13. -- @usage Unlike standard Lua indexing the lowest offset and default is 0.
  14. -- @param buffer Buffer holding the data to be written.
  15. -- @param offset Offset to start reading the buffer from. (optional)
  16. -- @param length Length of chunk to read from the buffer. (optional)
  17. -- @return number of bytes written
  18. --- Read from a file descriptor.
  19. -- @class function
  20. -- @name File.read
  21. -- @usage <strong>Warning:</strong> It is not guaranteed that all requested data
  22. -- is read at once especially when dealing with pipes.
  23. -- You have to check the return value - the length of the buffer actually read -
  24. -- or use the safe IO functions in the high-level IO utility module.
  25. -- @usage The length of the return buffer is limited by the (compile time)
  26. -- nixio buffersize which is <em>nixio.const.buffersize</em> (8192 by default).
  27. -- Any read request greater than that will be safely truncated to this value.
  28. -- @param length Amount of data to read (in Bytes).
  29. -- @return buffer containing data successfully read
  30. --- Reposition read / write offset of the file descriptor.
  31. -- The seek will be done either from the beginning of the file or relative
  32. -- to the current position or relative to the end.
  33. -- @class function
  34. -- @name File.seek
  35. -- @usage This function calls lseek().
  36. -- @param offset File Offset
  37. -- @param whence Starting point [<strong>"set"</strong>, "cur", "end"]
  38. -- @return new (absolute) offset position
  39. --- Return the current read / write offset of the file descriptor.
  40. -- @class function
  41. -- @name File.tell
  42. -- @usage This function calls lseek() with offset 0 from the current position.
  43. -- @return offset position
  44. --- Synchronizes the file with the storage device.
  45. -- Returns when the file is successfully written to the disk.
  46. -- @class function
  47. -- @name File.sync
  48. -- @usage This function calls fsync() when data_only equals false
  49. -- otherwise fdatasync(), on Windows _commit() is used instead.
  50. -- @usage fdatasync() is only supported by Linux and Solaris. For other systems
  51. -- the <em>data_only</em> parameter is ignored and fsync() is always called.
  52. -- @param data_only Do not synchronize the metadata. (optional, boolean)
  53. -- @return true
  54. --- Apply or test a lock on the file.
  55. -- @class function
  56. -- @name File.lock
  57. -- @usage This function calls lockf() on POSIX and _locking() on Windows.
  58. -- @usage The "lock" command is blocking, "tlock" is non-blocking,
  59. -- "ulock" unlocks and "test" only tests for the lock.
  60. -- @usage The "test" command is not available on Windows.
  61. -- @usage Locks are by default advisory on POSIX, but mandatory on Windows.
  62. -- @param command Locking Command ["lock", "tlock", "ulock", "test"]
  63. -- @param length Amount of Bytes to lock from current offset (optional)
  64. -- @return true
  65. --- Get file status and attributes.
  66. -- @class function
  67. -- @name File.stat
  68. -- @param field Only return a specific field, not the whole table (optional)
  69. -- @usage This function calls fstat().
  70. -- @return Table containing: <ul>
  71. -- <li>atime = Last access timestamp</li>
  72. -- <li>blksize = Blocksize (POSIX only)</li>
  73. -- <li>blocks = Blocks used (POSIX only)</li>
  74. -- <li>ctime = Creation timestamp</li>
  75. -- <li>dev = Device ID</li>
  76. -- <li>gid = Group ID</li>
  77. -- <li>ino = Inode</li>
  78. -- <li>modedec = Mode converted into a decimal number</li>
  79. -- <li>modestr = Mode as string as returned by `ls -l`</li>
  80. -- <li>mtime = Last modification timestamp</li>
  81. -- <li>nlink = Number of links</li>
  82. -- <li>rdev = Device ID (if special file)</li>
  83. -- <li>size = Size in bytes</li>
  84. -- <li>type = ["reg", "dir", "chr", "blk", "fifo", "lnk", "sock"]</li>
  85. -- <li>uid = User ID</li>
  86. -- </ul>
  87. --- Close the file descriptor.
  88. -- @class function
  89. -- @name File.close
  90. -- @return true
  91. --- Get the number of the filedescriptor.
  92. -- @class function
  93. -- @name File.fileno
  94. -- @return file descriptor number
  95. --- (POSIX) Set the blocking mode of the file descriptor.
  96. -- @class function
  97. -- @name File.setblocking
  98. -- @param blocking (boolean)
  99. -- @return true