From 5f4f2ed0b58332796f621be55f6110b497c11050 Mon Sep 17 00:00:00 2001
From: Patrick McDermott <patrick.mcdermott@libiquity.com>
Date: Tue, 18 Apr 2023 11:00:54 -0400
Subject: main, ustar: Add comments

---
(limited to 'src/ustar.c')

diff --git a/src/ustar.c b/src/ustar.c
index 43292e9..cf1134a 100644
--- a/src/ustar.c
+++ b/src/ustar.c
@@ -81,22 +81,28 @@ _opkg_opk_ustar_next(struct opkg_opk_ustar *ustar,
 	       size_t    i;
 	       char     *header_uc;
 
+	/* Decompress next (hopefully valid header) record. */
 	switch (opkg_opk_gzip_read(ustar->gzip, header)) {
 		case OPKG_OPK_OK:
 			break;
 		case OPKG_OPK_END:
+			/* End of gzip stream before end of ustar archive */
 		case OPKG_OPK_ERROR:
 			return OPKG_OPK_ERROR;
 	}
+
+	/* Check for end of archive. */
 	memset(record, 0, OPKG_OPK_USTAR_RECORD_SIZE);
 	if (memcmp(header, record, OPKG_OPK_USTAR_RECORD_SIZE) == 0) {
 		return OPKG_OPK_END;
 	}
 
+	/* Verify magic. */
 	if (memcmp(header->magic, "ustar", strlen("ustar")) != 0) {
 		return OPKG_OPK_ERROR;
 	}
 
+	/* Verify checksum. */
 	chksum_got = strtol(header->chksum, &end,
 			OPKG_OPK_USTAR_NUM_BASE_);
 	chksum_exp = 0;
@@ -114,6 +120,7 @@ _opkg_opk_ustar_next(struct opkg_opk_ustar *ustar,
 		return OPKG_OPK_ERROR;
 	}
 
+	/* Depending on type, get size. */
 	switch (*header->typeflag) {
 		case '0':  /* Regular file */
 		case '7':  /* High-performance or regular file */
@@ -147,15 +154,18 @@ opkg_opk_ustar_list(struct opkg_opk_ustar *ustar,
 	       int                            ret;
 	       char                          *end;
 
+	/* Get next header record, if any. */
 	if ((ret =_opkg_opk_ustar_next(ustar, &header)) != OPKG_OPK_OK) {
 		return ret;  /* Error or end of archive */
 	}
 
+	/* Allocate outward-facing member information structure. */
 	*member = malloc(sizeof(**member));
 	if (*member == NULL) {
 		return OPKG_OPK_ERROR;
 	}
 
+	/* Set name, mode, size, mtime, type, linkname, uname, and gname. */
 	if (header.prefix[0] != '\0') {
 		sprintf((*member)->name, "%s/%s", header.prefix, header.name);
 	} else {
@@ -205,6 +215,7 @@ opkg_opk_ustar_list(struct opkg_opk_ustar *ustar,
 	strncpy((*member)->uname, header.uname, sizeof((*member)->uname));
 	strncpy((*member)->gname, header.gname, sizeof((*member)->gname));
 
+	/* Seek through data records until next header record. */
 	while (ustar->data_size_remaining > 0) {
 		if (opkg_opk_ustar_read(ustar, NULL, NULL) == OPKG_OPK_ERROR) {
 			free(*member);
@@ -225,10 +236,12 @@ opkg_opk_ustar_seek(struct opkg_opk_ustar *ustar, int num_keys, ...)
 	       const char                    *member;
 
 	for (;;) {
+		/* Get next header record. */
 		if (_opkg_opk_ustar_next(ustar, &header) != OPKG_OPK_OK) {
 			return OPKG_OPK_ERROR;  /* Error or end (not found) */
 		}
 
+		/* Prepare name (with prefix if any) for check. */
 		if (header.prefix[0] != '\0') {
 			sprintf(name, "%s/%s", header.prefix,
 					header.name);
@@ -237,6 +250,7 @@ opkg_opk_ustar_seek(struct opkg_opk_ustar *ustar, int num_keys, ...)
 			name[sizeof(header.name)] = '\0';
 		}
 
+		/* Check each requested name. */
 		va_start(ap, num_keys);
 		for (key = 0; key < num_keys; ++key) {
 			member = va_arg(ap, const char *);
@@ -246,6 +260,7 @@ opkg_opk_ustar_seek(struct opkg_opk_ustar *ustar, int num_keys, ...)
 		}
 		va_end(ap);
 
+		/* Seek through data records until next header record. */
 		while (ustar->data_size_remaining > 0) {
 			if (opkg_opk_ustar_read(ustar, NULL, NULL) ==
 					OPKG_OPK_ERROR) {
@@ -264,6 +279,7 @@ opkg_opk_ustar_read(struct opkg_opk_ustar *ustar, char **buffer, size_t *size)
 		return OPKG_OPK_END;
 	}
 
+	/* Decompress next data record. */
 	switch (opkg_opk_gzip_read(ustar->gzip, ustar->read_record)) {
 		case OPKG_OPK_OK:
 			break;
@@ -272,6 +288,8 @@ opkg_opk_ustar_read(struct opkg_opk_ustar *ustar, char **buffer, size_t *size)
 			return OPKG_OPK_ERROR;
 	}
 
+	/* Store buffer and size in caller's memory and update remaining size.
+	 */
 	if (buffer != NULL) {
 		*buffer = ustar->read_record;
 	}
--
cgit v0.9.1