TarReader Class Reference

#include <Pt/System/TarReader.h>

Incremental reader for tar archives (Pax/UStar format). More...

Public Member Functions
	TarReader ()
	Default constructor.
	TarReader (std::istream &is)
	Constructor attaching to is.
	~TarReader ()
	Destructor.
void	attach (std::istream &is)
	Attach to an input stream.
void	detach ()
	Detach from the current input stream.
void	reset ()
	Reset state and detach from the input stream.
void	reset (std::istream &is)
	Reset state and attach to a new input stream.
const TarEntry *	advance (std::streamsize importSize=0)
	Advance to the next entry or deliver the next content chunk. More...
bool	isEnd () const
	Returns true when the end-of-archive marker has been read.

Detailed Description

TarReader parses a tar archive from a std::istream one entry at a time. It is designed for non-blocking use: advance() delivers only the bytes already in the stream buffer and returns nullptr when the stream is starved.

Call advance() in a loop. A non-null return value holds a TarEntry with the current entry's metadata and the first content chunk. Read TarEntry::data() for TarEntry::avail() bytes, then call advance() again to fetch the next chunk. Repeat until TarEntry::isEnd() is true, then call advance() once more to move to the next archive entry. The loop ends when isEnd() on the reader itself returns true.

Pass a non-zero importSize to advance() to read more bytes from the stream per call — this may block and is suitable for file-based use.

Pax extended headers handle long paths (> 99 characters), UTF-8 paths, and extended modification times automatically.

TarReader reader(stream);
 
while( ! reader.isEnd() )
{
    const TarEntry* entry = reader.advance();
    if( ! entry )
        break; // not enough data, call advance() again when more arrives
 
    if(entry->type() == TarEntry::File)
    {
        do
        {
            outFile.write(entry->data(), entry->avail());
            if(entry->isEnd())
                break;
            entry = reader.advance();
        }
        while(entry);
    }
}

Member Function Documentation

advance()

const TarEntry* advance

(

std::streamsize

importSize = 0

)

Each call consumes the bytes previously exposed via TarEntry::data() and fetches the next data from the stream. Process TarEntry::data() before calling advance() again — the buffer is reused on each call.

When importSize is 0 (default), only bytes already in the stream buffer are used and no blocking I/O is performed, making this safe for event-loop use. A value greater than 0 allows reading up to that many additional bytes from the stream, which may block.

Parameters

importSize

Maximum bytes to read from the stream; 0 is non-blocking.

Returns

Pointer to the current TarEntry once a header has been parsed, or nullptr when the stream is starved and more data is needed.