libcamera::FileDescriptor Class Reference

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...
ino_t	inode () const
	Retrieve the file descriptor inode. 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 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 functions 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() function. 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() function 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() function 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() function 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() function 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

inode()

ino_t libcamera::FileDescriptor::inode

(

)

const

Retrieve the file descriptor inode.

Todo:

Should this move to the File class ?

Returns

The file descriptor inode on success, or 0 on error

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() function 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