From f09e6f2e8536a57b37a297c30a840b77661fd13c Mon Sep 17 00:00:00 2001 From: apio Date: Sat, 4 Feb 2023 19:33:23 +0100 Subject: [PATCH] docs: Add documentation for the new "writing" API --- docs/API.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 58 insertions(+), 1 deletion(-) diff --git a/docs/API.md b/docs/API.md index f22a68f..5cd52f7 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1,11 +1,18 @@ # 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` structure 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` structure 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)` @@ -17,6 +24,30 @@ To read the contents of an entry, you should allocate a buffer large enough to h 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](README.md#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)` @@ -64,6 +95,13 @@ Closes the tar archive file `mp` points to. The pointer passed to `minitar_close 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 @@ -87,6 +125,15 @@ This enum lists all supported file types: Other file types supported in tar archives, such as block/character devices or FIFOs, are not supported and minitar will throw an error when encountering one of them. This behavior can be controlled by passing `-DMINITAR_IGNORE_UNSUPPORTED_TYPES=ON` to CMake when configuring, which will make minitar silently ignore such entries instead of panicking. +### 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` @@ -125,4 +172,14 @@ 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`) \ No newline at end of file +`_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. \ No newline at end of file