minitar/docs/API.md

minitar API documentation

Functions/types suffixed with _w or that contain write in their names are part of the newer API for writing to archives. Other types/functions are part of the (older) API for reading archives.

Functions

minitar_open

int minitar_open(const char* pathname, struct minitar* mp)

Initializes the caller-provided mp handle by opening the archive pointed to by pathname for reading. Returns 0 on success, anything else is failure.

minitar_open_w

int minitar_open_w(const char* pathname, struct minitar_w* mp, enum minitar_write_mode mode)

Initializes the caller-provided mp handle by opening the archive pointed to by pathname for writing (in case pathname already exists, mode selects if the existing file is overwritten or if new entries are appended to it). Returns 0 on success, anything else is failure.

minitar_read_entry

int minitar_read_entry(struct minitar* mp, struct minitar_entry* out)

Reads the next entry from a struct minitar which should be initialized by a previous call to minitar_open() and stores the result in out.

The minitar_entry structure consists of the file metadata (in the metadata field), and other internally-used values.

To read the contents of an entry, you should allocate a buffer large enough to hold metadata.size bytes and pass it to minitar_read_contents().

This function returns 0 on success and -1 on end-of-file (when all entries have been read).

minitar_write_file_entry

int minitar_write_file_entry(struct minitar_w* mp, const struct minitar_entry_metadata* metadata, char* buf)

Writes a regular file entry into a struct minitar_w which should be initialized by a previous call to minitar_open_w().

This function writes both a header (generated from the metadata) and the file contents in buf, which should be metadata.size bytes long.

This function will only write entries for regular files (metadata.type == MTAR_REGULAR). It will ignore the type field and write the "regular file" type into the tar archive.

To write any other kind of entry (directories, special files), use minitar_write_special_entry.

This function returns 0 on success.

minitar_write_special_entry

int minitar_write_special_entry(struct minitar_w* mp, const struct minitar_entry_metadata* metadata)

Writes a special file entry (anything that does not have contents, so directories or special files) into a struct minitar_w which should be initialized by a previous call to minitar_open_w().

This function only writes a header (generated from the metadata). The size field is written as 0, no matter what its original value was.

This function does not write entries for regular files (metadata.type == MTAR_REGULAR). Trying to do so will result in minitar panicking (see error handling). To write regular files, use minitar_write_file_entry.

This function returns 0 on success.

minitar_rewind

void minitar_rewind(struct minitar* mp)

Rewinds the struct minitar back to the beginning of the archive file, which means that the next call to minitar_read_entry() will fetch the first entry instead of the entry after the last read entry.

minitar_find_by_name

int minitar_find_by_name(struct minitar* mp, const char* name, struct minitar_entry* out)

Stores the first entry with a matching name in out and returns 0, or non-zero if none are found. If none are found, the state of out is unspecified and might have been changed by the function. (In this context, a "name" means the base name of a file, so baz.txt given the path foo/bar/baz.txt)

This function starts searching from the current archive position, which means that to find a matching entry in the entire archive minitar_rewind() should be called on it first.

The state of mp after minitar_find_by_name() returns is unspecified, but a successive call to minitar_find_by_name() will find the next matching entry, if there is one. (Calling minitar_find_by_name() in a loop until it returns non-zero will return all matching entries.)

In order to perform other minitar operations on the archive, minitar_rewind() should probably be called first, to get a known state.

minitar_find_by_path

int minitar_find_by_path(struct minitar* mp, const char* path, struct minitar_entry* out)

Same as minitar_find_by_name(), but matches the full path inside the archive instead of the file name.

minitar_find_any_of

int minitar_find_any_of(struct minitar* mp, enum minitar_file_type type, struct minitar_entry* out)

Same as minitar_find_by_name(), but matches the file type instead of the name. As with minitar_find_by_name(), this function starts searching from the current archive position and calling it in a loop until it returns -1 will find all matching entries.

minitar_read_contents

size_t minitar_read_contents(struct minitar* mp, const struct minitar_entry* entry, char* buf, size_t max)

Reads up to max bytes of an entry's contents from the archive stream mp and stores them into buf.

This function can be called as many times as desired, and at any given point in time, provided both mp and entry are valid. (mp should be initialized by a previous call to minitar_open(), and entry initialized by a previous call to minitar_read_entry(), minitar_find_by_name(), minitar_find_by_path() or minitar_find_any_of()).

This function returns the number of bytes read, or 0 on error. 0 might also be a successful return value (if max is 0 or the entry's size is 0, for example), which means errno should be checked to see if 0 means error or simply 0 bytes read.

minitar_read_contents() will never read more than metadata.size, regardless of the value in max. (so, if max == SIZE_MAX, minitar_read_contents() will always read metadata.size bytes).

The contents are not null-terminated. If you want null-termination (keep in mind the contents might not be ASCII and might contain null bytes before the end), just do buf[nread] = 0;. In that case, the value of max should be one less than the size of the buffer, to make sure the zero byte is not written past the end of buf if max bytes are read.

minitar_close

int minitar_close(struct minitar* mp)

Closes the tar archive file mp points to. The pointer passed to minitar_close() should be initialized by a previous call to minitar_open().

Returns 0 on success, everything else is failure and you should check errno.

minitar_close_w

int minitar_close_w(struct minitar_w* mp)

Closes the tar archive file mp points to. The pointer passed to minitar_close_w() should be initialized by a previous call to minitar_open_w().

Returns 0 on success, everything else is failure and you should check errno.

Types

minitar_file_type

enum minitar_file_type

This enum lists all supported file types:

MTAR_REGULAR: Regular files

MTAR_DIRECTORY: Directories

MTAR_SYMLINK: Symbolic links

MTAR_HARDLINK: Hard links

MTAR_FIFO: FIFO special files

MTAR_BLKDEV: Block devices

MTAR_CHRDEV: Character devices

minitar_write_mode

enum minitar_write_mode

This enum tells minitar_open_w what to do if the chosen archive path already exists:

MTAR_OVERWRITE: Overwrite the archive

MTAR_APPEND: Add new entries to the end of it

minitar_entry_metadata

struct minitar_entry_metadata

This structure represents an entry's metadata, with the following fields:

path: A string representing the full path of the entry within the archive. (char[])

name: A string representing the base name of the entry (the last component of its path). (char[])

link: A string representing the file being linked to. (Only applies to symlinks/hard links) (char[])

mode: An integer representing the permissions of the entry. (mode_t)

uid: An integer representing the user ID of the entry's owner. (uid_t)

gid: An integer representing the group ID of the entry's owner. (gid_t)

size: An integer representing the size of the entry's contents in bytes. (size_t)

mtime: A UNIX timestamp representing the last time the entry was modified. (time_t)

type: An enum representing the type of the entry. (enum minitar_file_type)

uname: A string representing the username of the entry's owner. (char[])

gname: A string representing the group name of the entry's owner. (char[])

devmajor: An integer representing the major number of a device. (unsigned int)

devminor: An integer representing the minor number of a device. (unsigned int)

minitar_entry

struct minitar_entry

An entry in a tar archive. Fields:

metadata: The entry's metadata. (struct minitar_entry_metadata)

_internal: Reserved for internal use. (struct minitar_entry_internal)

minitar

struct minitar

An archive handle for the "reading" API. To write to an archive, use struct minitar_w and minitar_open_w() instead.

minitar_w

struct minitar_w

An archive handle for the "writing" API. To read from an archive, use struct minitar and minitar_open() instead.