From: Michael Poole Date: Mon, 27 Sep 2004 22:22:47 +0000 (+0000) Subject: Doxyfy whowas.h and whowas.c. X-Git-Url: http://git.pk910.de/?a=commitdiff_plain;h=28179ce12deb2c6005995f5269e99092e6ccb94e;p=ircu2.10.12-pk.git Doxyfy whowas.h and whowas.c. git-svn-id: file:///home/klmitch/undernet-ircu/undernet-ircu-svn/ircu2/trunk@1182 c9e4aea6-c8fd-4c43-8297-357d70d61c8c --- diff --git a/include/whowas.h b/include/whowas.h index 5da1e25..8a06267 100644 --- a/include/whowas.h +++ b/include/whowas.h @@ -15,8 +15,10 @@ * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. - * - * $Id$ + */ +/* @file + * @brief Globally visible declarations to manipulate whowas information. + * @version $Id$ */ #ifndef INCLUDED_whowas_h #define INCLUDED_whowas_h @@ -31,35 +33,36 @@ struct Client; * General defines */ -#define BITS_PER_COL 3 -#define BITS_PER_COL_MASK 0x7 -#define WW_MAX_INITIAL 16 +#define BITS_PER_COL 3 /**< Magic number used by whowas hash function. */ +#define BITS_PER_COL_MASK 0x7 /**< Mask with #BITS_PER_COL least significant bits set. */ +#define WW_MAX_INITIAL 16 /**< Magic number used by whowas hash function. */ -#define MAX_SUB (1 << BITS_PER_COL) -#define WW_MAX_INITIAL_MASK (WW_MAX_INITIAL - 1) -#define WW_MAX (WW_MAX_INITIAL * MAX_SUB) +#define MAX_SUB (1 << BITS_PER_COL) /**< Magic number used by whowas hash function. */ +#define WW_MAX_INITIAL_MASK (WW_MAX_INITIAL - 1) /**< Magic number used by whowas hash function. */ +#define WW_MAX (WW_MAX_INITIAL * MAX_SUB) /**< Size of whowas hash table. */ /* * Structures */ +/** Tracks previously used nicknames. */ struct Whowas { - unsigned int hashv; - char *name; - char *username; - char *hostname; - char *realhost; - char *servername; - char *realname; - char *away; - time_t logoff; - struct Client *online; /* Needed for get_history() (nick chasing) */ - struct Whowas *hnext; /* Next entry with the same hash value */ - struct Whowas **hprevnextp; /* Pointer to previous next pointer */ - struct Whowas *cnext; /* Next entry with the same 'online' pointer */ - struct Whowas **cprevnextp; /* Pointer to previous next pointer */ - struct Whowas *wnext; /* Next entry in whowas linked list */ - struct Whowas *wprev; /* Pointer to previous next pointer */ + unsigned int hashv; /**< Hash value for nickname. */ + char *name; /**< Client's old nickname. */ + char *username; /**< Client's username. */ + char *hostname; /**< Client's hostname. */ + char *realhost; /**< Client's real hostname. */ + char *servername; /**< Name of client's server. */ + char *realname; /**< Client's realname (user info). */ + char *away; /**< Client's away message. */ + time_t logoff; /**< When the client logged off. */ + struct Client *online; /**< Needed for get_history() (nick chasing). */ + struct Whowas *hnext; /**< Next entry with the same hash value. */ + struct Whowas **hprevnextp; /**< Pointer to previous next pointer. */ + struct Whowas *cnext; /**< Next entry with the same 'online' pointer. */ + struct Whowas **cprevnextp; /**< Pointer to previous next pointer. */ + struct Whowas *wnext; /**< Next entry in whowas linked list. */ + struct Whowas *wprev; /**< Pointer to previous next pointer. */ }; /* diff --git a/ircd/whowas.c b/ircd/whowas.c index 5b72be0..b8fc173 100644 --- a/ircd/whowas.c +++ b/ircd/whowas.c @@ -31,8 +31,6 @@ * * --- Run --- 27th August 1997 * Speeded up the code, added comments. - * - * $Id$ */ #include "config.h" @@ -58,24 +56,30 @@ #include +/** Keeps track of whowas least-recently-used list. */ static struct { - struct Whowas *ww_list; /* list of whowas structures */ - struct Whowas *ww_tail; /* tail of list for getting structures */ - unsigned int ww_alloc; /* alloc count */ + struct Whowas *ww_list; /**< list of whowas structures */ + struct Whowas *ww_tail; /**< tail of list for getting structures */ + unsigned int ww_alloc; /**< alloc count */ } wwList = { 0, 0, 0 }; +/** Hash table of Whowas entries by nickname. */ struct Whowas* whowashash[WW_MAX]; -/* +/** @file + * @brief Manipulation functions for the whowas list. + * @version $Id$ + * * Since the introduction of numeric nicks (at least for upstream messages, - * like MODE +o , KICK #chan , KILL etc), there is no + * like MODE +o <nick>, KICK #chan <nick>, KILL <nick> etc), there is no * real important reason for a nick history anymore. * Nevertheless, there are two reason why we might want to keep it: - * 1) The /WHOWAS command, which is often usefull to catch harrashing + * @li The /WHOWAS command, which is often useful to catch harrassing * users or abusers in general. - * 2) Clients still use the normal nicks in the client-server protocol, + * @li Clients still use the normal nicks in the client-server protocol, * and it might be considered a nice feature that here we still have * nick chasing. + * * Note however that BOTH reasons make it redundant to keep a whowas history * for users that split off. * @@ -98,9 +102,9 @@ struct Whowas* whowashash[WW_MAX]; * is not anymore maintained (and hopefully not used anymore either ;). * * So now we have two ways of accessing this database: - * 1) Given a we can calculate a hashv and then whowashash[hashv] will + * @li Given a <nick> we can calculate a hashv and then whowashash[hashv] will * point to the start of the 'hash list': all entries with the same hashv. - * We'll have to search this list to find the entry with the correct . + * We'll have to search this list to find the entry with the correct <nick>. * Once we found the correct whowas entry, we have a pointer to the * corresponding client - if still online - for nich chasing purposes. * Note that the same nick can occur multiple times in the whowas history, @@ -108,25 +112,25 @@ struct Whowas* whowashash[WW_MAX]; * just a nick will return all entries, nick chasing will only find the * first in the list. Because new entries are added at the start of the * 'hash list' we will always find the youngest entry, which is what we want. - * 2) Given an online client we have a pointer to the first whowas entry + * @li Given an online client we have a pointer to the first whowas entry * of the linked list of whowas entries that all belong to this client. * We ONLY need this to reset all `online' pointers when this client * signs off. * - * 27/8/79: + * 27/8/97: * * Note that following: * - * a) We *only* (need to) change the 'hash list' and the 'online' list + * @li We *only* (need to) change the 'hash list' and the 'online' list * in add_history(). - * b) There we always ADD an entry to the BEGINNING of the 'hash list' + * @li There we always ADD an entry to the BEGINNING of the 'hash list' * and the 'online list': *new* entries are at the start of the lists. * The oldest entries are at the end of the lists. - * c) We always REMOVE the oldest entry we have (whowas_next), this means + * @li We always REMOVE the oldest entry we have (whowas_next), this means * that this is always an entry that is at the *end* of the 'hash list' * and 'online list' that it is a part of: the next pointer will * always be NULL. - * d) The previous pointer is *only* used to update the next pointer of the + * @li The previous pointer is *only* used to update the next pointer of the * previous entry, therefore we could better use a pointer to this * next pointer: That is faster - saves us a 'if' test (it will never be * NULL because the last added entry will point to the pointer that @@ -138,9 +142,9 @@ struct Whowas* whowashash[WW_MAX]; * --Run */ -/* whowas_clean() - * - * Clean up a whowas structure +/** Unlink a Whowas structure and free everything inside it. + * @param[in,out] ww The whowas record to free. + * @return The pointer \a ww. */ static struct Whowas * whowas_clean(struct Whowas *ww) @@ -187,9 +191,8 @@ whowas_clean(struct Whowas *ww) return ww; } -/* whowas_free() - * - * Free a struct Whowas... +/** Clean and free a whowas record. + * @param[in] ww Whowas record to free. */ static void whowas_free(struct Whowas *ww) @@ -205,39 +208,23 @@ whowas_free(struct Whowas *ww) wwList.ww_alloc--; } -/* whowas_init() - * - * Initializes a given whowas structure +/** Initialize a whowas record. + * @param[in,out] ww Whowas record to initialize. + * @return The pointer \a ww. */ static struct Whowas * whowas_init(struct Whowas *ww) { - if (!ww) - return 0; - - ww->hashv = 0; - ww->name = 0; - ww->username = 0; - ww->hostname = 0; - ww->realhost = 0; - ww->servername = 0; - ww->realname = 0; - ww->away = 0; - ww->logoff = 0; - ww->online = 0; - ww->hnext = 0; - ww->hprevnextp = 0; - ww->cnext = 0; - ww->cprevnextp = 0; - ww->wnext = 0; - ww->wprev = 0; - + if (ww) + memset(ww, 0, sizeof(*ww)); return ww; } -/* whowas_alloc() - * - * Returns a whowas structure to use +/** Return a fresh Whowas record. + * If the total number of records is smaller than determined by + * FEAT_NICKNAMEHISTORYLENGTH, allocate a new one. Otherwise, + * reuse the oldest record in use. + * @return A pointer to a clean Whowas. */ static struct Whowas * whowas_alloc(void) @@ -249,9 +236,9 @@ whowas_alloc(void) return whowas_init((struct Whowas *) MyMalloc(sizeof(struct Whowas))); } -/* whowas_realloc() - * - * Prune whowas list +/** If necessary, trim the whowas list. + * This function trims the whowas list until it contains no more than + * FEAT_NICKNAMEHISTORYLENGTH records. */ void whowas_realloc(void) @@ -271,14 +258,9 @@ whowas_realloc(void) } } -/* - * add_history - * - * Add a client (cptr) that just changed nick (still_on == true), or - * just signed off (still_on == false) to the `whowas' table. - * - * If the entry used was already in use, then this entry is - * freed (lost). +/** Add a client to the whowas list. + * @param[in] cptr Client to add. + * @param[in] still_on If non-zero, link the record to the client's personal history. */ void add_history(struct Client *cptr, int still_on) { @@ -324,11 +306,8 @@ void add_history(struct Client *cptr, int still_on) whowashash[ww->hashv] = ww; } -/* - * off_history - * - * Client `cptr' signed off: Set all `online' pointers - * corresponding to this client to NULL. +/** Clear all Whowas::online pointers that point to a client. + * @param[in] cptr Client who is going offline. */ void off_history(const struct Client *cptr) { @@ -338,15 +317,10 @@ void off_history(const struct Client *cptr) temp->online = NULL; } -/* - * get_history - * - * Return a pointer to a client that had nick `nick' not more then - * `timelimit' seconds ago, if still on line. Otherwise return NULL. - * - * This function is used for "nick chasing"; since the use of numeric - * nicks for "upstream" messages in ircu2.10, this is only used for - * looking up non-existing nicks in client->server messages. +/** Find a client who has recently used a particular nickname. + * @param[in] nick Nickname to find. + * @param[in] timelimit Maximum age for entry. + * @return User's online client, or NULL if none is found. */ struct Client *get_history(const char *nick, time_t timelimit) { @@ -360,6 +334,13 @@ struct Client *get_history(const char *nick, time_t timelimit) return NULL; } +/** Count memory used by whowas list. + * @param[out] wwu Number of entries in whowas list. + * @param[out] wwum Total number of bytes used by nickname, username, + * hostname and servername fields. + * @param[out] wwa Number of away strings in whowas list. + * @param[out] wwam Total number of bytes used by away strings. + */ void count_whowas_memory(int *wwu, size_t *wwum, int *wwa, size_t *wwam) { struct Whowas *tmp; @@ -389,7 +370,7 @@ void count_whowas_memory(int *wwu, size_t *wwum, int *wwa, size_t *wwam) *wwam = am; } - +/** Initialize whowas table. */ void initwhowas(void) { int i; @@ -398,6 +379,10 @@ void initwhowas(void) whowashash[i] = 0; } +/** Calculate a hash value for a string. + * @param[in] name Nickname to calculate hash over. + * @return Calculated hash value. + */ unsigned int hash_whowas_name(const char *name) { unsigned int hash = 0;