#include <Pt/System/TarEntry.h>
One entry in a tar archive. More...
Public Types | |
| enum | Type { Invalid = 0 , File = 1 , Directory = 2 , Link = 3 , Hardlink = 4 } |
| Kind of archive member. More... | |
Public Member Functions | |
| TarEntry ()=default | |
| Creates an entry with no metadata and an empty content window. | |
| TarEntry (TarEntry &&)=default | |
| Move constructor. | |
| TarEntry & | operator= (TarEntry &&)=default |
| Move assignment. | |
| ~TarEntry ()=default | |
| Destructor. | |
| void | clear () |
| Resets every field to the default-constructed state. | |
| bool | isEnd () const |
| Returns true when every content byte has been delivered. | |
| const Pt::System::Path & | path () const |
| Returns the archive path. | |
| std::size_t | size () const |
| Returns the content length declared in the archive header. | |
| std::size_t | avail () const |
| Returns the number of bytes readable at data(). | |
| const char * | data () const |
| Returns the current content chunk of avail() bytes. | |
| Type | type () const |
| Returns the member kind. | |
| const Pt::System::Path & | linkTarget () const |
| Returns the target of a symbolic link or a hard link. | |
| Pt::System::FileInfo::Perms | permissions () const |
| Returns the POSIX permission bits. | |
| const Pt::DateTime & | mtime () const |
| Returns the modification time in UTC. | |
| Pt::uint32_t | ownerId () const |
| Returns the numeric owner id. | |
| const Pt::String & | ownerName () const |
| Returns the owner name. | |
| Pt::uint32_t | groupId () const |
| Returns the numeric group id. | |
| const Pt::String & | groupName () const |
| Returns the group name. | |
| void | setPath (const Pt::System::Path &path) |
| Sets the archive path. | |
| void | setSize (std::size_t size) |
| Sets the content length declared in the header. | |
| void | setType (Type type) |
| Sets the member kind. | |
| void | setLinkTarget (const Pt::System::Path &target) |
| Sets the target of a symbolic link or a hard link. | |
| void | setPermissions (Pt::System::FileInfo::Perms permissions) |
| Sets the POSIX permission bits. | |
| void | setMtime (const Pt::DateTime &mtime) |
| Sets the modification time in UTC. | |
| void | setOwnerId (Pt::uint32_t id) |
| Sets the numeric owner id. | |
| void | setOwnerName (const Pt::String &name) |
| Sets the owner name. | |
| void | setGroupId (Pt::uint32_t id) |
| Sets the numeric group id. | |
| void | setGroupName (const Pt::String &name) |
| Sets the group name. | |
Static Public Attributes | |
| static const Pt::uint32_t | NoId = static_cast<Pt::uint32_t>(-1) |
| Id value meaning that no numeric id is set. | |
A TarEntry is the metadata of one member of a tar archive, together with a window onto that member's content. TarReader publishes an entry after it has parsed the header. TarWriter consumes an entry the caller has filled in. The same type travels in both directions, so a value read from one archive can be handed to a writer and reproduced, including owner, group, permissions, and modification time.
The metadata is the part the caller owns. path() is the name inside the archive. type() distinguishes a regular file, a directory, a symbolic link, and a hard link. A link also has linkTarget(). size() is the content length stored in the header. permissions() holds the POSIX permission bits, including the set-user-ID, set-group-ID, and sticky bits. mtime() is the modification time in UTC. A default-constructed Pt::DateTime means the Unix epoch, and that is what the writer stores when the caller never sets a time.
Owner and group are each an optional numeric id plus an optional name. NoId means the archive did not carry an id, or the caller has not set one. Numeric id 0 is a real value: it is the root user or the root group, and it is written and read as such. An empty Pt::String means the archive did not carry a name. A name that happens to be root is a real name and round-trips. The writer omits an unset id and an empty name. It does not invent root or id 0. Names are Unicode. The archive stores them as UTF-8, in the UStar header when they fit and in a Pax extended header otherwise.
The content window is the part TarReader fills in. After TarReader::advance() returns an entry, up to avail() bytes are readable at data(). Those bytes must be consumed before the next call to advance(), because the reader reuses its buffer and the pointer then refers to a different chunk, or to nothing. isEnd() becomes true once every byte of size() has been delivered. A directory, a symbolic link, and a hard link have no content, so isEnd() is already true when the entry is first published. TarWriter does not read the content window. The bytes of a file are the buffer passed to TarWriter::addFile(), or the chunks passed to TarWriter::writeFile(). size() on the entry is the length the writer declares in the header, and for a streamed file it is the total that writeFile() must deliver before endFile().
An entry returned by the reader stays valid until the next advance() call, which replaces its metadata and its content window. A caller who wants to keep an entry copies the fields out. The content pointer cannot be kept: it addresses the reader's buffer.
| enum Type |
| bool isEnd | ( | ) | const |
For a directory or a link this is true as soon as the reader publishes the entry. For a file it becomes true on the advance() call that delivers the last byte. The following advance() call moves to the next archive member.
| std::size_t avail | ( | ) | const |
Valid until the next TarReader::advance() call.
| const char * data | ( | ) | const |
The pointer addresses the reader's buffer and becomes invalid on the next TarReader::advance() call. A chunk of length zero returns a null pointer.
| const Pt::System::Path & linkTarget | ( | ) | const |
Empty for a file or a directory.
| Pt::System::FileInfo::Perms permissions | ( | ) | const |
Includes the set-user-ID, set-group-ID, and sticky bits when the archive stored them.
| const Pt::DateTime & mtime | ( | ) | const |
A default-constructed Pt::DateTime is the Unix epoch. That is the value of an entry whose archive header carried time 0, and the value the writer stores when the caller never sets a time.
| Pt::uint32_t ownerId | ( | ) | const |
NoId means the archive carried no uid, or the caller has not set one. Numeric id 0 is the root user.
| const Pt::String & ownerName | ( | ) | const |
Empty when the archive carried no owner name, or the caller has not set one.
| Pt::uint32_t groupId | ( | ) | const |
NoId means the archive carried no gid, or the caller has not set one. Numeric id 0 is the root group.
| const Pt::String & groupName | ( | ) | const |
Empty when the archive carried no group name, or the caller has not set one.
| void setSize | ( | std::size_t | size | ) |
For TarWriter::beginFile() this is the total number of bytes that TarWriter::writeFile() must deliver.
| void setOwnerId | ( | Pt::uint32_t | id | ) |
Pass NoId to clear a previously set id.
| void setOwnerName | ( | const Pt::String & | name | ) |
An empty name clears a previously set name and is omitted from the archive.
| void setGroupId | ( | Pt::uint32_t | id | ) |
Pass NoId to clear a previously set id.
| void setGroupName | ( | const Pt::String & | name | ) |
An empty name clears a previously set name and is omitted from the archive.
|
static |
Distinct from numeric id 0, which is the root user or the root group.