Module nixio.File
Large File Object.
Large file operations are supported up to 52 bits if the Lua number type is double (default).
Functions
| write (buffer, offset, length) | Write to the file descriptor. |
| read (length) | Read from a file descriptor. |
| seek (offset, whence) | Reposition read / write offset of the file descriptor. |
| tell () | Return the current read / write offset of the file descriptor. |
| sync (data_only) | Synchronizes the file with the storage device. |
| lock (command, length) | Apply or test a lock on the file. |
| stat (field) | Get file status and attributes. |
| close () | Close the file descriptor. |
| fileno () | Get the number of the filedescriptor. |
| setblocking (blocking) | (POSIX) Set the blocking mode of the file descriptor. |
Functions
- write (buffer, offset, length)
-
Write to the file descriptor.
Parameters:
- buffer Buffer holding the data to be written.
- offset Offset to start reading the buffer from. (optional)
- length Length of chunk to read from the buffer. (optional)
Returns:
-
number of bytes written
Usage:
<strong>Warning:</strong> It is not guaranteed that all data in the buffer is written at once especially when dealing with pipes. You have to check the return value - the number of bytes actually written - or use the safe IO functions in the high-level IO utility module.
Unlike standard Lua indexing the lowest offset and default is 0.
- read (length)
-
Read from a file descriptor.
Parameters:
- length Amount of data to read (in Bytes).
Returns:
-
buffer containing data successfully read
Usage:
<strong>Warning:</strong> It is not guaranteed that all requested data is read at once especially when dealing with pipes. You have to check the return value - the length of the buffer actually read - or use the safe IO functions in the high-level IO utility module.
The length of the return buffer is limited by the (compile time) nixio buffersize which is <em>nixio.const.buffersize</em> (8192 by default). Any read request greater than that will be safely truncated to this value.
- seek (offset, whence)
-
Reposition read / write offset of the file descriptor.
The seek will be done either from the beginning of the file or relative
to the current position or relative to the end.
Parameters:
- offset File Offset
- whence Starting point ["set", "cur", "end"]
Returns:
-
new (absolute) offset position
Usage:
This function calls lseek().
- tell ()
-
Return the current read / write offset of the file descriptor.
Returns:
-
offset position
Usage:
This function calls lseek() with offset 0 from the current position.
- sync (data_only)
-
Synchronizes the file with the storage device.
Returns when the file is successfully written to the disk.
Parameters:
- data_only Do not synchronize the metadata. (optional, boolean)
Returns:
-
true
Usage:
This function calls fsync() when data_only equals false otherwise fdatasync(), on Windows _commit() is used instead.
fdatasync() is only supported by Linux and Solaris. For other systems the <em>data_only</em> parameter is ignored and fsync() is always called.
- lock (command, length)
-
Apply or test a lock on the file.
Parameters:
- command Locking Command ["lock", "tlock", "ulock", "test"]
- length Amount of Bytes to lock from current offset (optional)
Returns:
-
true
Usage:
This function calls lockf() on POSIX and _locking() on Windows.
The "lock" command is blocking, "tlock" is non-blocking, "ulock" unlocks and "test" only tests for the lock.
The "test" command is not available on Windows.
Locks are by default advisory on POSIX, but mandatory on Windows.
- stat (field)
-
Get file status and attributes.
Parameters:
- field Only return a specific field, not the whole table (optional)
Returns:
-
Table containing:
- atime = Last access timestamp
- blksize = Blocksize (POSIX only)
- blocks = Blocks used (POSIX only)
- ctime = Creation timestamp
- dev = Device ID
- gid = Group ID
- ino = Inode
- modedec = Mode converted into a decimal number
- modestr = Mode as string as returned by `ls -l`
- mtime = Last modification timestamp
- nlink = Number of links
- rdev = Device ID (if special file)
- size = Size in bytes
- type = ["reg", "dir", "chr", "blk", "fifo", "lnk", "sock"]
- uid = User ID
Usage:
This function calls fstat().
- close ()
-
Close the file descriptor.
Returns:
-
true
- fileno ()
-
Get the number of the filedescriptor.
Returns:
-
file descriptor number
- setblocking (blocking)
-
(POSIX) Set the blocking mode of the file descriptor.
Parameters:
- blocking (boolean)
Returns:
-
true