Commit 6f7847b3 authored Oct 04, 2007 by Nick Mathewson

r15530@catbus: nickm | 2007-10-04 12:16:27 -0400

 Add a bunch of function documentation; clean up a little code; fix some XXXXs; tag the nonsensical EXTRAINFO_PURPOSE_GENERAL as nonsesnse; note another bit of "do not cache special routers" code to nuke.


svn:r11761

parent cc7e0f62

doc/TODO

+4 −3

Original line number	Diff line number	Diff line
		@@ -52,18 +52,19 @@ Things we'd like to do in 0.2.0.x:
		. 101: Voting on the Tor Directory System (plus 103)
		. Finalize proposal
		* Describe schedule in copious detail.
		- Get authorities voting
		. Get authorities voting
		o Code to manage key certificates
		o Download as needed.
		o Code to download
		. Code to retry download.
		D Code to retry download.
		o Code to generate consensus from a list of votes
		o Detect whether votes are really all for the same period.
		o Push/pull documents as appropriate.
		o Pull votes and signatures if we don't get them.
		- Cache votes and signatures on disk?
		o Cache votes and signatures on disk?
		o Code to keep consensus docs in limbo if they don't have
		have enough signatures.
		D Save votes on disk.
		o Have clients know which authorities are v3 authorities, and what
		their keys are.
		- While we're at it, let v3 authorities have fqdns lines.

src/common/aes.c

+2 −1

Original line number	Diff line number	Diff line
		@@ -311,7 +311,8 @@ aes_crypt(aes_cnt_cipher_t cipher, const char input, size_t len,
		}
		}

		/** DOCDOC */
		/** Reset the 128-bit counter of <b>cipher</b> to the 16-bit big-endian value
		* in <b>iv</b>. */
		void
		aes_set_iv(aes_cnt_cipher_t cipher, const char iv)
		{

src/common/util.c

+40 −12

Original line number	Diff line number	Diff line
		@@ -1516,16 +1516,32 @@ write_str_to_file(const char fname, const char str, int bin)
		return write_bytes_to_file(fname, str, strlen(str), bin);
		}

		/** DOCDOC */
		/** Represents a file that we're writing to, with support for atomic commit:
		* we can write into a a temporary file, and either remove the file on
		* failure, or replace the original file on success. */
		struct open_file_t {
		char *tempname;
		char *filename;
		int rename_on_close;
		int fd;
		FILE *stdio_file;
		char tempname; /< Name of the temporary file. /
		char filename; /< Name of the original file. /
		int rename_on_close; /*< Are we using the temporary file or not? /
		int fd; /*< fd for the open file. /
		FILE stdio_file; /< stdio wrapper for <b>fd</b>. /
		};

		/** DOCDOC */
		/** Try to start writing to the file in <b>fname</b>, passing the flags
		* <b>open_flags</b> to the open() syscall, creating the file (if needed) with
		* access value <b>mode</b>. If the O_APPEND flag is set, we append to the
		* original file. Otherwise, we open a new a temporary file in the same
		* directory, and either replace the original or remove the temprorary file
		* when we're done.
		*
		* Return the fd for the newly opened file, and store working data in
		* *<b>data_out</b>. The caller should not close the fd manually:
		* instead, call finish_writing_to_file() or abort_writing_to_file().
		* Returns -1 on failure.
		*
		* NOTE: When not appending, the flags O_CREAT and O_TRUNC are treated
		* as true and the flag O_EXCL is treated as false.
		*/
		int
		start_writing_to_file(const char *fname, int open_flags, int mode,
		open_file_t **data_out)
		@@ -1551,6 +1567,9 @@ start_writing_to_file(const char *fname, int open_flags, int mode,
		log(LOG_WARN, LD_GENERAL, "Failed to generate filename");
		goto err;
		}
		/* We always replace an existing temporary file if there is one. */
		open_flags \|= O_CREAT\|O_TRUNC;
		open_flags &= ~O_EXCL;
		new_file->rename_on_close = 1;
		}

		@@ -1572,7 +1591,9 @@ start_writing_to_file(const char *fname, int open_flags, int mode,
		return -1;
		}

		/** DOCDOC */
		/** Given <b>file_data</b> from start_writing_to_file(), return a stdio FILE*
		* that can be used to write to the same file. The caller should not mix
		* stdio calls with non-stdio calls. */
		FILE *
		fdopen_file(open_file_t *file_data)
		{
		@@ -1587,7 +1608,8 @@ fdopen_file(open_file_t *file_data)
		return file_data->stdio_file;
		}

		/** DOCDOC */
		/** Combines start_writing_to_file with fdopen_file(): arguments are as
		* for start_writing_to_file, but */
		FILE *
		start_writing_to_stdio_file(const char *fname, int open_flags, int mode,
		open_file_t **data_out)
		@@ -1600,7 +1622,10 @@ start_writing_to_stdio_file(const char *fname, int open_flags, int mode,
		return res;
		}

		/** DOCDOC */
		/** Helper function: close and free the underlying file and memory in
		* <b>file_data</b>. If we were writing into a temporary file, then delete
		* that file (if abort_write is true) or replaces the target file with
		* the temporary file (if abort_write is false). */
		static int
		finish_writing_to_file_impl(open_file_t *file_data, int abort_write)
		{
		@@ -1641,14 +1666,17 @@ finish_writing_to_file_impl(open_file_t *file_data, int abort_write)
		return r;
		}

		/** DOCDOC */
		/** Finish writing to <b>file_data</b>: close the file handle, free memory as
		* needed, and if using a temporary file, replace the original file with
		* the temporary file. */
		int
		finish_writing_to_file(open_file_t *file_data)
		{
		return finish_writing_to_file_impl(file_data, 0);
		}

		/** DOCDOC */
		/** Finish writing to <b>file_data</b>: close the file handle, free memory as
		* needed, and if using a temporary file, delete it. */
		int
		abort_writing_to_file(open_file_t *file_data)
		{

src/or/circuitbuild.c

+4 −2

Original line number	Diff line number	Diff line
		@@ -2103,7 +2103,9 @@ entry_guard_free(entry_guard_t *e)
		tor_free(e);
		}

		/** DOCDOC */
		/** Remove any entry guard which was selected by an unknown version of Tor,
		* or which was selected by a version of Tor that's known to select
		* entry guards badly. */
		static int
		remove_obsolete_entry_guards(void)
		{
		@@ -2512,7 +2514,7 @@ choose_random_entry(cpath_build_state_t *state)
		return r;
		}

		/** DOCDOC */
		/** Helper: Return the start of the month containing <b>time</b>. */
		static time_t
		start_of_month(time_t now)
		{

src/or/control.c

+14 −4

Original line number	Diff line number	Diff line
		@@ -1249,7 +1249,15 @@ getinfo_helper_misc(control_connection_t conn, const char question,
		return 0;
		}

		/** DOCDOC */
		/** Awful hack: return a newly allocated string based on a routerinfo and
		* (possibly) an extrainfo, sticking the read-history and write-history from
		* <b>ei</b> into the resulting string. The thing you get back won't
		* necessarily have a valid signature.
		*
		* New code should never use this; it's for backward compatibiliy.
		*
		* NOTE: <b>ri_body</b> is as returned by signed_descriptor_get_body: it might
		* not be NUL-terminated. */
		static char *
		munge_extrainfo_into_routerinfo(const char ri_body, signed_descriptor_t ri,
		signed_descriptor_t *ei)
		@@ -2355,7 +2363,8 @@ handle_control_closecircuit(control_connection_t *conn, uint32_t len,
		return 0;
		}

		/** DOCDOC */
		/** Called when we get a RESOLVE command: start trying to resolve
		* the listed addresses. */
		static int
		handle_control_resolve(control_connection_t *conn, uint32_t len,
		const char *body)
		@@ -2390,7 +2399,7 @@ handle_control_resolve(control_connection_t *conn, uint32_t len,
		return 0;
		}

		/** DOCDOC */
		/** Called when we get a PROTOCOLINFO command: send back a reply. */
		static int
		handle_control_protocolinfo(control_connection_t *conn, uint32_t len,
		const char *body)
		@@ -3554,7 +3563,8 @@ control_event_guard(const char nickname, const char digest,
		return 0;
		}

		/** DOCDOC */
		/** Helper: Return a newly allocated string containing a path to the
		* file where we store our authentication cookie. */
		static char *
		get_cookie_file(void)
		{