cosmos::DirStream Class Reference

Access directory contents in the file system. More...

#include <DirStream.hxx>

Public Member Functions
	DirStream ()=default
	Creates an object not associated with a directory.
	DirStream (const DirFD fd)
	Create a DirStream using the given file descriptor.
	DirStream (const DirFD fd, const SysString subpath)
	Open the directory subpath relative to fd.
	DirStream (const SysString path)
	Create a DirStream object operating on the directory at the given path location.
	DirStream (const DirStream &)=delete
DirStream &	operator= (const DirStream &)=delete
	~DirStream ()
	Closes the underlying directory object, if currently open.
void	close ()
	Close the currently associated directory.
void	open (const DirFD fd)
	Associate with the directory represented by the given file descriptor.
void	open (const DirFD dir_fd, const SysString subpath)
	Open the directory subpath relative to fd.
void	open (const SysString path, const FollowSymlinks follow_links=FollowSymlinks{false})
	Associate with the directory at the given file system path location.
auto	isOpen () const
	Indicates whether currently a directory is associated with this object.
DirFD	fd () const
	Return the file descriptor associated with the current DirStream object.
DirEntry::DirPos	tell () const
	Returns the current position in the directory iteration.
void	seek (const DirEntry::DirPos pos)
	Adjust the directory iterator to the given position.
void	rewind ()
	Rewind the directory stream to the beginning.
std::optional< DirEntry >	nextEntry ()
	Returns the next entry in the associated directory.

Protected Member Functions
void	open (const FileNum fd)
void	requireOpenStream (const std::string_view context) const

Protected Attributes
DIR *	m_stream = nullptr

Detailed Description

Access directory contents in the file system.

Using this type you can open directories in the file system either by path or by using an already opened Directory file descriptor. The directory contents can then be iterated over.

Note that the directory contents will be returned by the operating system in an undefined order (i.e. not alphabetically or otherwise sorted). Also entries for "." and ".." by convention should show up and often need to be filtered by applications, if necessary.

Definition at line 30 of file DirStream.hxx.

Constructor & Destructor Documentation

DirStream() [1/3]

cosmos::DirStream::DirStream ( const DirFD fd )

inlineexplicit

Create a DirStream using the given file descriptor.

See also

open(DirFD fd)

Definition at line 40 of file DirStream.hxx.

                                           {
                open(fd);
        }

DirStream() [2/3]

cosmos::DirStream::DirStream ( const DirFD fd, const SysString subpath )

inline

Open the directory subpath relative to fd.

Definition at line 45 of file DirStream.hxx.

                                                           {
                open(fd, subpath);
        }

DirStream() [3/3]

cosmos::DirStream::DirStream ( const SysString path )

inlineexplicit

Create a DirStream object operating on the directory at the given path location.

Definition at line 50 of file DirStream.hxx.

                                                 {
                open(path);
        }

~DirStream()

cosmos::DirStream::~DirStream

(

)

Closes the underlying directory object, if currently open.

Definition at line 14 of file DirStream.cxx.

                      {
        try {
                close();
        } catch (const std::exception &ex) {
                noncritical_error(
                                sprintf("%s: failed to close directory stream", __FUNCTION__),
                                ex);
        }
}

Member Function Documentation

close()

void cosmos::DirStream::close

(

)

Close the currently associated directory.

This will disassociate the DirStream object and further attempts to iterate over directory contents will fail.

If closing causes an error then an exception is thrown, but the state of the DirStream object will be invalidated, to avoid recurring errors trying to close() or reuse the object.

If the object is not currently associated with a directory then a call to this function does nothing.

Definition at line 24 of file DirStream.cxx.

                      {
        if (!m_stream) {
                return;
        }
 
        auto ret = closedir(m_stream);
        m_stream = nullptr;
 
        if (ret == -1) {
                cosmos_throw (ApiError("closedir()"));
        }
}

fd()

DirFD cosmos::DirStream::fd

(

)

const

Return the file descriptor associated with the current DirStream object.

The caller must not modify the state of this file descriptor, otherwise further attempts to iterate over directory contents will result in undefined behaviour. The file descriptor will become invalid after close() is invoked.

Definition at line 95 of file DirStream.cxx.

                          {
        requireOpenStream(__FUNCTION__);
        auto fd = dirfd(m_stream);
        DirFD ret{FileNum{fd}};
 
        if (ret.invalid()) {
                cosmos_throw (ApiError("dirfd()"));
        }
 
        return ret;
}

isOpen()

auto cosmos::DirStream::isOpen ( ) const

inline

Indicates whether currently a directory is associated with this object.

Definition at line 97 of file DirStream.hxx.

{ return m_stream != nullptr; }

nextEntry()

std::optional< DirEntry > cosmos::DirStream::nextEntry

(

)

Returns the next entry in the associated directory.

Calls to this function are only allowed if isOpen() returns true. The validity of the returned object is tied to the lifetime of the DirStream instance it came from. Also any call to nextEntry() will invalidate previously returned DirEntry instances returned from the same DirStream instance.

When the end of the directory has been reached then nullopt is returned.

Definition at line 107 of file DirStream.cxx.

                                           {
        requireOpenStream(__FUNCTION__);
 
        /*
         * there's a bit confusion between readdir and readdir_r(). Today on
         * Linux readdir() is thread-safe between different directory streams
         * but not thread safe when using the same directory stream in
         * parallel. The latter is rather peculiar and should not be needed.
         * Therefore use readdir().
         */
 
        // needed to differentiate between end-of-stream and error condition
        reset_errno();
        const auto entry = readdir(m_stream);
 
        if (entry) {
                return DirEntry{entry};
        }
 
        if (is_errno_set()) {
                cosmos_throw(ApiError("readdir()"));
        }
 
        return {};
}

open() [1/4]

void cosmos::DirStream::open	(	const DirFD	dir_fd,
		const SysString	subpath )

Open the directory subpath relative to fd.

Definition at line 82 of file DirStream.cxx.

                                                                {
 
        const OpenFlags flags{OpenFlag::DIRECTORY};
        auto fd = fs::open_at(dir_fd, subpath, OpenMode::READ_ONLY, flags);
 
        // ownership is transferred to the stream
        m_stream = ::fdopendir(to_integral(fd.raw()));
 
        if (!m_stream) {
                cosmos_throw (ApiError("fdopendir()"));
        }
}

open() [2/4]

void cosmos::DirStream::open

(

const DirFD

fd

)

Associate with the directory represented by the given file descriptor.

The implementation operates on a duplicate of the given file descriptor. You must not modify the file descriptor's state, otherwise the usage of the DirStream object will become undefined.

If the object is already associated with another directory then this previous association will be implicitly close()'d.

Definition at line 67 of file DirStream.cxx.

                                   {
        close();
 
        auto duplicate = fd.duplicate();
        open(duplicate.raw());
}

open() [3/4]

void cosmos::DirStream::open ( const FileNum fd )

protected

Definition at line 74 of file DirStream.cxx.

                                     {
        m_stream = ::fdopendir(to_integral(fd));
 
        if (!m_stream) {
                cosmos_throw (ApiError("fdopendir()"));
        }
}

open() [4/4]

void cosmos::DirStream::open	(	const SysString	path,
		const FollowSymlinks	follow_links = FollowSymlinks{false} )

Associate with the directory at the given file system path location.

If the object is already associated with another directory then this previous association will be implicitly close()'d.

Definition at line 37 of file DirStream.cxx.

                                                                            {
        close();
 
        /*
         * reuse the open(DirFD) logic and only open the file
         * descriptor before. This allows us to pass needful flags like
         * O_CLOEXEC. This gives us more control than when using opendir().
         */
        auto res = ::open(
                path.raw(),
                O_RDONLY | O_CLOEXEC | O_DIRECTORY | (follow_links ? O_NOFOLLOW : 0)
        );
 
        DirFD fd{FileNum{res}};
 
        if (fd.invalid()) {
                cosmos_throw (ApiError("open(O_DIRECTORY)"));
        }
 
        try {
                open(fd.raw());
        } catch (...) {
                // intentionally ignore error conditions here
                try {
                        fd.close();
                } catch(...) {}
                throw;
        }
}

requireOpenStream()

void cosmos::DirStream::requireOpenStream ( const std::string_view context ) const

inlineprotected

Definition at line 158 of file DirStream.hxx.

                                                                   {
                if (!isOpen()) {
                        cosmos_throw (UsageError(std::string(context) + " on unassociated DirStream instance"));
                }
        }

rewind()

void cosmos::DirStream::rewind ( )

inline

Rewind the directory stream to the beginning.

Definition at line 137 of file DirStream.hxx.

                      {
                ::rewinddir(m_stream);
        }

seek()

void cosmos::DirStream::seek ( const DirEntry::DirPos pos )

inline

Adjust the directory iterator to the given position.

pos needs to be previously obtained from tell().

Definition at line 130 of file DirStream.hxx.

                                            {
                requireOpenStream("seek");
 
                ::seekdir(m_stream, to_integral(pos));
        }

tell()

DirEntry::DirPos cosmos::DirStream::tell ( ) const

inline

Returns the current position in the directory iteration.

The returned value needs to be treated opaque, i.e. no assumptions should be made about it. It can merely be used to seek() at a later point in time.

Definition at line 114 of file DirStream.hxx.

                                    {
                requireOpenStream("tell");
 
                auto ret = ::telldir(m_stream);
 
                if (ret == -1) {
                        cosmos_throw (ApiError("telldir()"));
                }
 
                return DirEntry::DirPos{ret};
        }

Member Data Documentation

m_stream

DIR* cosmos::DirStream::m_stream = nullptr

protected

Definition at line 166 of file DirStream.hxx.

---

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

• include/fs/DirStream.hxx
• src/fs/DirStream.cxx