From 333c11eb6772cc3a020ae1ab354512519a3771b9 Mon Sep 17 00:00:00 2001 From: Andre Noll 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.30.2