class::sys::File

class sys::File
  : public api::SysWorkObject

This class is used to access files (and devices). It uses the POSIX functions open(), read(), write(), close(), etc. You can always call these functions directly or use the standard C library to access files (fopen(), fread(), fwrite()– these use more memory than this class or the POSIX functions).

Here is an example of using this class:

#include <sapi/sys.hpp>
#include <sapi/var.hpp>

int main(int argc, char * argv[]){
   File f;
   String str;

 //create a new file and write a string to it
   f.create("/home/myfile.txt");
   str = "Hello New File!\n";
   f.write(str);
   f.close();

 //Now open the file we just closed
   f.open("/home/myfile.txt");
   str = "";
   f.read(str.data(), str.capacity());
   f.close();

 //This is what was read from the file
   printf("The String is %s\n", str.c_str());

   File::remove("/home/myfile.txt"); //delete the file

   int fd;
   if(1){
     File file;
     file.open("/home/file.txt", File::READONLY);
     fd = file.fileno();
     file.set_keep_open(); //will keep the file open after ~File()
     //~File() is called here
   }

   char buffer[16];
   read(fd, buffer, 16); //OK because file.set_keep_open() was used
   return 0;
}

Methods

Details

publicFile()

public~File()

public virtual intclose()

Closes the file or device.


public intcreate(constvar::ConstString& path,bool overwrite,int perms)

Creates a new file (using the open() method).

Parameters

  • path The path to the file

  • overwrite Overwrite (truncate) the existing file (defaults to true)

  • perms The permissions to assign to the newly created file


public intfileno() const

Return the file number for accessing the file or device.


public intflags() const

Return the current flags for the file.


public intfstat(structstat* st) const

public inlineFileInfoget_info() const

publicvar::Stringgets(char term) const

Reads a line in to the var::String until end-of-file or term is reached.


public char *gets(var::String& s,char term) const

public char *gets(char * s,int n,char term) const

public virtual intioctl(int req,void * arg) const

Executes an IO control request.

Parameters

  • req The request value

  • arg A pointer to the arguments

This method is typically only implemented for devices and other special file systems.


public inline intioctl(int req,const void * arg) const

Executes an ioctl() with request and const arg pointer.

Parameters

  • req The request value

  • arg A pointer to the arguments

Returns

Depends on request


public inline intioctl(int req) const

Executes an ioctl() with just a request.

Parameters

  • req The request value

Returns

Depends on request

The arg value for the ioctl is set to NULL.


public inline intioctl(int req,int arg) const

Executes an ioctl() with request and integer arg.

Parameters

  • req The request value

  • arg An integer value (used with some requests)

Returns

Depends on request


public inline boolis_keep_open() const

Returns whether the file will be closed upon object destruction.

The default value on object creation is true.

See also: set_keep_open()


public intloc() const

Returns the location of the cursor in the device or file.


public virtual intopen(constvar::ConstString& name,int flags)

Opens a file.

Parameters

  • name The path to the file

  • flags The flags used to open the flag (e.g. File::READONLY)

Returns

Zero on success


public intopen(constvar::ConstString& name,int access,int perms)

Opens a file.

Parameters

  • name The filename to open

  • access The access ie RDWR

  • perms Permission settings

Returns

Zero on success

If the object already has a file open, the file will be closed.


public inline intopen_append(constvar::ConstString& path)

Opens a file for appending.

Parameters

  • path The path to the file

public inline intopen_readonly(constvar::ConstString& path)

Opens a read only file.

Parameters

  • path The path to the file

public inline intopen_readwrite(constvar::ConstString& path)

Opens a file for read/write.

Parameters

  • path The path to the file

public inline constFile&operator<<(constvar::ConstString& a) const

public inline constFile&operator<<(constvar::String& a) const

public inline constFile&operator<<(constvar::Data& a) const

public inline constFile&operator>>(var::Data& a) const

public virtual intread(void * buf,int nbyte) const

Reads the file.

Parameters

  • buf A pointer to the destination buffer

  • nbyte The number of bytes to read

Returns

The number of bytes read or less than zero on an error


public inline intread(var::Data& data) const

Reads the file into a var::Data object.

Parameters

  • data The destination data object

Returns

The number of bytes read

This method will read up to data.size() bytes.


public inline intread(api::InfoObject& info)

public intread(int loc,void * buf,int nbyte) const

Reads the file.

Parameters

  • loc The location of the file to read

  • buf A pointer to the destination buffer

  • nbyte The number of bytes to read

Returns

The number of bytes read or less than zero on an error


public inline intread(int loc,var::Data& data) const

Reads the file using a var::Data object.


public inline intread(int loc,api::InfoObject& info)

public intreadline(char * buf,int nbyte,int timeout_msec,char terminator) const

Reads a line from a file.

Parameters

  • buf Destination buffer

  • nbyte Number of bytes available in buffer

  • timeout_msec Timeout in ms if line does not arrive

  • terminator Terminating character of the line (default is newline)

Returns

Number of bytes received


public virtual intseek(int loc,int whence) const

Seeks to a location in the file or on the device.


public inline voidset_fileno(int fd) const

Sets the file descriptor for this object.


public inline voidset_fileno(constFile& file) const

Sets the file descriptor of this object to the file descriptor of file.

Parameters

  • file A reference to the file to share the fileno with.

The reference file must already be opened and have a valid file number. This won’t bind the file number to file just assign it based on the state of file.fileno() when this method is called.


public inline voidset_keep_open(bool value)

Sets the file to stay open even after the destructor has been called.

The default value on object creation is true.

#include <sapi/sys.hpp>

int fd;
if(1){
  File f;
  f.open("/home/data.txt");
  fd = f.fileno();
  f.set_keep_open();
  //~File() will be called here
}

//fd is still open because set_keep_open() was called
char buffer[16];
read(fd, buffer, 16);

public virtual u32size() const

Returns the file size.


public virtual intwrite(const void * buf,int nbyte) const

Write the file.

Parameters

  • buf A pointer to the source buffer

  • nbyte The number of bytes to read

Returns

The number of bytes written or less than zero on an error


public inline intwrite(constvar::Data& data) const

Writes the file using a var::Data object.


public inline intwrite(constvar::ConstString& str) const

Writes a var::ConstString to the file.

Parameters

  • str The string to write

Returns

The number of bytes written


public inline intwrite(constvar::String& str) const

Writes a var::String to the file.

Parameters

  • str The string to write

Returns

The number of bytes written


public inline intwrite(constapi::InfoObject& info) const

public intwrite(int loc,const void * buf,int nbyte) const

Writes the file at the location specified.

Parameters

  • loc Location to write (not application to character devices)

  • buf Pointer to the source data

  • nbyte Number of bytes to write

Returns

Number of bytes successfully written or less than zero with errno set


public inline intwrite(int loc,constvar::Data& data) const

Writes the file using a var::Data object at the location specified.


public inline intwrite(int loc,constvar::ConstString& str) const

Writes the file using a var::ConstString object at the location specified.


public inline intwrite(int loc,constvar::String& str) const

Writes the file using a var::String object at the location specified.


public inline intwrite(int loc,constapi::InfoObject& info) const

public intwrite(constsys::File& source_file,u32 chunk_size,u32 size) const

public inline intwrite(int loc,constsys::File& source_file,u32 chunk_size,u32 size) const

public intwrite(constsys::File& source_file,u32 chunk_size,u32 size,constProgressCallback* progress_callback) const

public inline intwrite(int loc,constsys::File& source_file,u32 chunk_size,u32 size,constProgressCallback* progress_callback) const

protected mutable intm_fd

enumo_open_flags
  • RDONLY Open as read-only
  • READONLY Open as read-only
  • WRONLY Open as write-only
  • WRITEONLY Open as write-only
  • CREATE Create when opening (files)
  • CREAT Create when opening (files)
  • TRUNCATE Truncate when opening (files)
  • TRUNC Truncate when opening (files)
  • APPEND Append when opening (files)
  • EXCLUSIVE Create exclusively (files)
  • EXCL Create exclusively (files)
  • READWRITE Open as read-write
  • RDWR Open as read-write
  • NONBLOCK Open as non-blocking
  • NDELAY Open as non-blocking
  • ACCMODE Access mode mask
  • ACCESS_MODE Access mode mask
  • FORMAT Mode format mask
  • FILE_SOCKET Mode Socket mask
  • REGULAR Mode regular file value
  • BLOCK Mode block device value
  • CHARACTER Mode character device value
  • DIRECTORY Mode directory value
  • FIFO Mode FIFO value
  • SYMBOLIC_LINK Mode symbolic link value
  • READ_OK Check if read access is allowed
  • WRITE_OK Check if write access is allowed
  • EXECUTE_OK Check if execute access is allowed
  • FILE_OK Check if file exists

These values are used as flags when opening devices or files


enumo_seek_whence
  • SET Set the location of the file descriptor
  • CURRENT Set the location relative to the current location
  • END Set the location relative to the end of the file or device

List of options for whence argument of seek()


X

Thanks for Coming!

Subscribe to news and updates