File_t Class Reference
File implementation.
#include <UTFile.h>
Public Member Functions | |
| File_t () | |
| virtual | ~File_t () |
| virtual Status_t | Open (const Path_t &path, int flags, mode_t permissions=0, MessageDestination_t< FileReadCompleteMessage_t > *read_dest=NULL, MessageDestination_t< FileWriteCompleteMessage_t > *write_dest=NULL, MessageDestination_t< FileOpenCompleteMessage_t > *open_dest=NULL) |
| Status_t | Open (const utf8 *path, int flags, mode_t permissions=0, MessageDestination_t< FileReadCompleteMessage_t > *read_dest=NULL, MessageDestination_t< FileWriteCompleteMessage_t > *write_dest=NULL, MessageDestination_t< FileOpenCompleteMessage_t > *open_dest=NULL) |
| Status_t | Open (stringliteral *path, int flags, mode_t permissions=0, MessageDestination_t< FileReadCompleteMessage_t > *read_dest=NULL, MessageDestination_t< FileWriteCompleteMessage_t > *write_dest=NULL, MessageDestination_t< FileOpenCompleteMessage_t > *open_dest=NULL) |
| int | OpenFlags () const |
| int | OpenRWFlags () const |
| const Path_t & | Path () const |
| virtual Status_t | Read (byte *buffer, int bytes_to_read, bool force_read_all=true) |
| virtual Status_t | Write (const byte *buffer, int bytes_to_write, bool force_write_all=true) |
| virtual Status_t | Size (out fileoff_t *size) |
| virtual Status_t | Position (out fileoff_t *position) |
| virtual Status_t | Seek (fileoff_t position) |
| virtual Status_t | Flush () |
| virtual Status_t | Close () |
Protected Member Functions | |
| virtual Status_t | AsyncOpenComplete () |
| virtual void | AppendStateInfo (String_t *state) const |
Detailed Description
Definition at line 83 of file UTFile.h.
Constructor & Destructor Documentation
| File_t::File_t | ( | ) |
File constructor. The file must be opened using the Open function.
| virtual File_t::~File_t | ( | ) | [virtual] |
File destructor. Unless an error had occurred previously, a file must be closed before deleting it.
Member Function Documentation
| virtual Status_t File_t::Open | ( | const Path_t & | path, | |
| int | flags, | |||
| mode_t | permissions = 0, |
|||
| MessageDestination_t< FileReadCompleteMessage_t > * | read_dest = NULL, |
|||
| MessageDestination_t< FileWriteCompleteMessage_t > * | write_dest = NULL, |
|||
| MessageDestination_t< FileOpenCompleteMessage_t > * | open_dest = NULL | |||
| ) | [virtual] |
Opens the file. If the file is opened successfully, returns a success status, otherwise an error status indicating the nature of the error. If an open_dest is specified, Open will return eERR_open_in_progress. GUI applications should, from their main thread, use O_NONBLOCK and message destinations unless there is 100% certainty that the file being opened resides on a local drive. That way, the main event loop will not be blocked on the file open or I/O.
- Parameters:
-
path The path to the file to be opened flags The parameter flags is one of O_RDONLY, O_WRONLY or O_RDWR which request opening the file read-only, write-only or read/write, respectively, bitwise-or'd with zero or more of the following:
O_CREAT If the file does not exist it will be created. The owner (user ID) of the file is set to the effective user ID of the process. The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on filesystem type and mount options, and the mode of the parent directory). If O_CREAT is specified, the permissions must include write permission (O_WRONLY or O_RDWR) and the permissions must include S_IWUSR.
O_EXCL When used with O_CREAT, if the file already exists it is an error and the open will fail. In this context, a symbolic link exists, regardless of where its points to. O_EXCL is broken on NFS file systems, programs which rely on it for performing locking tasks will contain a race condition.
O_TRUNC If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0. If the file is a FIFO or terminal device file, the O_TRUNC flag is ignored. Otherwise the effect of O_TRUNC is unspecified.
O_NONBLOCK When possible, the file is opened in non-blocking mode. If an operation cannot be completed without blocking, only the data which can be immediately read or written are returned. If no data can be immediately read or written, Read or Write will return eERR_async_io_in_progress, in which case the next read or write operation must exactly match the one which returned eERR_async_io_in_progress, and the buffer must remain valid until the next call. Also in that case no other file operations are permissible until the previous request has been repeated and succeeded.
O_SYNC File operations will not complete until all data has been written to disk.
Unlike the POSIX open function, the following flags are not supported:
O_APPEND
O_NOCTTY
O_DIRECTORY
O_LARGEFILE
O_DIRECT
O_RSYNC
O_DSYNCpermissions permissions must always be specified when O_CREAT is in the flags, and must be 0 otherwise. The following symbolic constants are provided for permissions:
S_IRWUSR user (file owner) has read, write permission
S_IRWXU user (file owner) has read, write and execute permission
S_IRUSR (S_IREAD) user has read permission
S_IWUSR (S_IWRITE) user has write permission
S_IXUSR (S_IEXEC) user has execute permission
S_IRWGRP group has read, write permission
S_IRWXG group has read, write and execute permission
S_IRGRP group has read permission
S_IWGRP group has write permission
S_IXGRP group has execute permission
S_IRWOTH others have read, write permission
S_IRWXO others have read, write and execute permission
S_IROTH others have read permission
S_IWOTH others have write permisson
S_IXOTH others have execute permission
read_dest Specifies a message destination to be notified when more data is available to be read. Use of this option requires that the flags include O_NONBLOCK. write_dest Specifies a message destination to be notified when a previously initiated asynchronous write has completed. Use of this option requires that the flags include O_NONBLOCK. open_dest Specifies a message destination to be notified when the file open has completed. This option would typically be coupled with use of O_NONBLOCK and a read_dest and/or write_dest.
Reimplemented in BufferedFile_t.
| Status_t File_t::Open | ( | const utf8 * | path, | |
| int | flags, | |||
| mode_t | permissions = 0, |
|||
| MessageDestination_t< FileReadCompleteMessage_t > * | read_dest = NULL, |
|||
| MessageDestination_t< FileWriteCompleteMessage_t > * | write_dest = NULL, |
|||
| MessageDestination_t< FileOpenCompleteMessage_t > * | open_dest = NULL | |||
| ) | [inline] |
Variant of Open( const Path_t& path, ... ) which takes a const utf8* for the file path instead of a const Path_t&
Reimplemented in BufferedFile_t.
| Status_t File_t::Open | ( | stringliteral * | path, | |
| int | flags, | |||
| mode_t | permissions = 0, |
|||
| MessageDestination_t< FileReadCompleteMessage_t > * | read_dest = NULL, |
|||
| MessageDestination_t< FileWriteCompleteMessage_t > * | write_dest = NULL, |
|||
| MessageDestination_t< FileOpenCompleteMessage_t > * | open_dest = NULL | |||
| ) | [inline] |
Variant of Open( const Path_t& path, ... ) which takes a const stringliteral* for the file path instead of a const Path_t&
Reimplemented in BufferedFile_t.
| int File_t::OpenFlags | ( | ) | const [inline] |
| int File_t::OpenRWFlags | ( | ) | const [inline] |
| const Path_t & File_t::Path | ( | ) | const [inline] |
| virtual Status_t File_t::Read | ( | byte * | buffer, | |
| int | bytes_to_read, | |||
| bool | force_read_all = true | |||
| ) | [virtual] |
Reads up to bytes_to_read bytes into buffer, and returns the number of bytes read as a success status indication, or an error status.
For nonblocking files, if force_read_all is true, Read will block until all data is read or the end of the file is reached.
If force_read_all is true, a returned byte count less than bytes_to_read indicates that the end of the file was reached.
If the end of the file is reached with no data having been read, the returned status will be eERR_end_of_file.
If O_NONBLOCK was specified when the file was opened, force_read_all is false, and the read was unable to complete immediately, the request will proceed to completion asynchronously. In that case the returned status is eERR_async_io_in_progress to indicate that data is not currently available, the next call to Read must exactly match the one which returned eERR_async_io_in_progress, and the buffer must remain valid until the next call. Also in that case, no other file operations are permissible until the previous request has been repeated and succeeded.
Implements InputStream_t.
Reimplemented in BufferedFile_t.
| virtual Status_t File_t::Write | ( | const byte * | buffer, | |
| int | bytes_to_write, | |||
| bool | force_write_all = true | |||
| ) | [virtual] |
Writes up to bytes_to_write bytes from buffer, and returns the number of bytes written as a success status indication, or an error status. If an error status is returned, some data may have been written, and it is not possible to determine how much data was written.
For nonblocking files, if force_write_all is true, Write will block until all data has been written.
If force_write_all is true, either all data will be written or an error will be returned. An end of file condition for write is not expected for regular files, but if reaching end-of-file without writing all of the specified data is not to be considered an error, force_write_all must be set to false.
If force_write_all is false, in the absence of any other error, the returned status will be the number of bytes written, which may be less than what was requested. An end of file condition for write is not expected for regular files, but if end of the file is reached with no data having been written, the returned status will be eERR_end_of_file.
If O_NONBLOCK was specified when the file was opened, force_write_all is false, and the write was unable to complete immediately, the request will proceed to completion asynchronously. In that case the returned status is eERR_async_io_in_progress to indicate that the write is proceeding asynchronously, the next call to Write must exactly match the one which returned eERR_async_io_in_progress, and the buffer must remain valid until the next call. Also in that case, no other file operations are permissible until the revious request has been repeated and succeeded.
Implements OutputStream_t.
Reimplemented in BufferedFile_t.
Returns the size of the file through the size parameter, or an error status if an error occurs.
Reimplemented in BufferedFile_t.
Returns the position in the file through the position output parameter unless an error occurs, in which case an error status is returned in the Status_t return value.
Implements IOStream_t.
Reimplemented in BufferedFile_t.
Repositions the input/output position to the requested offset in the file. Seek will block until completed even if the Open flags included O_NONBLOCK.
Implements IOStream_t.
Reimplemented in BufferedFile_t.
| virtual Status_t File_t::Flush | ( | ) | [virtual] |
Flushes any data buffered but not written to whatever physical layer the file represents. If an error occurs, an error status will be returned. Flush will block until completed even if the Open flags included O_NONBLOCK.
Implements OutputStream_t.
Reimplemented in BufferedFile_t.
| virtual Status_t File_t::Close | ( | ) | [virtual] |
Closes the file. Close will block until completed even if the Open flags included O_NONBLOCK. In the event of a prior error or error closing the file, Close will return an error, but the file will nonetheless be closed. If all prior operations had succeeded since the file was opened, then an error returned by Close indicates that an error occurred during the close. When a file had been written to, an error indicates that all data may not have been written. The path will be preserved, pointing to the file which was closed.
Implements IOStream_t.
Reimplemented in BufferedFile_t.
| virtual Status_t File_t::AsyncOpenComplete | ( | ) | [protected, virtual] |
Tests whether asynchronous open (initiated if the open_dest parameter passed to Open is not NULL) completed successfully. If opening the file was asynchronous, neither the file nor any subclass will get a chance to act upon it until the owner receives the open completion message and attempts to use the file. In that case, any subclass of file must, if open was proceeding asynchronously, leave itself in a state where when the first attempt to use the file is made, it can obtain the result of that open operation, verify that the open did in fact complete successfully, and clear the open pending status.
Reimplemented in BufferedFile_t.
| virtual void File_t::AppendStateInfo | ( | String_t * | state | ) | const [protected, virtual] |
Allows an IOStream_t subclass to output state information for file operation logging on function exit
Reimplemented from IOStream_t.
Reimplemented in BufferedFile_t.
The documentation for this class was generated from the following file:
- D:/develop/svn/utlib/utlib/trunk/UT/src_UT/UTFile.h
