class::fs::File

class fs::File
  : public api::FsWorkObject

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:

//md2code:include
#include <sapi/fs.hpp>
#include <sapi/var.hpp>
//md2code:main
File f;
String str;

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

 //Now open the file we just closed
f.open(
  arg::FilePath("/home/myfile.txt"),
  OpenFlags::read_only()
  );
str = "";
str = f.gets(); //reads a line from the file
f.close();

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

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

int fd;
if(1){
  File file;
  file.open(
    arg::FilePath("/home/file.txt"),
    OpenFlags::read_only()
  );
  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;

Summary

File()

~File()

virtual int close()

int create(

const arg::DestinationFilePath & path,
const arg::IsOverwrite & is_overwrite,
const Permissions & perms
)

int fileno() const

int flags() const

int fstat(

struct stat * st
) const

Stat get_info() const

var::String gets(

char term
) const

char * gets(

var::String & s,
char term
) const

char * gets(

char * s,
int n,
char term
) const

virtual int ioctl(

const arg::IoRequest request,
const arg::IoArgument arg
) const

int ioctl(

const arg::IoRequest request,
const arg::IoConstArgument argument
) const

int ioctl(

const arg::IoRequest request
) const

int ioctl(

const arg::IoRequest request,
const arg::IoIntArgument argument
) const

bool is_keep_open() const

int location() const

virtual int open(

const arg::FilePath & name,
const OpenFlags & flags
)

int open(

const arg::FilePath & name,
const OpenFlags & flags,
const Permissions & permissions
)

const File & operator<<(

const var::ConstString & a
) const

const File & operator<<(

const var::String & a
) const

const File & operator<<(

const var::DataReference & a
) const

const File & operator>>(

var::Data & a
) const

virtual int read(

arg::DestinationBuffer buf,
const arg::Size size
) const

int read(

var::Data & data
) const

int read(

const arg::Location location,
arg::DestinationBuffer buf,
const arg::Size size
) const

int read(

const arg::Location location,
arg::DestinationData data
) const

int read(

arg::DestinationData data
) const

int read(

api::InfoObject & info
)

int readline(

char * buf,
int nbyte,
int timeout_msec,
char terminator
) const

virtual int seek(

const arg::Location location,
enum whence whence
) const

void set_fileno(

int fd
) const

void set_fileno(

const File & file
) const

File & set_keep_open(

bool value
)

virtual u32 size() const

virtual int write(

const arg::SourceBuffer buf,
const arg::Size size
) const

int write(

const var::Data & data
) const

int write(

const var::ConstString & str
) const

int write(

const var::String & str
) const

int write(

const arg::Location location,
const arg::SourceBuffer buf,
const arg::Size size
) const

int write(

const arg::Location & location,
const arg::SourceData & data
) const

int write(

const arg::SourceData & data
) const

int write(

const arg::Location & location,
const var::ConstString & str
) const

int write(

const arg::Location location,
const var::String str
) const

int write(

const arg::SourceFile source_file,
const arg::PageSize page_size,
const arg::Size size
) const

int write(

const arg::Location location,
const arg::SourceFile source_file,
const arg::PageSize page_size,
const arg::Size size
) const

int write(

const arg::SourceFile source_file,
const arg::PageSize page_size,
const arg::Size size,
const sys::ProgressCallback * progress_callback
) const

int write(

const arg::Location location,
const arg::SourceFile source_file,
const arg::PageSize page_size,
const arg::Size size,
const sys::ProgressCallback * progress_callback
) const

static int access(

const arg::SourceFilePath path,
const Access & o_access
)

static int copy(

const arg::SourceFilePath source_path,
const arg::DestinationFilePath dest_path
)

static int copy(

const arg::SourceFilePath source_path,
const arg::DestinationFilePath dest_path,
const arg::IsOverwrite is_overwrite
)

static bool exists(

const arg::SourceFilePath path
)

static Stat get_info(

const arg::SourceFilePath path
)

static Stat get_info(

const arg::FileDescriptor fd
)

static var::ConstString name(

const arg::ImplicitFilePath & path
)

static var::String parent_directory(

const arg::ImplicitFilePath & path
)

static int remove(

const arg::SourceFilePath path
)

static int rename(

const arg::SourceFilePath old_path,
const arg::DestinationFilePath new_path
)

static u32 size(

const arg::SourceFilePath & path
)

static int stat(

const arg::SourceFilePath & path,
struct stat & st
)

static var::ConstString suffix(

const arg::ImplicitFilePath & path
)

protected mutable int m_fd

enum whence

Members

File()

~File()

virtual int close()

Closes the file or device.


int create(

const arg::DestinationFilePath & path,
const arg::IsOverwrite & is_overwrite,
const Permissions & perms
)

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

Parameters

  • path The path to the file

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

  • perms The permissions to assign to the newly created file


int fileno() const

Return the file number for accessing the file or device.


int flags() const

Return the current flags for the file.


int fstat(

struct stat * st
) const


Stat get_info() const

var::String gets(

char term
) const

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


char * gets(

var::String & s,
char term
) const


char * gets(

char * s,
int n,
char term
) const


virtual int ioctl(

const arg::IoRequest request,
const arg::IoArgument arg
) const

Executes an IO control request.

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


int ioctl(

const arg::IoRequest request,
const arg::IoConstArgument argument
) const

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

Returns

Depends on request


int ioctl(

const arg::IoRequest request
) const

Executes an ioctl() with just a request.

Returns

Depends on request

The arg value for the ioctl is set to NULL.


int ioctl(

const arg::IoRequest request,
const arg::IoIntArgument argument
) const

Executes an ioctl() with request and integer arg.

Returns

Depends on request


bool is_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()


int location() const

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


virtual int open(

const arg::FilePath & name,
const OpenFlags & 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


int open(

const arg::FilePath & name,
const OpenFlags & flags,
const Permissions & permissions
)

Opens a file.

Parameters

  • name The filename to open

  • flags The access ie RDWR

  • permissions Permission settings

Returns

Zero on success

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


const File & operator<<(

const var::ConstString & a
) const


const File & operator<<(

const var::String & a
) const


const File & operator<<(

const var::DataReference & a
) const


const File & operator>>(

var::Data & a
) const


virtual int read(

arg::DestinationBuffer buf,
const arg::Size size
) const

Reads the file.

Returns

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

//md2code:main
File f;
char buffer[64];
f.read(
  arg::DestinationBuffer(buffer),
  arg::Size(64)
);

//the above works but this is better
f.read(
  arg::DestinationData( DataReference(buffer) )
);

int read(

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.


int read(

const arg::Location location,
arg::DestinationBuffer buf,
const arg::Size size
) const

Reads the file.

Returns

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


int read(

const arg::Location location,
arg::DestinationData data
) const

Reads the file using a var::Data object.


int read(

arg::DestinationData data
) const


int read(

api::InfoObject & info
)


int readline(

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


virtual int seek(

const arg::Location location,
enum whence whence
) const

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


void set_fileno(

int fd
) const

Sets the file descriptor for this object.


void set_fileno(

const File & file
) const

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

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.


File & set_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);

virtual u32 size() const

Returns the file size.


virtual int write(

const arg::SourceBuffer buf,
const arg::Size size
) const

Write the file.

Returns

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


int write(

const var::Data & data
) const

Writes the file using a var::Data object.


int write(

const var::ConstString & str
) const

Writes a var::ConstString to the file.

Parameters

  • str The string to write

Returns

The number of bytes written


int write(

const var::String & str
) const

Writes a var::String to the file.

Parameters

  • str The string to write

Returns

The number of bytes written


int write(

const arg::Location location,
const arg::SourceBuffer buf,
const arg::Size size
) 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


int write(

const arg::Location & location,
const arg::SourceData & data
) const

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


int write(

const arg::SourceData & data
) const


int write(

const arg::Location & location,
const var::ConstString & str
) const

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


int write(

const arg::Location location,
const var::String str
) const

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


int write(

const arg::SourceFile source_file,
const arg::PageSize page_size,
const arg::Size size
) const


int write(

const arg::Location location,
const arg::SourceFile source_file,
const arg::PageSize page_size,
const arg::Size size
) const


int write(

const arg::SourceFile source_file,
const arg::PageSize page_size,
const arg::Size size,
const sys::ProgressCallback * progress_callback
) const


int write(

const arg::Location location,
const arg::SourceFile source_file,
const arg::PageSize page_size,
const arg::Size size,
const sys::ProgressCallback * progress_callback
) const


static int access(

const arg::SourceFilePath path,
const Access & o_access
)

Returns an error if the access is not allowed.


static int copy(

const arg::SourceFilePath source_path,
const arg::DestinationFilePath dest_path
)

Copies a file from the source to the destination.

Returns

Zero on success


static int copy(

const arg::SourceFilePath source_path,
const arg::DestinationFilePath dest_path,
const arg::IsOverwrite is_overwrite
)

Copies a file from the source to the destination.

Returns

Zero on success


static bool exists(

const arg::SourceFilePath path
)


static Stat get_info(

const arg::SourceFilePath path
)


static Stat get_info(

const arg::FileDescriptor fd
)


static var::ConstString name(

const arg::ImplicitFilePath & path
)

Gets the name of the file from a given path.

const char * path = "/app/flash/HelloWorld";
printf("Name is %s", File::name(path));

The above code will output:

Name is HelloWorld

static var::String parent_directory(

const arg::ImplicitFilePath & path
)


static int remove(

const arg::SourceFilePath path
)

Deletes a file.

Returns

Zero on success


static int rename(

const arg::SourceFilePath old_path,
const arg::DestinationFilePath new_path
)

Renames a file.

Parameters

  • old_path Current path to the file (will be old path after rename)

  • new_path New path to the file

Returns

Zero on success


static u32 size(

const arg::SourceFilePath & path
)

Gets the size of the file.

Parameters

  • path The path to the file

Returns

The number of bytes in the file or less than zero for an error


static int stat(

const arg::SourceFilePath & path,
struct stat & st
)

Gets file stat data.

Returns

Zero on success


static var::ConstString suffix(

const arg::ImplicitFilePath & path
)

Returns a pointer to the file suffix.

Returns

A pointer to the suffix

For example:

const var::ConstString path = "/home/data.txt";
printf("Suffix is %s", File::suffix(path).cstring());

The above code will output:

Suffix is txt

protected mutable int m_fd

enum 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