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] name The 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] name The 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]	offset	The region offset within the file
[in]	size	The region sise
[in]	flags	The 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] mode The 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] data Memory 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] pos The 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] name The 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] addr The 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] data Memory 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:

include/libcamera/base/file.h
src/libcamera/base/file.cpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ File() [1/2]

◆ File() [2/2]

◆ ~File()

Member Function Documentation

◆ close()

◆ error()

◆ exists() [1/2]

◆ exists() [2/2]

◆ fileName()

◆ isOpen()

◆ map()

◆ open()

◆ openMode()

◆ pos()

◆ read()

◆ seek()

◆ setFileName()

◆ size()

◆ unmap()

◆ write()