libcamera  v0.0.0
Supporting cameras in Linux since 2019
Public Types | Public Member Functions | Static Public Member Functions | List of all members
libcamera::File Class Reference

Interface for I/O operations on files. More...

Public Types

enum  MapFlag { MapNoOption = 0 , MapPrivate = (1 << 0) }
 Flags for the File::map() function. More...
 
enum  OpenMode { NotOpen = 0 , ReadOnly = (1 << 0) , WriteOnly = (1 << 1) , ReadWrite = ReadOnly | WriteOnly }
 Mode in which a file is opened. More...
 

Public Member Functions

 File (const std::string &name)
 Construct a File to represent the file name. More...
 
 File ()
 Construct a File without an associated name. More...
 
 ~File ()
 Destroy a File instance. More...
 
 File (const File &)=delete
 
Fileoperator= (const File &)=delete
 
const std::string & fileName () const
 Retrieve the file name. More...
 
void setFileName (const std::string &name)
 Set the name of the file. More...
 
bool exists () const
 Check if the file specified by fileName() exists. More...
 
bool open (OpenMode mode)
 Open the file in the given mode. More...
 
bool isOpen () const
 Check if the file is open. More...
 
OpenMode openMode () const
 Retrieve the file open mode. More...
 
void close ()
 Close the file. More...
 
int error () const
 Retrieve the file error status. More...
 
ssize_t size () const
 Retrieve the file size. More...
 
Span< uint8_t > map (off_t offset=0, ssize_t size=-1, MapFlag flags=MapNoOption)
 Map a region of the file in the process memory. More...
 
bool unmap (uint8_t *addr)
 Unmap a region mapped with map() More...
 

Static Public Member Functions

static bool exists (const std::string &name)
 Check if the file specified by name exists. More...
 

Detailed Description

Interface for I/O operations on files.

The File class provides an interface to perform I/O operations on files. It wraps opening, closing and mapping files in memory, and handles the cleaning of allocated resources.

File instances are usually constructed with a file name, but the name can be set later through the setFileName() function. Instances are not automatically opened when constructed, and shall be opened explictly with open().

Files can be mapped to the process memory with map(). Mapped regions can be unmapped manually with munmap(), and are automatically unmapped when the File is destroyed or when it is used to reference another file with setFileName().

Member Enumeration Documentation

◆ MapFlag

Flags for the File::map() function.

Enumerator
MapNoOption 

No option (used as default value)

MapPrivate 

The memory region is mapped as private, changes are not reflected in the file constents.

◆ OpenMode

Mode in which a file is opened.

Enumerator
NotOpen 

The file is not open.

ReadOnly 

The file is open for reading.

WriteOnly 

The file is open for writing.

ReadWrite 

The file is open for reading and writing.

Constructor & Destructor Documentation

◆ File() [1/2]

libcamera::File::File ( const std::string &  name)

Construct a File to represent the file name.

Parameters
[in]nameThe file name

Upon construction the File object is closed and shall be opened with open() before performing I/O operations.

◆ File() [2/2]

libcamera::File::File ( )

Construct a File without an associated name.

Before being used for any purpose, the file name shall be set with setFileName().

◆ ~File()

libcamera::File::~File ( )

Destroy a File instance.

Any memory mapping associated with the File is unmapped, and the File is closed if it is open.

Member Function Documentation

◆ close()

void libcamera::File::close ( )

Close the file.

This function closes the File. If the File is not open, it performs no operation. Memory mappings created with map() are not destroyed when the file is closed.

◆ error()

int libcamera::File::error ( ) const
inline

Retrieve the file error status.

This function retrieves the error status from the last file open or I/O operation. The error status is a negative number as defined by errno.h. If no error occurred, this function returns 0.

Returns
The file error status

◆ exists() [1/2]

bool libcamera::File::exists ( ) const

Check if the file specified by fileName() exists.

This function checks if the file specified by fileName() exists. The File instance doesn't need to be open to check for file existence, and this function may return false even if the file is open, if it was deleted from the file system.

Returns
True if the the file exists, false otherwise

◆ exists() [2/2]

bool libcamera::File::exists ( const std::string &  name)
static

Check if the file specified by name exists.

Parameters
[in]nameThe file name
Returns
True if the file exists, false otherwise

◆ fileName()

const std::string & libcamera::File::fileName ( ) const
inline

Retrieve the file name.

Returns
The file name

◆ isOpen()

bool libcamera::File::isOpen ( ) const
inline

Check if the file is open.

Returns
True if the file is open, false otherwise

◆ map()

Span< uint8_t > libcamera::File::map ( off_t  offset = 0,
ssize_t  size = -1,
enum File::MapFlag  flags = MapNoOption 
)

Map a region of the file in the process memory.

Parameters
[in]offsetThe region offset within the file
[in]sizeThe region sise
[in]flagsThe mapping flags

This function maps a region of size bytes of the file starting at offset into the process memory. The File instance shall be open, but may be closed after mapping the region. Mappings stay valid when the File is closed, and are destroyed automatically when the File is deleted.

If size is a negative value, this function maps the region starting at offset until the end of the file.

The mapping memory protection is controlled by the file open mode, unless flags contains MapPrivate in which case the region is mapped in read/write mode.

The error() status is updated.

Returns
The mapped memory on success, or an empty span otherwise

◆ open()

bool libcamera::File::open ( File::OpenMode  mode)

Open the file in the given mode.

Parameters
[in]modeThe open mode

This function opens the file specified by fileName() in mode. If the file doesn't exist and the mode is WriteOnly or ReadWrite, this function will attempt to create the file.

The error() status is updated.

Returns
True on success, false otherwise

◆ openMode()

OpenMode libcamera::File::openMode ( ) const
inline

Retrieve the file open mode.

Returns
The file open mode

◆ setFileName()

void libcamera::File::setFileName ( const std::string &  name)

Set the name of the file.

Parameters
[in]nameThe name of the file

The name can contain an absolute path, a relative path or no path at all. Calling this function on an open file results in undefined behaviour.

Any memory mapping associated with the File is unmapped.

◆ size()

ssize_t libcamera::File::size ( ) const

Retrieve the file size.

This function retrieves the size of the file on the filesystem. The File instance shall be open to retrieve its size. The error() status is not modified, error codes are returned directly on failure.

Returns
The file size in bytes on success, or a negative error code otherwise

◆ unmap()

bool libcamera::File::unmap ( uint8_t *  addr)

Unmap a region mapped with map()

Parameters
[in]addrThe region address

The error() status is updated.

Returns
True on success, or false if an error occurs

The documentation for this class was generated from the following files: