Do not automatically read an entry's contents, leave it up to the user

This API change modifies minitar_read_entry to skip over the file's contents and instead store the current read position in the entry.

struct minitar_entry no longer has a ptr field, but has a position field (of type fpos_t) for internal use.

minitar_free_entry no longer frees entry->ptr.

A new function has been added, minitar_read_contents().
It reads a certain number of bytes from an entry (which is capped to the entry's size) into a user-provided buffer.
This function can be called at any time provided it is called with a valid archive stream and entry.
This is achieved by calling fgetpos() to store the start of the entry's contents in the entry's position field while reading it.
Then minitar_read_contents() will store the current position, rewind to the entry's position, read the chosen number of bytes from the archive, and then rewind back to the current position.

Since this is a breaking change, it needs a major version bump. Since there was no version, I bumped it to 1.0.0 :)

CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required(VERSION 3.8..3.22)
 
-project(minitar C)
+project(minitar LANGUAGES C VERSION 1.0.0)
 
 set(SOURCES
     src/tar.c

README.md

@@ -48,16 +48,16 @@ A `struct minitar` is opaque, and should only be passed to other minitar functio
 
 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 structure consists of the file metadata (in the `metadata` field), and other internally-used values.
 
-This pointer will be freed when calling `minitar_free_entry()`, so if you're intending to use the file's contents later, copy them somewhere else.
+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 NULL on end-of-file (when all entries have been read).
 
 ### minitar_free_entry
 `void minitar_free_entry(struct minitar_entry* entry)`
 
-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()`.
+Frees the heap-allocated `struct minitar_entry`. 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()`.
 
 ### minitar_rewind
 `void minitar_rewind(struct minitar* mp)`
@@ -80,6 +80,19 @@ In order to perform other minitar operations on the archive, `minitar_rewind()`
 
 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.
 
+### minitar_read_contents
+`size_t minitar_read_contents(struct minitar* mp, 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 the return value of a previous call to `minitar_open()`, and `entry` the return value of a previous call to `minitar_read_entry()`, `minitar_find_by_name()` 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()` only reads up to `metadata.size`, regardless of the value in `max`.
+
+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)`
 
@@ -134,9 +147,7 @@ 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*`)
+`position`: Reserved for internal use. (`fpos_t`)
-
-More details about this structure are available in the documentation for `minitar_read_entry()`.
 
 ## Error handling
 

minitar.h

@@ -1,9 +1,9 @@
 #ifndef MINITAR_H
 #define MINITAR_H
+#include <stdio.h>
 #include <sys/types.h>
 
 #ifdef _IN_MINITAR
-#include <stdio.h>
 struct minitar
 {
     FILE* stream;
@@ -36,7 +36,7 @@ struct minitar_entry_metadata
 struct minitar_entry
 {
     struct minitar_entry_metadata metadata;
-    char* ptr;
+    fpos_t position;
 };
 
 #ifdef __cplusplus
@@ -51,6 +51,7 @@ extern "C"
     struct minitar_entry* minitar_find_by_name(struct minitar* mp, const char* name);
     struct minitar_entry* minitar_find_any_of(struct minitar* mp, enum minitar_file_type type);
     int minitar_close(struct minitar* mp);
+    size_t minitar_read_contents(struct minitar* mp, struct minitar_entry* entry, char* buf, size_t max);
 
 #ifdef __cplusplus
 }

src/tar.c

@@ -10,6 +10,7 @@ int minitar_validate_header(const struct tar_header*);
 void minitar_parse_tar_header(const struct tar_header*, struct minitar_entry_metadata*);
 struct minitar_entry* minitar_dup_entry(const struct minitar_entry*);
 char* minitar_read_file_contents(struct minitar_entry_metadata*, struct minitar*);
+size_t minitar_get_size_in_blocks(size_t);
 
 struct minitar* minitar_open(const char* pathname)
 {
@@ -47,11 +48,19 @@ static struct minitar_entry* minitar_attempt_read_entry(struct minitar* mp, int*
         *valid = 0;
         return NULL;
     }
+    *valid = 0;
+    if (fgetpos(mp->stream, &entry.position)) return NULL;
     *valid = 1;
     minitar_parse_tar_header(&hdr, &entry.metadata);
-    char* buf = minitar_read_file_contents(&entry.metadata, mp);
+    if (entry.metadata.size)
-    if (!buf) return NULL;
+    {
-    entry.ptr = buf;
+        size_t size_in_blocks = minitar_get_size_in_blocks(entry.metadata.size);
+        if (fseek(mp->stream, size_in_blocks,
+                  SEEK_CUR)) // move over to the next block, skipping over the file contents
+        {
+            return NULL;
+        }
+    }
     return minitar_dup_entry(&entry);
 }
 
@@ -72,7 +81,6 @@ void minitar_rewind(struct minitar* mp)
 
 void minitar_free_entry(struct minitar_entry* entry)
 {
-    free(entry->ptr);
     free(entry);
 }
 
@@ -102,4 +110,16 @@ struct minitar_entry* minitar_find_any_of(struct minitar* mp, enum minitar_file_
         }
     } while (entry);
     return NULL;
+}
+
+size_t minitar_read_contents(struct minitar* mp, struct minitar_entry* entry, char* buf, size_t max)
+{
+    if (!max) return 0;
+    fpos_t current_position;
+    if (fgetpos(mp->stream, &current_position)) return 0;
+    if (fsetpos(mp->stream, &entry->position)) return 0;
+    size_t nread = fread(buf, 1, max > entry->metadata.size ? entry->metadata.size : max, mp->stream);
+    if (ferror(mp->stream)) return 0;
+    if (fsetpos(mp->stream, &current_position)) return 0;
+    return nread;
 }

src/util.c

@@ -39,6 +39,21 @@ void minitar_append_char(char* str, char c)
     str[len + 1] = 0;
 }
 
+size_t minitar_is_block_aligned(size_t size)
+{
+    return (size % 512 == 0);
+}
+
+size_t minitar_align_down_to_block(size_t size)
+{
+    return size - (size % 512);
+}
+
+size_t minitar_get_size_in_blocks(size_t size)
+{
+    return minitar_is_block_aligned(size) ? size : minitar_align_down_to_block(size) + 512;
+}
+
 void minitar_parse_tar_header(const struct tar_header* hdr, struct minitar_entry_metadata* metadata)
 {
     if (!strlen(hdr->prefix))
@@ -110,34 +125,4 @@ struct minitar_entry* minitar_dup_entry(const struct minitar_entry* original)
     if (!new) return NULL;
     memcpy(new, original, sizeof *new);
     return new;
-}
-
-char* minitar_read_file_contents(struct minitar_entry_metadata* metadata, struct minitar* mp)
-{
-    char* buf = malloc(metadata->size + 1);
-    if (!buf) return NULL;
-
-    size_t nread = fread(buf, 1, metadata->size, mp->stream);
-    if (!nread)
-    {
-        if (feof(mp->stream))
-        {
-            free(buf);
-            return NULL;
-        }
-        if (ferror(mp->stream))
-        {
-            free(buf);
-            minitar_panic("Error while reading file data from tar archive");
-        }
-    }
-    else
-    {
-        long rem = 512 - (nread % 512);
-        fseek(mp->stream, rem, SEEK_CUR); // move the file offset over to the start of the next block
-    }
-
-    buf[nread] = 0;
-
-    return buf;
 }