From 6c50ab6e61f952714cfee5de76e471036cb924d7 Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Mon, 10 Nov 2008 20:40:01 +0000 Subject: Document a couple of functions. svn:r17239 --- src/common/compat.c | 13 ++++++++++++- src/or/main.c | 6 +++++- 2 files changed, 17 insertions(+), 2 deletions(-) diff --git a/src/common/compat.c b/src/common/compat.c index 11455356ed..b3d4361969 100644 --- a/src/common/compat.c +++ b/src/common/compat.c @@ -476,12 +476,22 @@ touch_file(const char *fname) return 0; } +/** Represents a lockfile on which we hold the lock. */ struct tor_lockfile_t { char *filename; int fd; }; -/** DOCDOC. What's this function do? */ +/** Try to get a lock on the lockfile filename, creating it as + * necessary. If someone else has the lock and blocking is true, + * wait until the lock is available. Otherwise return immediately whether + * we succeeded or not. + * + * Set *locked_out to true if somebody else had the lock, and to false + * otherwise. + * + * Return a tor_lockfile_t on success, NULL on failure. + */ tor_lockfile_t * tor_lockfile_lock(const char *filename, int blocking, int *locked_out) { @@ -523,6 +533,7 @@ tor_lockfile_lock(const char *filename, int blocking, int *locked_out) return result; } +/** Release the lock held as lockfile. */ void tor_lockfile_unlock(tor_lockfile_t *lockfile) { diff --git a/src/or/main.c b/src/or/main.c index c65a5a3a5e..2d3cc72c6d 100644 --- a/src/or/main.c +++ b/src/or/main.c @@ -1861,7 +1861,11 @@ tor_init(int argc, char *argv[]) static tor_lockfile_t *lockfile = NULL; -/** DOCDOC. What's this function do? */ +/** Try to grab the lock file described in options, if we do not + * already have it. If err_if_locked is true, warn if somebody else is + * holding the lock, and exit if we can't get it after waiting. Otherwise, + * return -1 if we can't get the lockfile. Return 0 on success. + */ int try_locking(or_options_t *options, int err_if_locked) { -- cgit v1.2.3-54-g00ecf