Committer : entrope
CVSROOT : /cvsroot/undernet-ircu
Module : ircu2.10
Commit time: 2004-10-03 13:36:15 UTC
Modified files:
include/listener.h ircd/listener.c
Log message:
Doxyfy listener.h and listener.c.
---------------------- diff included ----------------------
Index: ircu2.10/include/listener.h
diff -u ircu2.10/include/listener.h:1.5 ircu2.10/include/listener.h:1.6
--- ircu2.10/include/listener.h:1.5 Sat Sep 11 20:53:44 2004
+++ ircu2.10/include/listener.h Sun Oct 3 06:36:04 2004
@@ -14,9 +14,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: listener.h,v 1.5 2004/09/12 03:53:44 entrope Exp $
+ */
+/** @file
+ * @brief Interface and declarations for handling listening sockets.
+ * @version $Id: listener.h,v 1.6 2004/10/03 13:36:04 entrope Exp $
*/
#ifndef INCLUDED_listener_h
#define INCLUDED_listener_h
@@ -37,23 +38,22 @@
struct Client;
struct StatDesc;
+/** Describes a single listening port. */
struct Listener {
- struct Listener* next; /* list node pointer */
- int fd; /* file descriptor */
- int ref_count; /* number of connection references */
- unsigned char active; /* current state of listener */
- unsigned char hidden; /* hidden in stats output for clients */
- unsigned char server; /* 1 if port is a server listener */
- unsigned char mask_bits; /* number of bits in mask address */
- int index; /* index into poll array */
- time_t last_accept; /* last time listener accepted */
- struct irc_sockaddr addr; /* virtual address and port */
- struct irc_in_addr mask; /* listener hostmask */
- struct Socket socket; /* describe socket to event system */
+ struct Listener* next; /**< list node pointer */
+ int fd; /**< file descriptor */
+ int ref_count; /**< number of connection references */
+ unsigned char active; /**< current state of listener */
+ unsigned char hidden; /**< hidden in stats output for clients */
+ unsigned char server; /**< 1 if port is a server listener */
+ unsigned char mask_bits; /**< number of bits in mask address */
+ int index; /**< index into poll array */
+ time_t last_accept; /**< last time listener accepted */
+ struct irc_sockaddr addr; /**< virtual address and port */
+ struct irc_in_addr mask; /**< listener hostmask */
+ struct Socket socket; /**< describe socket to event system */
};
-extern struct Listener* ListenerPollList; /* GLOBAL - listener list */
-
extern void add_listener(int port, const char* vaddr_ip,
const char* mask, int is_server,
int is_hidden);
Index: ircu2.10/ircd/listener.c
diff -u ircu2.10/ircd/listener.c:1.24 ircu2.10/ircd/listener.c:1.25
--- ircu2.10/ircd/listener.c:1.24 Mon Sep 13 11:38:32 2004
+++ ircu2.10/ircd/listener.c Sun Oct 3 06:36:05 2004
@@ -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: listener.c,v 1.24 2004/09/13 18:38:32 entrope Exp $
+ */
+/** @file
+ * @brief Implementation for handling listening sockets.
+ * @version $Id: listener.c,v 1.25 2004/10/03 13:36:05 entrope Exp $
*/
#include "config.h"
@@ -49,14 +51,17 @@
#include <sys/socket.h>
#include <arpa/inet.h>
-#ifndef INADDR_NONE
-#define INADDR_NONE ((unsigned int) 0xffffffff)
-#endif
-
+/** List of listening sockets. */
struct Listener* ListenerPollList = 0;
static void accept_connection(struct Event* ev);
+/** Allocate and initialize a new Listener structure for a particular
+ * socket address.
+ * @param[in] port Port number to listen on.
+ * @param[in] addr Local address to listen on.
+ * @return Newly allocated and initialized Listener.
+ */
static struct Listener* make_listener(int port, const struct irc_in_addr *addr)
{
struct Listener* listener =
@@ -76,17 +81,21 @@
return listener;
}
+/** Deallocate a Listener structure.
+ * @param[in] listener Listener to be freed.
+ */
static void free_listener(struct Listener* listener)
{
assert(0 != listener);
MyFree(listener);
}
+/** Maximum length for a port number. */
#define PORTNAMELEN 10 /* ":31337" */
-/*
- * get_listener_name - return displayable listener name and port
- * returns "host.foo.org:6667" for a given listener
+/** Return displayable listener name and port.
+ * @param[in] listener %Listener to format as a text string.
+ * @return Pointer to a static buffer that contains "server.name:6667".
*/
const char* get_listener_name(const struct Listener* listener)
{
@@ -96,8 +105,9 @@
return buf;
}
-/*
- * count_listener_memory - count memory and listeners
+/** Count allocated listeners and the memory they use.
+ * @param[out] count_out Receives number of allocated listeners.
+ * @param[out] size_out Receives bytes used by listeners.
*/
void count_listener_memory(int* count_out, size_t* size_out)
{
@@ -110,13 +120,11 @@
*count_out = count;
*size_out = count * sizeof(struct Listener);
}
-
-/*
- * show_ports - send port listing to a client
- * inputs - pointer to client to show ports to
- * output - none
- * side effects - show ports
- * author - Dianora
+
+/** Report listening ports to a client.
+ * @param[in] sptr Client requesting statistics.
+ * @param[in] sd Stats descriptor for request (ignored).
+ * @param[in] param Extra parameter from user (port number to search for).
*/
void show_ports(struct Client* sptr, const struct StatDesc* sd,
char* param)
@@ -164,9 +172,14 @@
#ifdef SOMAXCONN
#define HYBRID_SOMAXCONN SOMAXCONN
#else
+/** Maximum length of socket connection backlog. */
#define HYBRID_SOMAXCONN 64
#endif
+/** Open listening socket for \a listener.
+ * @param[in,out] listener Listener to make a socket for.
+ * @return Non-zero on success, zero on failure.
+ */
static int inetport(struct Listener* listener)
{
int fd;
@@ -215,11 +228,10 @@
return 1;
}
-/*
- * find_listener - find a listener in the list
- *
- * XXX - this function does N comparisons so if the list is huge
- * we may want to do something else for this. (rehash and init use this)
+/** Find the listener (if any) for a particular port and address.
+ * @param[in] port Port number to search for.
+ * @param[in] addr Local address to search for.
+ * @return Listener that matches (or NULL if none match).
*/
static struct Listener* find_listener(int port, const struct irc_in_addr *addr)
{
@@ -231,11 +243,15 @@
return 0;
}
-/*
- * add_listener- create a new listener
- * port - the port number to listen on
- * vhost_ip - if non-null must contain a valid IP address string in
- * the format "255.255.255.255"
+/** Make sure we have a listener for \a port on \a vhost_ip.
+ * If one does not exist, create it. Then mark it as active and set
+ * the peer mask, server, and hidden flags according to the other
+ * arguments.
+ * @param[in] port Port number to listen on.
+ * @param[in] vhost_ip Local address to listen on.
+ * @param[in] mask Address mask to accept connections from.
+ * @param[in] is_server Non-zero if the port should only accept server connections.
+ * @param[in] is_hidden Non-zero if the port should be hidden from /STATS P output.
*/
void add_listener(int port, const char* vhost_ip, const char* mask,
int is_server, int is_hidden)
@@ -278,9 +294,8 @@
free_listener(listener);
}
-/*
- * mark_listeners_closing - iterate through listeners and mark them as
- * inactive
+/** Mark all listeners as closing (inactive).
+ * This is done so unused listeners are closed after a rehash.
*/
void mark_listeners_closing(void)
{
@@ -289,8 +304,8 @@
listener->active = 0;
}
-/*
- * close_listener - close a single listener
+/** Close a single listener.
+ * @param[in] listener Listener to close.
*/
void close_listener(struct Listener* listener)
{
@@ -313,10 +328,8 @@
close(listener->fd);
socket_del(&listener->socket);
}
-
-/*
- * close_listeners - close and free all listeners that are not being used
- */
+
+/** Close all inactive listeners. */
void close_listeners()
{
struct Listener* listener;
@@ -331,6 +344,9 @@
}
}
+/** Dereference the listener previously associated with a client.
+ * @param[in] listener Listener to dereference.
+ */
void release_listener(struct Listener* listener)
{
assert(0 != listener);
@@ -339,8 +355,8 @@
close_listener(listener);
}
-/*
- * accept_connection - accept a connection on a listener
+/** Accept a connection on a listener.
+ * @param[in] ev Socket callback structure.
*/
static void accept_connection(struct Event* ev)
{
----------------------- End of diff -----------------------
