molib documentation

Languages Available: français español

CLASS

moTar::moTarHeader

NAME

Contructor - creates an empty header

VERSION

Version: 1.2.0

SYNOPSIS

moTarHeader(void);

DESCRIPTION

To insert a new file in a tar stream, you need to have a header. Use this object to create the header. Then use all the necessary Set...() functions to define all the necessary fields.

SEE ALSO

moOTar, moITar

COPYRIGHTS

This documentation and the code being documented is proprietary and cannot be duplicated without the express and written consent of Made to Order Software Coporation.

Copyright (c) 1999-2007 by Made to Order Software Corporation
All rights reserved.

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moTar::moTarHeader

NAME

Reset - resets a tar header so you can use it again

VERSION

Version: 1.2.0

SYNOPSIS

void Reset(void);

DESCRIPTION

The Reset() function will be called once you are done with a file before to re-use the same tar header object to save another file.

SEE ALSO

Constructor, Set...

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moTar::moTarHeader

NAME

SetName - defines the filename (in full)
SetLinkTo - when defining a link, where it points to
SetUserName - the name of the owner
SetGroupName - the name of the group it belongs to
SetID - set the user and group identifiers numerically
SetMode - the standard mode (as with chmod())
SetSize - set the size in bytes of the file
SetModifTime - defines the last modification time
SetDevice - sets the major and minor device numbers (block device file)

VERSION

Version: 1.2.0

SYNOPSIS

void SetName(const moWCString& name);
void SetLinkTo(const moWCString& link_to);
void SetUserName(const moWCString& user_name);
void SetGroupName(const moWCString& group_name);
void SetID(uid_t uid, gid_t gid);
void SetMode(mode_t mode);
void SetSize(size_t size);
void SetModifTime(time_t time);
void SetDevice(dev_t device);

PARAMETERS

name - the filename
link_to - a filename where the link points
user_name - the name of the owner
group_name - the name of the group
uid - the user identification number
gid - the group identification number
mode - a mode specification
size - the total size of the file in bytes
time - the last modification time (Unix time)
device - the major & minor block device number

DESCRIPTION

Use all of the Set() functions that you can to determine a tar header as well as you can. This is useful to save as much information as possible. All the undefined information will automatically be filled in with defaults when not defined except for the name.

It is usually not necessary to define both, the user and group names and IDs. The IDs will be searched by name when only the names are given and vice versa.

When the tar object is used to save files, then most of the information will be gathered through the moIStream specified to the AppendFile() function. However, it is always a good idea to define the header to the best of your knowledge before to call the append functions.

Once you are done with a header current setup, you can call the Reset() function to clear everything at once.

If you have a major & minor device number, you can generate the device number using the following macro:

makedev(dev_major, dev_minor);

Similarly, you can extract these numbers with:

dev_major = major(device); dev_minor = minor(device);

SEE ALSO

Get...(), Reset()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moTar::moTarHeader

NAME

GetType - retrieve the type of this entry
GetName - retrieve the filename
GetLinkTo - retrieve the link to which it points
GetUserName - retrieve the name of the owner
GetGroupName - retrieve the name of the group
GetMode - retrieve the mode
GetID - retrieve the user and group identification numbers
GetSize - retrieve the file size in bytes
GetModifTime - retrieve the last modification time (a Unix time)
GetDevice - retrieve the device major & minor numbers

VERSION

Version: 1.2.0

SYNOPSIS

bool GetName(moWCString& name) const;
bool GetLinkTo(moWCString& link_to) const;
bool GetUserName(moWCString& user_name) const;
bool GetGroupName(moWCString& group_name) const;
bool GetMode(mode_t& mode) const;
bool GetID(uid_t& uid, gid_t& gid) const;
bool GetSize(size_t& size) const;
bool GetModifTime(time_t& time) const;
bool GetDevice(dev_t& device) const;

DESCRIPTION

The Get() functions will read the header data and return true if the corresponding data was defined by the user.

Note that when a Get() function returns false, the input parameter remains unchanged. In other words, it is possible to define a default.

SEE ALSO

Set, Reset

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moTar::moTarHeader

NAME

CopyMost - copy everything except the filename, link & type

VERSION

Version: 1.2.0

SYNOPSIS

void CopyMost(const moTarHeader& header);

PARAMETERS

header - the header to copy from

DESCRIPTION

This function will be used when it is necessary to force some parameters to a specific value while creating a tar file. For instance, one may want to make sure that all the files are owned by a specific user (such as root), that all have a mode of a+r, all have a modification time set to the exact same value without having to change the date on the input files, etc.

The function will test for defined values in the header and copy what is necessary to this tar header object.

Everything is copied except the prefix, name, link to, device IDs, the size and the type which are too specific to the file being saved.

Note that the mode will be copied except if the destination is of type directory in which case the execution flags are merged instead of being copied.

SEE ALSO

Set...()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moOTar::moTarHeader

NAME

Define - get file information for the tar header

VERSION

Version: 1.2.0

SYNOPSIS

bool Define(const moWCString& filename, const moWCString& root);

PARAMETERS

filename - the name of the directory to put in the output tar
root - the root path not to be included

DESCRIPTION

This function can be used to initialize an moTarHeader from the information gathered via the system about the specified file.

The root path is used to simulate a cd into that directory and thus that path will be removed from the path present in the header name (if it matches).

NOTES

The user and group names are not determined here. This is anyway automatic in the tar_header_t.ConvertFrom() function.

RETURN VALUE

the function returns true when successful

SEE ALSO

AppendDirectory, AcceptFile

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moTar::tar_header_t

NAME

ConvertFrom - convert from an moTagHeader to a tar_header_t
ConvertTo - convert to an moTagHeader from a tar_header_t

VERSION

Version: 1.2.0

SYNOPSIS

void ConvertFrom(const moTarHeader& header);
void ConvertTo(moTarHeader& header);

PARAMETERS

header - an moTarHeader object to copy from or to

DESCRIPTION

When the moOTar object is ready to save an input file, buffer, etc. it needs to convert a tar_header_t to an moTarHeader. This is done with the ConvertFrom() function.

Similarly, the moITar converts the tar_header_t it reads from the input file into an moTarHeader with ConvertTo().

RETURN VALUE

When the convertion from an moTarHeader to a tar_header_t
fails (name too long or no name in most cases), then it
returns false, otherwise true is returned.

The errno is set to one of the following errors:

ENOENT no name was defined

ENAMETOOLONG name can't fit in a tar file

EINVAL the file type is not acceptable
for the information available

SEE ALSO

moTarHeader functions

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moOTar

NAME

Constructor - creates an moOTar object
Destructor - cleans up an moOTar object

VERSION

Version: 1.2.0

SYNOPSIS

moOTar(void);
moOTar(moOStream *output);
~moOTar();

private:
void Init(void);

PARAMETERS

output - the tar output stream

DESCRIPTION

The constructors will initialize the output tar object.

NOTE: the output stream will be handed to the tar object, the means the tar object should be the only one writing to it. Also, it will automatically close it on destruction.

The destructor will ensure that the file is properly ended and then closed. This means the output file given by the user won't be usable afterward.

SEE ALSO

SetOutput

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moOTar

NAME

SetOutput - sets the output to the specified stream

VERSION

Version: 1.2.0

SYNOPSIS

void SetOutput(moOStream *output);
moOStreamSPtr Output(void) const;

PARAMETERS

output - the new output stream

DESCRIPTION

The SetOutput() function assigns an output stream to the output tar object. After this calls, the stream should be viewed as the property of the tar object until the tar object is destroyed or another stream is assigned to that same tar object. After a call to the SetOutput() the caller can Release() the output stream safely.

A previous output object will get it's Release() function called whenever it is removed from a tar object.

The Output() function returns a pointer to the output object previously linked to the tar object using the SetOutput() function.

SEE ALSO

Init, Constructors, Destructor, Output

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moOTar

NAME

AppendHeader - append a header which doesn't require data

VERSION

Version: 1.2.0

SYNOPSIS

bool AppendHeader(const moTarHeader& header);

PARAMETERS

header - an initialized tar file header

DESCRIPTION

The AppendHeader() function creates an entry in the tar file for an object which doesn't require any data to be saved.

It will be used for all the special files such as devices, directories and links.

Note that you could also use the AppendBuffer() with a size of zero.

SEE ALSO

AppendFile, AppendStream, AppendBuffer

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moOTar

NAME

AppendBuffer - append a buffer as if it were a file

VERSION

Version: 1.2.0

SYNOPSIS

bool AppendBuffer(const moTarHeader& header, const void *data, size_t size);

PARAMETERS

header - an initialized tar file header
data - a pointer to a buffer
size - the size of the data buffer

DESCRIPTION

The AppendBuffer() function writes the data pointed by data to the output tar file.

The size can be zero (in which case the data pointer can be null) in which case the type of the file being added must be an empty type (such as SYMTYPE, LNKTYPE, DIRTYPE). It is also possible to include empty regular files, etc. in which case you can also have an empty buffer.

SEE ALSO

AppendFile, AppendStream

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moOTar

NAME

AppendStream - copy the stream data to the output tar

VERSION

Version: 1.2.0

SYNOPSIS

bool AppendStream(const moTarHeader& header, moIStream& input);

PARAMETERS

header - the tar file header representing input
input - the input stream to read from

DESCRIPTION

The AppendStream() function reads data from an input stream and writes it to this output tar file.

It first converts the header into a tar file header and saves that. This header should be information about the input file being saved in the tape archive.

The number of bytes which will be read from the input stream is the size defined in the header parameter, not the size of the input stream (thus the input stream doesn't need to be able to return a size).

The input stream should at least have that many bytes available.

NOTES

because you may be trying to save a directory structure from a set of files which may not all be placed in a similar directory tree, the header won't be changed by this function.

We will have to have helper functions to setup headers from different sources such as a filename.

RETURN VALUE

when the file is properly duplicated in the tar file, this
function returns true; if an error occurs converting the
header, reading the input stream or writing to this out
tar file, then false is returned

SEE ALSO

AppendBuffer, AppendFile

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moOTar

NAME

AppendFile - append a file specified by filename

VERSION

Version: 1.2.0

SYNOPSIS

bool AppendFile(const moTarHeader& header, const moWCString& filename);

PARAMETERS

header - the header saved in the tar file
filename - the name of the file to copy in the output tar

DESCRIPTION

The AppendFile() function will read an entire file from disk and copy it in the output tar file.

The tar header should correspond to the file being saved in the file.

This function is a wrapper of the AppendStream() function. It just opens the file for you before to call the AppendStream() function.

NOTES

The header isn't modified by the function, thus it has to be properly setup before a call to this function.

Please, see the AppendStream() function for more information about the header.

RETURN VALUE

The function returns true when nothing goes wrong, false otherwise.

SEE ALSO

AppendBuffer, AppendStream

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moOTar

NAME

AppendDirectory - append a directory and all the files within

VERSION

Version: 1.2.0

SYNOPSIS

bool AppendDirectory(const moTarHeader& header, const moWCString& path, const moWCString& root);
bool AppendDir(const moTarHeader& header, const moDirectory& dir, const moWCString& root);

PARAMETERS

header - the header saved in the tar file
path - the name of the directory to copy to the output tar
dir - if you already have a directory instead of just a path
root - the root path not to be included

DESCRIPTION

The AppendDirectory() function reads an entire directory tree from disk and copy all the files it in the output tar file.

The AppendDir() function uses an existing directory and saves all the files present in it in the output tar file.

The tar headers are created using the files inserted in the tar file for the names, most of the other parameters can be overwriten by passing a tar header with defined parameters (thus, you can force a specific user name and mode to be copied for all the files). For more information about which information is copied, please look at the CopyMost() function of the moTarHeader object.

For each regular file, the AppendFile() function will be called. For other files, the AppendHeader() function is used instead. More than one directory can be included in the same tar file.

The root path can be set to anything within the filename path. It will then be removed from all the filenames (in effect, it simulates a cd to the root path before the filenames are inserted, except ../ won't be generated).

One can derive the moOTar object in order to apply a filter on the files to be included. You can then reject some files from being included (because these are backup files, object files which can be regenerated, etc.) The function to be overwritten is AcceptFile(). This can also be reached by creating your own moDirectory list.

NOTES

Please, see the AppendStream() and moTarHeader::Define functions for more information about the header.

RETURN VALUE

The function returns true when nothing goes wrong, false otherwise.

SEE ALSO

AppendBuffer, AppendStream, AppendHeader moTarHeader::CopyMost, moTarHeader::Define

BUGS

The errno value is usually invalid at the time the function returns. We may add a LastErrno() function at a later time if it seems to be necessary.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

Links:
molib
the sandbox