Object Instance nixio.File
Large File Object. Large file operations are supported up to 52 bits if the Lua number type is double (default).
Functions
| File:close () | Close the file descriptor. |
| File:fileno () | Get the number of the filedescriptor. |
| File:lock (command, length) | Apply or test a lock on the file. |
| File:read (length) | Read from a file descriptor. |
| File:seek (offset, whence) | Reposition read / write offset of the file descriptor. |
| File:setblocking (blocking) | (POSIX) Set the blocking mode of the file descriptor. |
| File:stat (field) | Get file status and attributes. |
| File:sync (data_only) | Synchronizes the file with the storage device. |
| File:tell () | Return the current read / write offset of the file descriptor. |
| File:write (buffer, offset, length) | Write to the file descriptor. |
Functions
- File:close ()
-
Close the file descriptor.
Return value:
true - File:fileno ()
-
Get the number of the filedescriptor.
Return value:
file descriptor number - File: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)
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.
Return value:
true - File:read (length)
-
Read from a file descriptor.
Parameters
- length: Amount of data to read (in Bytes).
Usage
- Warning: 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 nixio.const.buffersize (8192 by default). Any read request greater than that will be safely truncated to this value.
Return value:
buffer containing data successfully read - File: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"]
Usage:
This function calls lseek().Return value:
new (absolute) offset position - File:setblocking (blocking)
-
(POSIX) Set the blocking mode of the file descriptor.
Parameters
- blocking: (boolean)
Return value:
true - File:stat (field)
-
Get file status and attributes.
Parameters
- field: Only return a specific field, not the whole table (optional)
Usage:
This function calls fstat().Return value:
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
- File: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)
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 data_only parameter is ignored and fsync() is always called.
Return value:
true - File:tell ()
-
Return the current read / write offset of the file descriptor.
Usage:
This function calls lseek() with offset 0 from the current position.Return value:
offset position - File: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)
Usage
- Warning: 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.
Return value:
number of bytes written