Add os9 reveal to identify what lives at a given disk location

build/unix/os9/Makefile

@@ -8,7 +8,7 @@ CFLAGS	+= -I../../../include -Wall -MMD -MP
 SRCS = os9copy.c os9dsave.c os9gen.c os9modbust.c os9dcheck.c os9dump.c \
 	os9id.c os9padrom.c os9_main.c os9del.c os9format.c os9ident.c \
 	os9rename.c os9attr.c os9deldir.c os9free.c os9list.c os9cmp.c \
-	os9dir.c os9fstat.c os9makdir.c
+	os9dir.c os9fstat.c os9makdir.c os9reveal.c
 OBJS = $(SRCS:.c=.o)
 DEPS = $(OBJS:.o=.d)
 

doc/ToolShed.md

@@ -36,6 +36,7 @@ ToolShed v2.5.1
   * [MODBUST](#modbust) - Bust a single merged file of OS-9 modules into separate files
   * [PADROM](#padrom) - Pad a file to a specific length
   * [RENAME](#rename_os9) - Give a file a new filename
+  * [REVEAL](#reveal_os9) - Explain what lives at a given LSN of a disk image
 * [decb](#decb) - Manipulate RSDOS formatted disk images
   * [Options](#decb_exec_option) - The DECB executive's option
   * [ATTR](#attr_decb) - Display or modify file attributes
@@ -828,6 +829,35 @@ The rename command renames a file with a new filename.
 
 ---
 
+<h3 id="reveal_os9">REVEAL - Explain what lives at a given LSN of a disk image</h3>
+
+#### Syntax and Scope
+
+    reveal {[<opts>]} <disk> <lsn>[:<offset>]
+    reveal -b <disk> <byte-offset>
+
+This command is intended for RBF disk image files only.
+
+#### Description
+
+Reveal takes an LSN (and, optionally, a byte offset within that sector) or an absolute byte offset into the image, and explains, in plain English, exactly what lives at that location: a field of LSN0, a bitmap byte and the cluster/LSN range it tracks, a file descriptor and which field of it, a segment entry, a directory entry (and which byte of its name or LSN pointer), or a byte inside a file's data. If the LSN doesn't map to anything reveal recognizes, it reports whether the bitmap marks it allocated or free, and whether it falls within the boot track.
+
+Options:
+
+    -b    Treat <offset> as an absolute byte offset from the start
+          of the disk image, rather than an LSN[:offset] pair.
+    -d    Dragon disk (used to find the location of a boot track)
+
+#### Example
+
+    os9 reveal 68SDC.VHD -b 88179138
+
+    Examining LSN 344,449, byte 194 of '68SDC.VHD'...
+
+    This is byte 164,290 of file "/SOURCECODE/ASM/NITROS9/CMDS/grfdrv_older_source.lzh" (the 164,291st byte overall), found in the 2nd segment/extent of this file, which begins at LSN 344,064.
+
+---
+
 <h2 id="decb">decb</h2>
 
 The following pages document the commands built into the decb tool. Its interface is similar to that of the os9 tool discussed in previous pages.

include/rbfutil.h

@@ -46,7 +46,14 @@ int os9padrom(int, char **);
 int os9rename(int, char **);
 
 int StrToInt(char *s);
-void show_help(char **helpMessage);
+void show_help(char const * const *helpMessage);
+
+struct personality
+{
+	int startlsn;
+};
+
+error_code get_boottrack_lsn(lsn0_sect LSN0, struct personality *hwtype, int *startlsn, int verbose);
 
 #ifdef __cplusplus
 }

include/util.h

@@ -42,6 +42,7 @@ int os9makdir(int, char **);
 int os9modbust(int, char **);
 int os9padrom(int, char **);
 int os9rename(int, char **);
+int os9reveal(int, char **);
 int os9rdump(int, char **);
 
 int StrToInt(char *s);

os9/os9_main.c

@@ -56,6 +56,7 @@ static struct cmdtbl table[] = {
 	{os9modbust, "modbust"},
 	{os9padrom, "padrom"},
 	{os9rename, "rename"},
+	{os9reveal, "reveal"},
 	{NULL, NULL}
 };
 

os9/os9gen.c

@@ -12,18 +12,12 @@
 #include <cocotypes.h>
 #include <cocopath.h>
 #include <toolshed.h>
-
-struct personality
-{
-	int startlsn;
-};
+#include <rbfutil.h>
 
 static int do_os9gen(char **argv, char *device, char *bootfile,
 		     char *trackfile, struct personality *hwtype,
 		     int extended);
 
-error_code get_boottrack_lsn(lsn0_sect LSN0, struct personality *hwtype, int *startlsn);
-
 static struct personality coco = { 18 * 34 };
 static struct personality dragon = { 2 };
 
@@ -193,7 +187,7 @@ static int do_os9gen(char **argv, char *device, char *bootfile,
                 return (1);
             }
 
-			ec = get_boottrack_lsn(*cpath->path.os9->lsn0, hwtype, &startlsn);
+			ec = get_boottrack_lsn(*cpath->path.os9->lsn0, hwtype, &startlsn, 1);
 			if (ec != 0)
 			{
 				_coco_close(cpath);
@@ -269,7 +263,7 @@ static int do_os9gen(char **argv, char *device, char *bootfile,
 			return (1);
 		}
 
-		ec = get_boottrack_lsn(*opath->path.os9->lsn0, hwtype, &startlsn);
+		ec = get_boottrack_lsn(*opath->path.os9->lsn0, hwtype, &startlsn, 1);
 		if (ec != 0)
 		{
 			_coco_close(opath);
@@ -433,7 +427,19 @@ static int do_os9gen(char **argv, char *device, char *bootfile,
     return (0);
 }
 
-error_code get_boottrack_lsn(lsn0_sect LSN0, struct personality *hwtype, int *startlsn)
+#define QPRINTF(enabled, ...) \
+    do { \
+        if (enabled) \
+            printf(__VA_ARGS__); \
+    } while (0)
+
+#define QFPRINTF(enabled, ...) \
+    do { \
+        if (enabled) \
+            fprintf(stderr, __VA_ARGS__); \
+    } while (0)
+
+error_code get_boottrack_lsn(lsn0_sect LSN0, struct personality *hwtype, int *startlsn, int verbose)
 {
 	int is_osk;
 	u_char *pd_sct, *pd_cyl, *pd_sid, *pd_typ;
@@ -459,20 +465,20 @@ error_code get_boottrack_lsn(lsn0_sect LSN0, struct personality *hwtype, int *st
 
 	if (*startlsn == 2)
 	{
-		printf("Dragon boottrack selected: ");
+		QPRINTF(verbose, "Dragon boottrack selected: ");
 		/* Check to make sure the disk image has minimum of 18 sectors per track */
 		if (int2(pd_sct) < 18)
 		{
-			printf("\n");
-			fprintf(stderr,
+			QPRINTF(verbose, "\n");
+			QFPRINTF(verbose,
 				"Error: minimum sectors per track of 18 required for DragonDOS, found %d\n",
 				int2(pd_sct));
 			return (1);
 		}
 	}
 	else
 	{
-		printf("CoCo boottrack selected: ");
+		QPRINTF(verbose, "CoCo boottrack selected: ");
 		/* If special startLSN for boottrack is set then set startlsn to  */
 		/* the value stored in specialStartLSN  */
 		if (specialStartLSN > 0)
@@ -492,7 +498,7 @@ error_code get_boottrack_lsn(lsn0_sect LSN0, struct personality *hwtype, int *st
 				/* Check to make sure the disk image has minimum of 18 sectors per track */
 				if (int2(pd_sct) < 18)
 				{
-					printf("\n");
+					QPRINTF(verbose, "\n");
 					fprintf(stderr,
 						"Error: minimum sectors per track of 18 required for Disk Basic, found %d\n",
 						int2(pd_sct));
@@ -501,7 +507,7 @@ error_code get_boottrack_lsn(lsn0_sect LSN0, struct personality *hwtype, int *st
 				/* Check to make sure the disk image has minimum of 35 tracks */
 				if (int2(pd_cyl) < 35)
 				{
-					printf("\n");
+					QPRINTF(verbose, "\n");
 					fprintf(stderr,
 						"Error: minimum number of tracks required for Disk Basic is 35, found %d\n",
 						int2(pd_cyl));