libcamera::FileDescriptor Class Referencefinal

RAII-style wrapper for file descriptors. More...

## Public Member Functions

| FileDescriptor (const int &fd=-1)
| Create a FileDescriptor copying a given fd. More...
| FileDescriptor (int &&fd)
| Create a FileDescriptor taking ownership of a given fd. More...
| FileDescriptor (const FileDescriptor &other)
| Copy constructor, create a FileDescriptor from a copy of other. More...
| FileDescriptor (FileDescriptor &&other)
| Move constructor, create a FileDescriptor by taking over other. More...
| ~FileDescriptor ()
| Destroy the FileDescriptor instance. More...
FileDescriptor & | operator= (const FileDescriptor &other)
| Copy assignment operator, replace the wrapped file descriptor with a copy of other. More...
FileDescriptor & | operator= (FileDescriptor &&other)
| Move assignment operator, replace the wrapped file descriptor by taking over other. More...
bool | isValid () const
| Check if the FileDescriptor instance is valid. More...
int | fd () const
| Retrieve the numerical file descriptor. More...
FileDescriptor | dup () const
| Duplicate a FileDescriptor. More...

## Detailed Description

RAII-style wrapper for file descriptors.

The FileDescriptor class provides RAII-style lifetime management of file descriptors with an efficient mechanism for ownership sharing. At its core, an internal Descriptor object wraps a file descriptor (expressed as a signed integer) with an RAII-style interface. The Descriptor is then implicitly shared with all FileDescriptor instances constructed as copies.

When constructed from a numerical file descriptor, the FileDescriptor instance either duplicates or takes over the file descriptor:

- The FileDescriptor(const int &) constructor duplicates the numerical file descriptor and wraps the duplicate in a Descriptor. The caller is responsible for closing the original file descriptor, and the value returned by fd() will be different from the value passed to the constructor.
- The FileDescriptor(int &&) constructor takes over the numerical file descriptor and wraps it in a Descriptor. The caller is shall not touch the original file descriptor once the function returns, and the value returned by fd() will be identical to the value passed to the constructor.

The copy constructor and assignment operator create copies that share the Descriptor, while the move versions of those methods additionally make the other FileDescriptor invalid. When the last FileDescriptor that references a Descriptor is destroyed, the file descriptor is closed.

The numerical file descriptor is available through the fd() method. All FileDescriptor instances created as copies of a FileDescriptor will report the same fd() value. Callers can perform operations on the fd(), but shall never close it manually.

## Constructor & Destructor Documentation

## FileDescriptor() [1/4]

libcamera::FileDescriptor::FileDescriptor | ( | const int & | fd = `-1` | ) |

explicit

Create a FileDescriptor copying a given fd.

Parameters

  [in] | fd | File descriptor

Construct a FileDescriptor from a numerical file descriptor by duplicating the fd, and take ownership of the copy. The original fd is left untouched, and the caller is responsible for closing it when appropriate. The duplicated file descriptor will be closed automatically when all FileDescriptor instances that reference it are destroyed.

If the fd is negative, the FileDescriptor is constructed as invalid and the fd() method will return -1.

## FileDescriptor() [2/4]

libcamera::FileDescriptor::FileDescriptor | ( | int && | fd | ) |

explicit

Create a FileDescriptor taking ownership of a given fd.

Parameters

  [in] | fd | File descriptor

Construct a FileDescriptor from a numerical file descriptor by taking ownership of the fd. The original fd is set to -1 and shall not be touched by the caller anymore. In particular, the caller shall not close the original fd manually. The duplicated file descriptor will be closed automatically when all FileDescriptor instances that reference it are destroyed.

If the fd is negative, the FileDescriptor is constructed as invalid and the fd() method will return -1.

## FileDescriptor() [3/4]

libcamera::FileDescriptor::FileDescriptor | ( | const FileDescriptor & | other | ) |

Copy constructor, create a FileDescriptor from a copy of other.

Parameters

  [in] | other | The other FileDescriptor

Copying a FileDescriptor implicitly shares ownership of the wrapped file descriptor. The original FileDescriptor is left untouched, and the caller is responsible for destroying it when appropriate. The wrapped file descriptor will be closed automatically when all FileDescriptor instances that reference it are destroyed.

## FileDescriptor() [4/4]

libcamera::FileDescriptor::FileDescriptor | ( | FileDescriptor && | other | ) |

Move constructor, create a FileDescriptor by taking over other.

Parameters

  [in] | other | The other FileDescriptor

Moving a FileDescriptor moves the reference to the wrapped descriptor owned by other to the new FileDescriptor. The other FileDescriptor is invalidated and its fd() method will return -1. The wrapped file descriptor will be closed automatically when all FileDescriptor instances that reference it are destroyed.

## ~FileDescriptor()

libcamera::FileDescriptor::~FileDescriptor | ( |  | ) |

Destroy the FileDescriptor instance.

Destroying a FileDescriptor instance releases its reference to the wrapped descriptor, if any. When the last instance that references a wrapped descriptor is destroyed, the file descriptor is automatically closed.

## Member Function Documentation

## dup()

FileDescriptor libcamera::FileDescriptor::dup | ( |  | ) | const

Duplicate a FileDescriptor.

Duplicating a FileDescriptor creates a duplicate of the wrapped file descriptor and returns a new FileDescriptor instance that wraps the duplicate. The fd() method of the original and duplicate instances will return different values. The duplicate instance will not be affected by destruction of the original instance or its copies.

Returns
  A new FileDescriptor instance wrapping a duplicate of the original file descriptor

## fd()

libcamera::FileDescriptor::fd | ( |  | ) | const

inline

Retrieve the numerical file descriptor.

Returns
  The numerical file descriptor, which may be -1 if the FileDescriptor instance is invalid

## isValid()

libcamera::FileDescriptor::isValid | ( |  | ) | const

inline

Check if the FileDescriptor instance is valid.

Returns
  True if the FileDescriptor is valid, false otherwise

## operator=() [1/2]

FileDescriptor & libcamera::FileDescriptor::operator= | ( | const FileDescriptor & | other | ) |

Copy assignment operator, replace the wrapped file descriptor with a copy of other.

Parameters

  [in] | other | The other FileDescriptor

Copying a FileDescriptor creates a new reference to the wrapped file descriptor owner by other. If other is invalid, *this will also be invalid. The original FileDescriptor is left untouched, and the caller is responsible for destroying it when appropriate. The wrapped file descriptor will be closed automatically when all FileDescriptor instances that reference it are destroyed.

Returns
  A reference to this FileDescriptor

## operator=() [2/2]

FileDescriptor & libcamera::FileDescriptor::operator= | ( | FileDescriptor && | other | ) |

Move assignment operator, replace the wrapped file descriptor by taking over other.

Parameters

  [in] | other | The other FileDescriptor

Moving a FileDescriptor moves the reference to the wrapped descriptor owned by other to the new FileDescriptor. If other is invalid, *this will also be invalid. The other FileDescriptor is invalidated and its fd() method will return -1. The wrapped file descriptor will be closed automatically when all FileDescriptor instances that reference it are destroyed.

Returns
  A reference to this FileDescriptor

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

- include/libcamera/file_descriptor.h
- src/libcamera/file_descriptor.cpp