Document the API in the README

This structure should be opaque for everyone using the library, and every public API just uses a pointer to it.

.clang-format

@@ -0,0 +1,12 @@
+---
+BasedOnStyle: Microsoft
+CompactNamespaces: 'false'
+FixNamespaceComments: 'false'
+NamespaceIndentation: All
+AllowShortBlocksOnASingleLine: 'true'
+AllowShortCaseLabelsOnASingleLine: 'true'
+AllowShortFunctionsOnASingleLine: None
+AllowShortIfStatementsOnASingleLine: Always
+AllowShortLambdasOnASingleLine: All
+AllowShortLoopsOnASingleLine: 'true'
+PointerAlignment: Left

Makefile

@@ -6,7 +6,7 @@ SRC := src
 CC ?= gcc
 AR ?= ar
 CFLAGS ?= -O2 -Wall -Wextra
-CFLAGS := ${CFLAGS} -I.
+CFLAGS := ${CFLAGS} -I. -D_IN_MINITAR
 DESTDIR ?= /usr/local
 
 OBJS := $(OBJ)/tar.o \

README.md

@@ -34,3 +34,34 @@ int main(int argc, char** argv)
 ```
 
 This program will list out the files in a tar archive :)
+
+## API
+### minitar_open
+`struct minitar* minitar_open(const char* filename)`
+
+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.
+
+### minitar_read_entry
+`struct minitar_entry* minitar_read_entry(struct minitar* mp)`
+
+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).
+
+### 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_close
+`int minitar_close(struct minitar* mp)`
+
+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()`.
+
+Returns 0 on success, everything else is failure and you should check `errno`.

minitar.h

@@ -3,10 +3,14 @@
 #include <stdio.h>
 #include <sys/types.h>
 
+#ifdef _IN_MINITAR
 struct minitar
 {
     FILE* stream;
 };
+#else
+struct minitar;
+#endif
 
 enum minitar_file_type
 {

src/tar.c

@@ -1,6 +1,6 @@
-#include <stdlib.h>
-#include "minitar.h"
 #include "tar.h"
+#include "minitar.h"
+#include <stdlib.h>
 
 int minitar_read_header(struct minitar* mp, struct tar_header* hdr);
 int minitar_validate_header(struct tar_header* hdr);
@@ -13,7 +13,11 @@ struct minitar* minitar_open(const char* path)
     FILE* fp = fopen(path, "rb"); // On some systems, this might be necessary to read the file properly.
     if (!fp) return NULL;
     struct minitar* mp = malloc(sizeof(struct minitar));
-    if(!mp) { fclose(fp); return NULL; }
+    if (!mp)
+    {
+        fclose(fp);
+        return NULL;
+    }
     mp->stream = fp;
     return mp;
 }

src/tar.h

@@ -1,7 +1,8 @@
 #ifndef MINITAR_TAR_H
 #define MINITAR_TAR_H
 
-struct tar_header {
+struct tar_header
+{
     char name[100];
     char mode[8];
     char uid[8];

src/util.c

@@ -1,11 +1,11 @@
 #define _POSIX_C_SOURCE 200809L
+#include "minitar.h"
+#include "tar.h"
+#include <stdarg.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <stdnoreturn.h>
-#include <stdarg.h>
 #include <string.h>
-#include "minitar.h"
-#include "tar.h"
 
 noreturn void minitar_panic(const char* message)
 {
@@ -19,7 +19,9 @@ void minitar_parse_tar_header(struct tar_header* hdr, struct minitar_entry_metad
     {
         strncpy(metadata->name, hdr->name, 100);
         metadata->name[100] = '\0';
-    } else {
+    }
+    else
+    {
         strcpy(metadata->name, hdr->prefix);
         strcat(metadata->name, "/");
         strncat(metadata->name, hdr->name, 100);
@@ -43,26 +45,14 @@ void minitar_parse_tar_header(struct tar_header* hdr, struct minitar_entry_metad
     switch (hdr->typeflag)
     {
     case '\0':
-        case '0':
+    case '0': metadata->type = MTAR_REGULAR; break;
-            metadata->type = MTAR_REGULAR;
+    case '1': minitar_panic("Links to other files within a tar archive are unsupported");
-            break;
+    case '2': minitar_panic("Symbolic links are unsupported");
-        case '1':
+    case '3': metadata->type = MTAR_CHRDEV; break;
-            minitar_panic("Links to other files within a tar archive are unsupported");
+    case '4': metadata->type = MTAR_BLKDEV; break;
-        case '2':
+    case '5': metadata->type = MTAR_DIRECTORY; break;
-            minitar_panic("Symbolic links are unsupported");
+    case '6': minitar_panic("FIFOs are unsupported");
-        case '3':
+    default: minitar_panic("Unknown entry type in tar header");
-            metadata->type = MTAR_CHRDEV;
-            break;
-        case '4':
-            metadata->type = MTAR_BLKDEV;
-            break;
-        case '5':
-            metadata->type = MTAR_DIRECTORY;
-            break;
-        case '6':
-            minitar_panic("FIFOs are unsupported");
-        default:
-            minitar_panic("Unknown entry type in tar header");
     }
 
     strcpy(metadata->uname, hdr->uname);