dj(1): more better comments

src/dj.c

@@ -20,6 +20,7 @@
 #include <assert.h> /* assert(3) */
 #include <errno.h> /* errno */
 #include <fcntl.h> /* open(2) */
+#include <stdbool.h> /* bool */
 #include <stdio.h> /* fprintf(3), stderr */
 #include <stdlib.h> /* malloc(3), strtol(3), size_t */
 #include <string.h> /* memcpy(3), memmove(3), memset(3) */
@@ -28,8 +29,6 @@
                      * optarg, optind, STDIN_FILENO, STDOUT_FILENO */
 #include <sys/stat.h> /* S_IRGRP, S_IROTH, S_IRUSR, S_IWGRP, S_IWOTH, S_IWUSR */
 
-extern int errno;
-
 char *program_name = "dj";
 
 /* dj uses two structures that respectively correspond to the reading and
@@ -62,6 +61,7 @@ static int write_flags = O_WRONLY | O_CREAT;
 /* Macro to check if fd is stdin or stdout */
 #define fdisstd(fd) ((fd) == STDIN_FILENO || (fd) == STDOUT_FILENO)
 
+/* Completes one Io block read */
 static struct Io *
 Io_read(struct Io *io) {
 	int t;
@@ -84,6 +84,7 @@ Io_read(struct Io *io) {
 	return io;
 }
 
+/* Completes one Io block write */
 static struct Io *
 Io_write(struct Io *io) {
 	int t;
@@ -168,16 +169,16 @@ usage(char *argv0) {
 int main(int argc, char *argv[]) {
    	int align;    /* low 8b used, negative if no alignment is being done */
 	int count;    /* -1 if dj(1) runs until no more reads are possible */
-	char *fmt;    /* == fmt_asv (default) or fmt_human (-H) */
-	size_t i;     /* side of io being modified */
-	char noerror; /* 0=exits (default) 1=retries on partial reads or writes */
+	char *fmt;    /* set to fmt_asv (default) or fmt_human (-H) */
+	size_t i;     /* side of io (in or out) being modified */
+	bool retry;   /* false if exits on partial reads or writes */
 	struct Io io[2 /* { in, out } */];
 
 	/* Set defaults. */
 	align = -1;
 	count = -1;
 	fmt = fmt_asv;
-	noerror = 0;
+	retry = 0;
 	for (i = 0; i < (sizeof io) / (sizeof *io); ++i) {
 		io[i].bs = 1024 /* 1 KiB */; /* GNU dd(1) default; POSIX says 512B */
 		io[i].bufuse = 0;
@@ -218,8 +219,9 @@ int main(int argc, char *argv[]) {
 						}
 					}
 
-					return oserr(optarg, errno); /* break; */
-				case 'n': noerror = 1; break; /* retry failed reads once */
+					return oserr(optarg, errno);
+					/* UNREACHABLE */
+				case 'n': retry = 1; break; /* retry failed reads once */
 				case 'H': fmt = fmt_human; break; /* human-readable output */
 				case 'a': /* input buffer padding */
 					if (optarg[0] == '\0' || optarg[1] == '\0') {
@@ -233,12 +235,12 @@ int main(int argc, char *argv[]) {
 					if (c == 'c' && (count = parse(optarg)) >= 0) { break; }
 
 					i = (c >= 'A' && c <= 'Z');
-					c |= 0x20; /* 0b 0010 0000 (ASCII make lowercase) */
+					c |= 0x20; /* 0b 0010 0000 (ASCII) make lowercase */
 
-					if (
+					if ( /* if -b or -s is parsed out correctly */
 						(c == 'b' && (io[i].bs = parse(optarg)) > 0)
 						|| (c == 's' && (io[i].seek = parse(optarg)) >= 0)
-					) { break; }
+					) { break; } /* don't error */
 
 					/* FALLTHROUGH */
 				default:
@@ -277,7 +279,7 @@ int main(int argc, char *argv[]) {
 			(t = io[1].bufuse = MIN(io[1].bs, io[1].seek)) /* saturate block */
 		);
 
-		if (Io_write(&io[1])->bufuse == t && !noerror && io[1].error == 0) {
+		if (Io_write(&io[1])->bufuse == t && !retry && io[1].error == 0) {
 			(void)Io_write(&io[1]); /* second chance */
 		}
 
@@ -286,7 +288,7 @@ int main(int argc, char *argv[]) {
 		if (io[1].bufuse == t) { break; } /* all writes failed! */
 	}
 
-	io[1].bufuse = 0;
+	io[1].bufuse = 0; /* reset after hard seek */
 
 	if (io[1].seek > 0) { /* hard seeking failed */
 		(void)fprintio(stderr, fmt, io);
@@ -309,7 +311,7 @@ int main(int argc, char *argv[]) {
 			}
 
 			t = io[0].bufuse;
-			if (Io_read(&io[0])->bufuse == t && !noerror && io[0].error == 0) {
+			if (Io_read(&io[0])->bufuse == t && !retry && io[0].error == 0) {
 				(void)Io_read(&io[0]); /* second chance */
 			}
 
@@ -321,7 +323,7 @@ int main(int argc, char *argv[]) {
 				(void)fprintf(stderr, "%s: Partial read:\n\t", program_name);
 				(void)fprintio(stderr, fmt, io);
 
-				if (!noerror) { count = 1; }
+				if (!retry) { count = 1; }
 
 				if (align >= 0) {
 					/* fill the rest of the ibuf with padding */
@@ -380,7 +382,7 @@ int main(int argc, char *argv[]) {
 
 				t = io[1].bufuse;
 				if (Io_write(&io[1])->bufuse == t
-						&& !noerror
+						&& !retry
 						&& io[1].error == 0) {
 					(void)Io_write(&io[1]); /* second chance */
 				}
@@ -402,7 +404,7 @@ int main(int argc, char *argv[]) {
 				(void)fprintf(stderr, "%s: Partial write:\n\t", program_name);
 				(void)fprintio(stderr, fmt, io);
 
-				if(!noerror) { count = 1; }
+				if(!retry) { count = 1; }
 			}
 		}
 	}