libcamera  v0.3.0+92-226ce294
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 { NoOption = 0, Private = (1 << 0) }
 Flags for the File::map() function.
 
enum  OpenModeFlag { NotOpen = 0, ReadOnly = (1 << 0), WriteOnly = (1 << 1), ReadWrite = ReadOnly | WriteOnly }
 Mode in which a file is opened.
 
using MapFlags = Flags< MapFlag >
 A bitwise combination of File::MapFlag values.
 
using OpenMode = Flags< OpenModeFlag >
 A bitwise combination of File::OpenModeFlag values.
 

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...
 
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...
 
off_t pos () const
 Return current read or write position. More...
 
off_t seek (off_t pos)
 Set the read or write position. More...
 
ssize_t read (const Span< uint8_t > &data)
 Read data from the file. More...
 
ssize_t write (const Span< const uint8_t > &data)
 Write data to the file. More...
 
Span< uint8_t > map (off_t offset=0, ssize_t size=-1, MapFlags flags=MapFlag::NoOption)
 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().

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,
File::MapFlags  flags = MapFlag::NoOption 
)

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 MapFlag::Private 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 with initial permissions set to 0666 (modified by the process' umask).

The file is opened with the O_CLOEXEC flag, and will be closed automatically when a new binary is executed with one of the exec(3) functions.

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

◆ pos()

off_t libcamera::File::pos ( ) const

Return current read or write position.

If the file is closed, this function returns 0.

Returns
The current read or write position

◆ read()

ssize_t libcamera::File::read ( const Span< uint8_t > &  data)

Read data from the file.

Parameters
[in]dataMemory to read data into

Read at most data.size() bytes from the file into data.data(), and return the number of bytes read. If less data than requested is available, the returned byte count may be smaller than the requested size. If no more data is available, 0 is returned.

The position of the file as returned by pos() is advanced by the number of bytes read. If an error occurs, the position isn't modified.

Returns
The number of bytes read on success, or a negative error code otherwise

◆ seek()

off_t libcamera::File::seek ( off_t  pos)

Set the read or write position.

Parameters
[in]posThe desired position
Returns
The resulting offset from the beginning of the file on success, or a negative error code otherwise

◆ 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

◆ write()

ssize_t libcamera::File::write ( const Span< const uint8_t > &  data)

Write data to the file.

Parameters
[in]dataMemory containing data to be written

Write at most data.size() bytes from data.data() to the file, and return the number of bytes written. If the file system doesn't have enough space for the data, the returned byte count may be less than requested.

The position of the file as returned by pos() is advanced by the number of bytes written. If an error occurs, the position isn't modified.

Returns
The number of bytes written on success, or a negative error code otherwise

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