libcamera: libcamera::File Class Reference

libcamera v0.1.0 Supporting cameras in Linux since 2019

Loading...
Searching...
No Matches
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 class | MapFlag { NoOption = 0 , Private = (1 << 0) }
| Flags for the File::map() function. More...
enum class | OpenModeFlag { NotOpen = 0 , ReadOnly = (1 << 0) , WriteOnly = (1 << 1) , ReadWrite = ReadOnly | WriteOnly }
| Mode in which a file is opened. More...
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.
| File ()
| Construct a File without an associated name.
| ~File ()
| Destroy a File instance.
const std::string & | fileName () const
| Retrieve the file name.
void | setFileName (const std::string &name)
| Set the name of the file.
bool | exists () const
| Check if the file specified by fileName() exists.
bool | open (OpenMode mode)
| Open the file in the given mode.
bool | isOpen () const
| Check if the file is open.
OpenMode | openMode () const
| Retrieve the file open mode.
void | close ()
| Close the file.
int | error () const
| Retrieve the file error status.
ssize_t | size () const
| Retrieve the file size.
off_t | pos () const
| Return current read or write position.
off_t | seek (off_t pos)
| Set the read or write position.
ssize_t | read (const Span< uint8_t > &data)
| Read data from the file.
ssize_t | write (const Span< const uint8_t > &data)
| Write data to the file.
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.
bool | unmap (uint8_t *addr)
| Unmap a region mapped with map()

## Static Public Member Functions
static bool | exists (const std::string &name)
| Check if the file specified by name exists.

## 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

enum class libcamera::File::MapFlag
| strong

Flags for the File::map() function.

Enumerator
NoOption | No option (used as default value)
Private | The memory region is mapped as private, changes are not reflected in the file constents.

## ◆ OpenModeFlag

enum class libcamera::File::OpenModeFlag
| strong

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] | 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