functions for shifting a cluster reference to its target

docs/fat_functions.3

@@ -1278,6 +1278,20 @@ int " index ", int32_t " previous )
 Print a representation of the cluster reference to stdout.
 .
 .P
+A cluster reference can be advanced in the chain of clusters of one step or
+until the end of the chain. The latter function is useful for appending data to
+the end of a file.
+.TP
+.BI "int32_t fatreferencenext(fat *" f ", \
+unit **" directory ", int *" index ", int32_t *" previous)
+Make the cluster reference point to its target.
+.TP
+.BI "int fatreferencelast(fat *" f ", \
+unit **" directory ", int *" index ", int32_t *" previous)
+Traverse the chain of clusters starting from the cluster reference until its
+end. Return the number of clusters in the chain.
+.
+.P
 The point of using a cluster reference rather than the cluster itself is that a
 cluster can be moved to another position without changing the content of its
 chain. While \fIfatunitmove()\fP only copies the content of a cluster to

lib/reference.c

@@ -130,6 +130,33 @@ int fatreferenceisdotfile(unit *directory, int index,
 	return directory != NULL && fatentryisdotfile(directory, index);
 }
 
+/*
+ * advance a cluster reference
+ */
+int32_t fatreferencenext(fat *f,
+		unit **directory, int *index, int32_t *previous) {
+	*previous = fatreferencegettarget(f, *directory, *index, *previous);
+	*directory = NULL;
+	*index = 0;
+	return fatreferencegettarget(f, *directory, *index, *previous);
+}
+
+/*
+ * follow a chain of clusters to its end; return lenght of chain in clusters
+ */
+int fatreferencelast(fat *f,
+		unit **directory, int *index, int32_t *previous) {
+	int32_t cl;
+	int n;
+
+	n = 0;
+	for (cl = fatreferencegettarget(f, *directory, *index, *previous);
+	     cl >= FAT_FIRST;
+	     cl = fatreferencenext(f, directory, index, previous))
+		n++;
+	return n;
+}
+
 /*
  * print a cluster reference
  */

lib/reference.h

@@ -40,6 +40,14 @@ int fatreferenceisdotfile(unit *directory, int index, int32_t previous);
 int fatreferenceisboot(unit *directory, int index, int32_t previous);
 int fatreferenceisvoid(unit *directory, int index, int32_t previous);
 
+/*
+ * advance a cluster reference
+ */
+int32_t fatreferencenext(fat *f,
+		unit **directory, int *index, int32_t *previous);
+int fatreferencelast(fat *f,
+		unit **directory, int *index, int32_t *previous);
+
 /*
  * check if a cluster reference points to the directory entry of a directory
  */