From 333c11eb6772cc3a020ae1ab354512519a3771b9 Mon Sep 17 00:00:00 2001
From: Andre Noll <maan@systemlinux.org>
Date: Sat, 22 Mar 2008 15:06:12 +0100
Subject: [PATCH] Add more source code documentation.
---
dss.c | 27 ++++++++++++++++++++-------
snap.h | 35 ++++++++++++++++++++++++++++-------
2 files changed, 48 insertions(+), 14 deletions(-)
diff --git a/dss.c b/dss.c
index 9dc717d..cee0f07 100644
--- a/dss.c
+++ b/dss.c
@@ -29,11 +29,12 @@
#include "time.h"
#include "snap.h"
-
+/** Command line and config file options. */
static struct gengetopt_args_info conf;
+/** Non-NULL if we log to a file. */
static FILE *logfile;
+/** The read end of the signal pipe */
static int signal_pipe;
-
/** Process id of current rsync process. */
static pid_t rsync_pid;
/** Whether the rsync process is currently stopped */
@@ -46,11 +47,11 @@ static struct timeval next_snapshot_time;
static pid_t pre_create_hook_pid;
/** The pid of the post-create hook. */
static pid_t post_create_hook_pid;
-/* Creation time of the snapshot currently being created. */
+/** Creation time of the snapshot currently being created. */
static int64_t current_snapshot_creation_time;
-
+/** Needed by the post-create hook. */
static char *path_to_last_complete_snapshot;
-
+/** \sa \ref snap.h for details. */
static unsigned snapshot_creation_status;
@@ -76,6 +77,14 @@ static int call_command_handler(void)
#undef COMMAND
#undef COMMANDS
+/**
+ * The log function of dss.
+ *
+ * \param ll Loglevel.
+ * \param fml Usual format string.
+ *
+ * All DSS_XXX_LOG() macros use this function.
+ */
__printf_2_3 void dss_log(int ll, const char* fmt,...)
{
va_list argp;
@@ -543,7 +552,6 @@ static int handle_sigchld(void)
exit(EXIT_FAILURE);
}
-
static int check_config(void)
{
if (conf.unit_interval_arg <= 0) {
@@ -931,7 +939,12 @@ err:
exit(EXIT_FAILURE);
}
-
+/**
+ * The main function of dss.
+ *
+ * \param argc Usual argument count.
+ * \param argv Usual argument vector.
+ */
int main(int argc, char **argv)
{
int ret;
diff --git a/snap.h b/snap.h
index 1e9fc2b..90a2e3a 100644
--- a/snap.h
+++ b/snap.h
@@ -1,3 +1,5 @@
+
+/** The state of snapshot creation. */
enum {
/** We are ready to take the next snapshot. */
SCS_READY,
@@ -9,15 +11,20 @@ enum {
SCS_RSYNC_RUNNING,
/** The rsync process exited successfully. */
SCS_RSYNC_SUCCESS,
- /** The post-create hook has been started- */
+ /** The post-create hook has been started. */
SCS_POST_HOOK_RUNNING,
};
-/*
- * complete, not being deleted: 1204565370-1204565371.Sun_Mar_02_2008_14_33-Sun_Mar_02_2008_14_43
- * complete, being deleted: 1204565370-1204565371.being_deleted
- * incomplete, not being deleted: 1204565370-incomplete
- * incomplete, being deleted: 1204565370-incomplete.being_deleted
+/**
+ * The status of a snapshot.
+ *
+ * The snapshot directories come in four different flavours, depending
+ * on how the two staus flags are set. Examples:
+ *
+ * Complete, not being deleted: 1204565370-1204565371.Sun_Mar_02_2008_14_33-Sun_Mar_02_2008_14_43.
+ * Complete, being deleted: 1204565370-1204565371.being_deleted.
+ * Incomplete, not being deleted: 1204565370-incomplete.
+ * incomplete, being deleted: 1204565370-incomplete.being_deleted.
*/
enum snapshot_status_flags {
/** The rsync process terminated successfully. */
@@ -26,11 +33,20 @@ enum snapshot_status_flags {
SS_BEING_DELETED = 2,
};
+/** Desribes one snapshot */
struct snapshot {
+ /** The name of the directory, relative to the destination dir. */
char *name;
+ /** Seconds after the epoch when this snapshot was created. */
int64_t creation_time;
+ /**
+ * Seconds after the epoch when creation of this snapshot completed.
+ * Only meaningful if the SS_COMPLTE bit is set.
+ */
int64_t completion_time;
+ /** See \ref snapshot_status_flags. */
enum snapshot_status_flags flags;
+ /** The interval this snapshot belongs to. */
unsigned interval;
};
@@ -48,9 +64,11 @@ struct snapshot_list {
unsigned *interval_count;
};
+/** Iterate over all snapshots in a snapshot list. */
#define FOR_EACH_SNAPSHOT(s, i, sl) \
for ((i) = 0; (i) < (sl)->num_snapshots && ((s) = (sl)->snapshots[(i)]); (i)++)
+/** Iterate backwards over all snapshots in a snapshot list. */
#define FOR_EACH_SNAPSHOT_REVERSE(s, i, sl) \
for ((i) = (sl)->num_snapshots; (i) > 0 && ((s) = (sl)->snapshots[(i - 1)]); (i)--)
@@ -64,7 +82,10 @@ __malloc char *being_deleted_name(struct snapshot *s);
int complete_name(int64_t start, int64_t end, char **result);
__malloc char *name_of_newest_complete_snapshot(struct snapshot_list *sl);
-static inline struct snapshot *get_oldest_snapshot(struct snapshot_list *sl)
+/**
+ * Get the oldest snapshot in a snapshot list.
+ */
+_static_inline_ struct snapshot *get_oldest_snapshot(struct snapshot_list *sl)
{
if (!sl->num_snapshots)
return NULL;
--
2.39.5