TarWriter Class Reference

#include <Pt/System/TarWriter.h>

Blocking writer for tar archives (Pax/UStar format). More...

Public Member Functions
	TarWriter ()
	Default constructor.
	TarWriter (std::ostream &os)
	Constructor attaching to os.
	~TarWriter ()
	Destructor.
void	attach (std::ostream &os)
	Attach to an output stream.
void	detach ()
	Detach from the current output stream.
void	reset ()
	Detach from the current output stream and reset state.
void	addFile (const Pt::System::Path &path, const char *data, std::size_t size, Pt::System::FileInfo::Perms permissions)
	Write a regular file entry. More...
void	addDirectory (const Pt::System::Path &path, Pt::System::FileInfo::Perms permissions)
	Write a directory entry. More...
void	addSymlink (const Pt::System::Path &path, const Pt::System::Path &target)
	Write a symbolic-link entry. More...
void	addHardlink (const Pt::System::Path &path, const Pt::System::Path &target)
	Write a hard-link entry. More...
void	beginFile (const Pt::System::Path &path, std::size_t totalSize, Pt::System::FileInfo::Perms permissions)
	Begin writing a regular file entry for streaming. More...
void	writeFile (const char *data, std::size_t size)
	Write a chunk of data for the current streaming file entry. More...
void	endFile ()
	Finish the current streaming file entry started by beginFile(). More...
void	finish ()
	Write the end-of-archive marker (two 512-byte null blocks).

Detailed Description

TarWriter writes entries sequentially into a tar archive. All operations are synchronous and write directly to the attached std::ostream.

Use addFile(), addDirectory(), addSymlink(), or addHardlink() to write complete entries in a single call. For large files, use the streaming API: beginFile() writes the header, writeFile() delivers the content in one or more chunks, and endFile() closes the entry.

Always call finish() before closing the stream to write the mandatory end-of-archive marker. Paths are interpreted as UTF-8; Pax extended headers are written automatically for long or non-ASCII paths.

std::ofstream ofs("archive.tar", std::ios::binary);
TarWriter writer(ofs);
 
// complete entries
writer.addDirectory(Pt::System::Path("src/"), dirPerms);
writer.addFile(Pt::System::Path("src/main.cpp"),
               src.data(), src.size(), filePerms);
 
// streaming a large file
writer.beginFile(Pt::System::Path("data.bin"), totalSize, filePerms);
writer.writeFile(chunk1, size1);
writer.writeFile(chunk2, size2);
writer.endFile();
 
writer.finish();

Member Function Documentation

addFile()

void addFile	(	const Pt::System::Path &	path,
		const char *	data,
		std::size_t	size,
		Pt::System::FileInfo::Perms	permissions
	)

Parameters

path	Archive path (UTF-8).
data	File content buffer.
size	Number of bytes in data.
permissions	POSIX permission bits.

addDirectory()

void addDirectory	(	const Pt::System::Path &	path,
		Pt::System::FileInfo::Perms	permissions
	)

Parameters

path	Archive path (UTF-8).
permissions	POSIX permission bits.

addSymlink()

void addSymlink	(	const Pt::System::Path &	path,
		const Pt::System::Path &	target
	)

Parameters

path	Archive path (UTF-8).
target	Link target path (UTF-8).

addHardlink()

void addHardlink	(	const Pt::System::Path &	path,
		const Pt::System::Path &	target
	)

Parameters

path	Archive path of the new link (UTF-8).
target	Archive path of the existing file to link to (UTF-8).

beginFile()

void beginFile	(	const Pt::System::Path &	path,
		std::size_t	totalSize,
		Pt::System::FileInfo::Perms	permissions
	)

Writes the archive header for a file of the given total size. Subsequent calls to writeFile() deliver the content bytes; endFile() must be called once all data has been written.

Parameters

path	Archive path (UTF-8).
totalSize	Total byte count that will be written via writeFile().
permissions	POSIX permission bits.

writeFile()

void writeFile	(	const char *	data,
		std::size_t	size
	)

May be called multiple times after beginFile() until all totalSize bytes have been written. The sum of all size arguments must equal the totalSize passed to beginFile().

Parameters

data	Pointer to data bytes.
size	Number of bytes to write.

Exceptions

Pt::IOError

if size exceeds the remaining byte count declared in beginFile().

endFile()

void endFile

(

)

Writes the 512-byte block-alignment padding.

Exceptions

Pt::IOError

if not all bytes declared in beginFile() have been written via writeFile().