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 + + + +
+
+
+