Opens a tar archive for reading, and returns a heap-allocated `struct minitar` which must be freed with `minitar_close()` after using it. If opening the file or allocating the struct fails, returns NULL.
A `struct minitar` is opaque, and should only be passed to other minitar functions. You should not care about its contents.
Reads the next entry from a `struct minitar` which should be the return value of a previous call to `minitar_open()`. The return value is a heap-allocated `struct minitar_entry`, which should be freed with `minitar_free_entry()` when no longer needed.
This structure consists of the file metadata (in the `metadata` field), and a heap-allocated pointer to the file's contents (the `ptr` field), of size metadata.size + a NULL character, for convenience. This means you can use normal C string functions if you're expecting an ASCII file. Other kinds of files may have NULL characters before the end of the file, so you should assume the length of `ptr` is `metadata.size` and not `strlen(ptr)`.
This pointer will be freed when calling `minitar_free_entry()`, so if you're intending to use it later, copy its contents somewhere else.
This function returns NULL on end-of-file (when all entries have been read).
Frees the heap-allocated `struct minitar_entry` and the file contents stored inside it. The pointer passed to `minitar_free_entry()` should be the return value of a previous call to `minitar_read_entry()`, `minitar_find_by_name()` or `minitar_find_any_of()`.
Rewinds the `struct minitar` back to the beginning of the archive file, which means that the next call to `minitar_read_entry()` will return the first entry instead of the entry after the last read entry.
Returns the first entry with a matching name, or NULL if none are found. The return value is a `struct minitar_entry`, which is heap-allocated and should be freed after use with `minitar_free_entry()`. This structure is already documented in the entry documenting `minitar_read_entry()`.
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 return the next matching entry, if there is one. (Calling `minitar_find_by_name()` in a loop until it returns NULL will return all matching entries.)
Does the same thing 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 NULL will return all matching entries.
Closes the tar archive file `mp` points to and frees the heap memory it was using. The pointer passed to `minitar_close()` should be the return value of a previous call to `minitar_open()`.
Other file types supported in tar archives, such as FIFOs or symlinks, are not supported and minitar will throw an error when encountering one of them.
### minitar_entry_metadata
`struct minitar_entry_metadata`
This structure represents an entry's metadata, with the following fields:
`name`: A string representing the full path of the entry within the archive. (`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[]`)
### minitar_entry
`struct minitar_entry`
An entry in a tar archive. Fields:
`metadata`: The entry's metadata. (`struct minitar_entry_metadata`)
`ptr`: A pointer to the entry's contents, heap-allocated. (`char*`)
More details about this structure are available in the documentation for `minitar_read_entry()`.
and put your error handling code in there. This function will automatically override the default one used by minitar.
This function needs to have C linkage and be unmangled. If you're using other languages, this might not be the case, for example, a C++ implementation would need the following signature:
