tar/multitape: add clarifying comments

Author: gperciva

tar/multitape/multitape_fsck.c

@@ -176,6 +176,7 @@ phase1(uint64_t machinenum, STORAGE_D * SD, STORAGE_R * SR,
 		if ((mdat = malloc(sizeof(struct tapemetadata))) == NULL)
 			goto err2;
 
+		/* Get the next metadata file. */
 		switch (multitape_metadata_get_byhash(SR, NULL, mdat,
 		    &flist[file * 32], 1)) {
 		case -1:

tar/multitape/multitape_metadata.c

@@ -506,9 +506,12 @@ multitape_metadata_delete(STORAGE_D * S, CHUNKS_D * C,
 {
 	uint8_t hbuf[32];
 
+	/* Compute the hash of the tape name. */
 	if (crypto_hash_data(CRYPTO_KEY_HMAC_NAME,
 	    (uint8_t *)mdat->name, strlen(mdat->name), hbuf))
 		goto err0;
+
+	/* Delete the file and update the stats. */
 	if (storage_delete_file(S, 'm', hbuf))
 		goto err0;
 	chunks_delete_extrastats(C, mdat->metadatalen);

tar/multitape/multitape_metaindex.c

@@ -38,7 +38,10 @@ multitape_metaindex_fragname(const uint8_t namehash[32], uint32_t fragnum,
 {
 	uint8_t fragnum_le[4];
 
+	/* Use a platform-agnostic format for fragnum. */
 	le32enc(fragnum_le, fragnum);
+
+	/* SHA256(namehash || fragnum). */
 	if (crypto_hash_data_2(CRYPTO_KEY_HMAC_SHA256, namehash, 32,
 	    fragnum_le, 4, fraghash)) {
 		warn0("Programmer error: "
@@ -90,19 +93,21 @@ multitape_metaindex_put(STORAGE_W * S, CHUNKS_W * C,
 	if ((p = buf = malloc(buflen)) == NULL)
 		goto err0;
 
-	/* Copy values into buffer. */
+	/* Copy the header index into the buffer. */
 	le32enc(p, (uint32_t)mind->hindexlen);
 	p += 4;
 	if (mind->hindexlen > 0)
 		memcpy(p, mind->hindex, mind->hindexlen);
 	p += mind->hindexlen;
 
+	/* Copy the chunk index into the buffer. */
 	le32enc(p, (uint32_t)mind->cindexlen);
 	p += 4;
 	if (mind->cindexlen > 0)
 		memcpy(p, mind->cindex, mind->cindexlen);
 	p += mind->cindexlen;
 
+	/* Copy the trailer index into the buffer. */
 	le32enc(p, (uint32_t)mind->tindexlen);
 	p += 4;
 	if (mind->tindexlen > 0)
@@ -231,8 +236,11 @@ multitape_metaindex_get(STORAGE_R * S, CHUNKS_S * C,
 	buf += 4;
 	buflen -= 4;
 
+	/* Sanity check. */
 	if (buflen < mind->hindexlen)
 		goto corrupt0;
+
+	/* Copy the header index into a new buffer. */
 	if (((mind->hindex = malloc(mind->hindexlen)) == NULL) &&
 	    (mind->hindexlen > 0))
 		goto err1;
@@ -248,8 +256,11 @@ multitape_metaindex_get(STORAGE_R * S, CHUNKS_S * C,
 	buf += 4;
 	buflen -= 4;
 
+	/* Sanity check. */
 	if (buflen < mind->cindexlen)
 		goto corrupt1;
+
+	/* Copy the chunk index into a new buffer. */
 	if (((mind->cindex = malloc(mind->cindexlen)) == NULL) &&
 	    (mind->cindexlen > 0))
 		goto err2;
@@ -265,8 +276,11 @@ multitape_metaindex_get(STORAGE_R * S, CHUNKS_S * C,
 	buf += 4;
 	buflen -= 4;
 
+	/* Sanity check. */
 	if (buflen < mind->tindexlen)
 		goto corrupt2;
+
+	/* Copy the trailer index into a new buffer. */
 	if (((mind->tindex = malloc(mind->tindexlen)) == NULL) &&
 	    (mind->tindexlen > 0))
 		goto err3;
@@ -275,6 +289,7 @@ multitape_metaindex_get(STORAGE_R * S, CHUNKS_S * C,
 	buf += mind->tindexlen;
 	buflen -= mind->tindexlen;
 
+	/* Sanity check. */
 	if (buflen != 0)
 		goto corrupt3;
 
@@ -331,6 +346,7 @@ multitape_metaindex_free(struct tapemetaindex * mind)
 	if (mind == NULL)
 		return;
 
+	/* Clean up. */
 	free(mind->tindex);
 	free(mind->cindex);
 	free(mind->hindex);
@@ -351,6 +367,7 @@ multitape_metaindex_delete(STORAGE_D * S, CHUNKS_D * C,
 	size_t fraglen;
 	uint8_t fraghash[32];
 
+	/* Compute the hash of the tape name. */
 	if (crypto_hash_data(CRYPTO_KEY_HMAC_NAME,
 	    (uint8_t *)mdat->name, strlen(mdat->name), hbuf))
 		goto err0;

tar/multitape/multitape_read.c

@@ -127,10 +127,12 @@ stream_get_chunk(struct stream * S, const uint8_t ** buf, size_t * clen,
 
 	/* Skip part of the current chunk if appropriate. */
 	if (S->skiplen) {
+		/* How many bytes should we skip? */
 		skip = (off_t)(S->chunklen - S->chunkpos);
 		if (skip > S->skiplen)
 			skip = S->skiplen;
 
+		/* Skip bytes. */
 		S->skiplen -= skip;
 		S->chunkpos += (size_t)skip;
 	}
@@ -377,11 +379,13 @@ readtape_read(TAPE_R * d, const void ** buffer)
 			continue;
 		}
 
+		/* Read data. */
 		if (stream_get_chunk(readstream, buf, &clen, d->C))
 			goto err0;
 		if ((off_t)clen > *readmaxlen)
 			clen = (size_t)(*readmaxlen);
 
+		/* Update position and length. */
 		readstream->chunkpos += clen;
 		*readmaxlen -= clen;
 

tar/multitape/multitape_stats.c

@@ -401,6 +401,7 @@ statstape_print(TAPE_S * d, const char * tapename, const char * csv_filename,
 		goto err0;
 	}
 
+	/* Compute statistics. */
 	if (multitape_chunkiter_tmd(d->SR, d->C, &tmd,
 	    callback_print, d->C, 0))
 		goto err2;

tar/multitape/multitape_write.c

@@ -1054,6 +1054,7 @@ writetape_free(TAPE_W * d)
 	if (d == NULL)
 		return;
 
+	/* Clean up. */
 	chunks_write_free(d->C);
 	storage_write_free(d->S);
 	if ((d->lockfd != -1) && close(d->lockfd))