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

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