Adaugă codul complet al proiectului underchat-ircd

This commit is contained in:
mihaiitdata committed 2026-02-13 00:04:12 +02:00
1 parent caba5224bf
commit 5fdc1cc27c
462 files changed
+164488

No files matched your search

+105
View File
@@ -0,0 +1,105 @@
This directory is intended for documents describing programming
interfaces within ircu, including such things as modebuf's and the
features interface. Please write these documents as plain text; if we
want HTML, we can write a script to convert the text versions into
HTML versions. Toward that end, I respectfully suggest everyone
conform to a common format, which I will describe here:
Every .txt file should begin with a couple of paragraphs giving an
overview of the API, its purpose, and how to use it. Paragraphs
should be separated by blank lines, as shown here. Paragraphs that do
not end in some form of punctuation, such as a period, will be treated
as section headings. The introduction ends when the first API element
appears. API element documentation is introduced with "<" followed by
the element type--"struct", "typedef", "function", "macro", or (heaven
forbid) "global", followed by ">", all on a line by itself. The next
line should contain a declaration of the element as it would appear in
a header file; this may spread across multiple lines and contain
comments and blank lines. The declaration ends for most elements when
a ";" is encountered; for macros, the declaration ends on the last
line not ending in "\".
The documentation for the API element should immediately follow the
declaration of that element, and should be separated from it by a
single blank line. This documentation should explain the purpose of
the element and describe what each of its fields mean. The
documentation ends when the corresponding "</" tag is reached, just as
in HTML or XML. (I don't intend for the files to be either HTML or
XML, I just want them to be easy to parse so they could be turned into
either, as occasion warrants.) An example follows:
<struct>
struct FooBar; /* a sample structure with no definition */
The comment, since it's on the same line as the ";", is associated
with the declaration for struct FooBar.
</struct>
<struct>
struct FooBar {
long fb_magic; /* a magic number */
char *fb_string; /* a string of some sort */
};
The sequence "};" ends the struct declaration.
</struct>
<typedef>
typedef FooBar_t; /* a simple typedef */
This element shows how to hide the inner workings of typedefs.
</typedef>
<typedef>
typedef struct FooBar FooBar_t; /* a more complex typedef */
Here we show the full typedef declaration.
</typedef>
<global>
extern int fooBarFreeList; /* global variables should be avoided */
You should avoid global variables, but if you must have one for alloc
counts or whatever, here's how to specify documentation for them.
</global>
<macro>
#define HAVE_FOOBAR /* We have FOOBAR, whatever it may be */
This could be used for boolean macros (macros used in #ifdef's, for
instance) or for simple value macros where you're hiding the values.
Since there are so many variations on macros, I'll only show one other
variation below:
</macro>
<macro>
#define FooBarVerify(foobar) ((foobar) && \
(foobar)->fb_magic == FOOBAR_STRUCT_MAGIC)
This macro takes arguments. Again, we could leave out the actual
definition, or even treat the macro as a function rather than a
macro. This also shows how to do multi-line macros.
</macro>
<function>
void *foobar(struct FooBar *blah, int flag);
Since function definitions never appear in header files anyway, we
don't have to worry about hiding information. You should leave off
"extern" in the function declaration, and please include names for the
variables, so you can refer to them in the function documentation.
</function>
The API document may then end in some summary information, if you
wish, or a ChangeLog of some form, such as follows.
<authors>
Kev <klmitch@mit.edu>
</authors>
<changelog>
[2000-12-18 Kev] Initial definition of how API documents should look.
Further entries in the changelog should *precede* this one and should
be separated from it by a blank line. Also specify your name, as
listed in the "<authors>" section, so we know who to blame ;)
</changelog>
+816
View File
@@ -0,0 +1,816 @@
The IRC server is built around an event loop. Until the u2.10.11
release, this event loop has been rather ad-hoc; timed events are
hard-coded in, signals are handled inside the signal handler, etc.
All of this has changed with u2.10.11. A new subsystem, the events
subsystem, has been introduced; the new subsystem contains a
generalization of the concept of an event. An event is a signal, the
expiration of a timer, or some form of activity on a network socket.
This new subsystem has the potential to vastly simplify the code that
is arguably the core of any network program, and makes it much simpler
to support more exotic forms of network activity monitoring than the
conventional select() and poll() calls.
The primary concepts that the events subsystem works with are the
"event," represented by a struct Event, and the "generator." There
are three types of generators: sockets, represented by struct Socket;
signals, represented by struct Signal; and timers, represented by
struct Timer. Each of these generators will be described in turn.
Signals
The signal is perhaps the simplest generator in the entire events
subsystem. Basically, instead of setting a signal handler, the
function signal_add() is called, specifying a function to be called
when a given signal is detected. Most importantly, that call-back
function is called _outside_ the context of a signal handler,
permitting the call-back to use more exotic functions that are
anathema within a signal handler, such as MyMalloc(). Once a
call-back for a signal has been established, it cannot be deleted;
this design decision was driven by the fact that ircd never changes
its signal handlers.
Whenever a signal is received, an event of type ET_SIGNAL is
generated, and that event is passed to the event call-back function
specified in the signal_add() call.
Timers
Execution of the call-back functions for a timer occur when that timer
_expires_; when a timer expires depends on the type of timer and the
expiration time that was used for that timer. A TT_ABSOLUTE timer,
for instance, expires at exactly the time given as the expiration
time. This time is a standard UNIX time_t value, measuring seconds
since the UNIX epoch. The TT_ABSOLUTE timer type is complemented by
the TT_RELATIVE timer; the time passed as its expiration time is
relative to the current time. If a TT_RELATIVE timer is given an
expiration time of 5, for instance, it will expire 5 seconds after the
present time. Internally, TT_RELATIVE timers are converted into
TT_ABSOLUTE timers, with the expiration time adjusted by addition of
the current time.
Those two types of timers, TT_ABSOLUTE and TT_RELATIVE, are
single-shot timers. Once they expire, they are removed from the timer
list unless re-added by the event call-back or through some other
mechanism. There is another type of timer, however, the TT_PERIODIC
timer, that is not removed from the timer list. TT_PERIODIC timers
are similar to TT_RELATIVE timers, in that one passes in the expire
time as a relative number of seconds, but when they expire, they are
re-added to the timer list with the same relative expire time. This
means that a TT_PERIODIC timer with an expire time of 5 seconds that
is set at 11:50:00 will have its call-back called at 11:50:05,
11:50:10, 11:50:15, and so on.
Timers have to be run by the event engines explicitly by calling
timer_run() on the generator list passed to the engine event loop.
In addition, engines may determine the next (absolute) time that a
timer needs to be run by calling the timer_next() macro; this may be
used to set a timeout on the engine's network activity monitoring
function. Engines are described in detail below.
When a timer expires, an event of ET_EXPIRE is generated, and the
call-back function is called. When a timer is destroyed, either as
the result of an expiration or as a result of an explicit timer_del()
call, an event of ET_DESTROY is generated, notifying the call-back
that the struct Timer can be deallocated.
Sockets
Perhaps the most complicated event generator in all of the event
system is the socket, as described by struct Socket. This single
classification covers datagram sockets and stream sockets. To
differentiate the different kinds of sockets, there is a socket state
associated with each socket. The available states are SS_CONNECTING,
which indicates that a particular socket is in the process of
completing a non-blocking connect(); SS_LISTENING, which indicates
that a particular socket is a listening socket; SS_CONNECTED, which is
the state of every other stream socket; SS_DATAGRAM, which is an
ordinary datagram socket, and SS_CONNECTDG, which describes a
connected datagram socket. (The SS_NOTSOCK state is for the internal
use of the events system and will not be described here.)
In addition to the socket states, there's also an event mask for each
socket; this set of flags is used to tell the events subsystem what
events the application is interested in for the socket. For
SS_CONNECTING and SS_LISTENING sockets, this events mask has no
meaning, but on the other socket states, the event mask is used to
determine if the application is interested in readable
(SOCK_EVENT_READABLE) or writable (SOCK_EVENT_WRITABLE) indications.
Most of the defined event types have to do with socket generators.
When a socket turns up readable, for instance, an event of type
ET_READ is generated. Similarly, ET_WRITE is generated when a socket
can be written to. The ET_ACCEPT event is generated when a listening
socket indicates that there is a connection to be accepted; ET_CONNECT
is generated when a non-blocking connect is completed. Finally, if an
end-of-file indication is detected, ET_EOF is generated, whereas if an
error has occurred on the socket, ET_ERROR is generated. Of course,
when a socket has been deleted by the socket_del() function, an event
of ET_DESTROY is generated when it is safe for the memory used by the
struct Socket to be reclaimed.
Events
An event, represented by a struct Event, describes in detail all of
the particulars of an event. Each event has a type, and an optional
integer piece of data may be passed with some events--in particular,
ET_SIGNAL events pass the signal number, and ET_ERROR events pass the
errno value. The struct Event also contains a pointer to the
structure describing the generated event--although it should be noted
that the only way to disambiguate which type of generator is contained
within the struct Event is by which call-back function has been
called.
All generators have a void pointer which can be used to pass important
information to the call-back, such as a pointer to a struct Client.
Additionally, generators have a reference count, and a union of a void
pointer and an integer that should only be utilized by the event
engine. Finally, there is also a field for flags, although the only
flag of concern to the application (or the engine) is the active flag,
which may be tested using the test macros described below.
Whatever the generator, the call-back function is a function returning
nothing (void) and taking as its sole argument a pointer to struct
Event. This call-back function may be implemented as a single switch
statement that calls out to appropriate external functions as needed.
Engines
Engines implement the actual socket event loop, and may also have some
means of receiving signal events. Each engine has a name, which
should describe what its core function is; for instance, the engine
based on the standard select() function is named, simply, "select()."
Each engine must implement several call-backs which are used to
initialize the engine, notify the engine of sockets the application is
interested in, etc. All of this data is described by a single struct
Engine, which should be the only non-static variable or function in
the engine's source file.
The engine's event loop, pointed to by the eng_loop field of the
struct Engine, must consist of a single while loop predicated on the
global variable _running_. Additionally, this loop's final statement
must be a call to timer_run(), to execute all timers that have become
due. Ideally, this construction should be pulled out of each engine's
eng_loop and put in the event_loop() function of the events
subsystem.
Reference Counts
As mentioned previously, all generators keep a reference count.
Should timer_del() or socket_del() be called on a generator with a
non-zero reference count, for whatever reason, the actual destruction
of the generator will be delayed until the reference count again
reaches zero. This is used by the event loop to keep sockets that it
is currently referencing from being deallocated before it is done
checking all pending events on them. To increment the reference count
by one, call gen_ref_inc() on the generator; the corresponding macro
gen_ref_dec() decrements the reference counts, and will automatically
destroy the generator if the appropriate conditions are met.
Debugging Functions
It can be difficult to debug an engines if, say, a socket state can
only be expressed as a meaningless number. Therefore, when DEBUGMODE
is #define'd, five number-to-name functions are also defined to make
the debugging data more meaningful. These functions must only be
called when DEBUGMODE is #define'd. Calling them from within Debug()
macro calls is safe; calling them from log_write() calls is not.
<typedef>
typedef void (*EventCallBack)(struct Event*);
The _EventCallBack_ type is used to simplify declaration of event
call-back functions. It is used in timer_add(), signal_add(), and
socket_add(). The event call-back should process the event, taking
whatever actions are necessary. The function should be declared as
returning void.
</typedef>
<typedef>
typedef int (*EngineInit)(int);
The _EngineInit_ function takes an integer specifying the maximum
number of sockets the event system is expecting to handle. This
number may be used by the engine initialization function for memory
allocation computations. If initialization succeeds, this function
must return 1. If initialization fails, the function should clean up
after itself and return 0. The events subsystem has the ability to
fall back upon another engine, should an engine initialization fail.
Needless to say, the engines based upon poll() and select() should
never fail in this way.
</typedef>
<typedef>
typedef void (*EngineSignal)(struct Signal*);
If an engine has the capability to directly detect signals, it should
set the eng_signal field of struct Engine non-zero. When the
application indicates interest in a particular signal, the
_EngineSignal_ function will be called with the filled-in struct
Signal, in order to register interest in that signal with the engine.
</typedef>
<typedef>
typedef int (*EngineAdd)(struct Socket*);
All engines must define an _EngineAdd_ function, which is used to
inform the engine of the application's interest in the socket. If the
new socket cannot be accommodated by the engine for whatever reason,
this function must return 0. Otherwise, the function must return 1,
informing the events subsystem that the interest has been noted.
</typedef>
<typedef>
typedef void (*EngineState)(struct Socket*, enum SocketState new_state);
Sockets can change state. SS_CONNECTING sockets, for instance, can
become SS_CONNECTED. Whenever a socket state changes, the engine is
informed, since some states require different notification procedures
than others. This is accomplished by calling the _EngineState_
function with the new state. The struct Socket passed to the engine
will still have the old state, if the engine must reference that.
</typedef>
<typedef>
typedef void (*EngineEvents)(struct Socket*, unsigned int new_events);
Applications may only be interested in given events on a socket for a
limited time. When the application's interest shifts, a new events
mask is set for the socket. The engine is informed of this change by
a call to its _EngineEvents_ function.
</typedef>
<typedef>
typedef void (*EngineDelete)(struct Socket*);
Eventually, an application will close all the sockets it has opened.
When a socket is closed, and the corresponding struct Socket deleted
with a call to socket_del(), the _EngineDelete_ function will be
called to notify the engine of the change.
</typedef>
<typedef>
typedef void (*EngineLoop)(struct Generators*);
The workhorse of the entire events subsystem is the event loop,
implemented by each engine as the _EngineLoop_ function. This
function is called with a single argument that may be passed to
timer_next() to calculate the next time a timer will expire.
</typedef>
<enum>
enum SocketState {
SS_CONNECTING, /* Connection in progress on socket */
SS_LISTENING, /* Socket is a listening socket */
SS_CONNECTED, /* Socket is a connected socket */
SS_DATAGRAM, /* Socket is a datagram socket */
SS_CONNECTDG, /* Socket is a connected datagram socket */
SS_NOTSOCK /* Socket isn't a socket at all */
};
This enumeration contains a list of all possible states a socket can
be in. Applications should not use SS_NOTSOCK; engines should treat
it as a special socket state for non-sockets. The only event that
should be watched for on a struct Socket in the SS_NOTSOCK state is
readability. This socket state is used to implement the fall-back
signal event generation.
</enum>
<enum>
enum TimerType {
TT_ABSOLUTE, /* timer that runs at a specific time */
TT_RELATIVE, /* timer that runs so many seconds in the future */
TT_PERIODIC /* timer that runs periodically */
};
The three possible timer types are defined by the TimerType
enumeration. More details can be found in the "Timers" sub-section.
</enum>
<enum>
enum EventType {
ET_READ, /* Readable event detected */
ET_WRITE, /* Writable event detected */
ET_ACCEPT, /* Connection can be accepted */
ET_CONNECT, /* Connection completed */
ET_EOF, /* End-of-file on connection */
ET_ERROR, /* Error condition detected */
ET_SIGNAL, /* A signal was received */
ET_EXPIRE, /* A timer expired */
ET_DESTROY /* The generator is being destroyed */
};
This enumeration contains all the types of events that can be
generated by the events subsystem. The first 6 are generated by
socket generators, the next by signal generators, and the next by
timer generators. ET_DESTROY is generated by both socket and timer
generators when the events subsystem is finished with the memory
allocated by both.
</enum>
<struct>
struct Socket;
This structure describes everything the events subsystem knows about a
given socket. All of its fields may be accessed through the s_*
macros described below.
</struct>
<struct>
struct Timer;
The struct Timer structure describes everything the events subsystem
knows about a given timer. Again, all of its fields may be accessed
through the t_* macros described below.
</struct>
<struct>
struct Signal;
Signal generators are described by a struct Signal. All of the fields
of a struct Signal may be accessed by the sig_* macros described
below.
</struct>
<struct>
struct Event;
Each event is described by a struct Event. Its fields may be examined
using the ev_* macros described below.
</struct>
<struct>
struct Generators;
Each engine is passed a list of all generators when the engine's
_EngineLoop_ function is called. The only valid way to access this
structure is via the timer_next() function described below.
</struct>
<struct>
struct Engine {
const char* eng_name; /* a name for the engine */
EngineInit eng_init; /* initialize engine */
EngineSignal eng_signal; /* express interest in a signal */
EngineAdd eng_add; /* express interest in a socket */
EngineState eng_state; /* mention a change in state to engine */
EngineEvents eng_events; /* express interest in socket events */
EngineDelete eng_closing; /* socket is being closed */
EngineLoop eng_loop; /* actual event loop */
};
Each engine is described by the struct Engine structure. Each engine
must define all of the functions described above except for the
_EngineSignal_ function, which is optional.
</struct>
<macro>
#define SOCK_EVENT_READABLE 0x0001 /* interested in readable */
The SOCK_EVENT_READABLE flag indicates to the engine that the
application is interested in readability on this particular socket.
</macro>
<macro>
#define SOCK_EVENT_WRITABLE 0x0002 /* interested in writable */
The SOCK_EVENT_WRITABLE flag indicates to the engine that the
application is interested in this socket being writable.
</macro>
<macro>
#define SOCK_EVENT_MASK (SOCK_EVENT_READABLE | SOCK_EVENT_WRITABLE)
SOCK_EVENT_MASK may be used to extract only the event interest flags
from an event interest set.
</macro>
<macro>
#define SOCK_ACTION_SET 0x0000 /* set interest set as follows */
When socket_events() is called with a set of event interest flags and
SOCK_ACTION_SET, the socket's event interest flags are set to those
passed into socket_events().
</macro>
<macro>
#define SOCK_ACTION_ADD 0x1000 /* add to interest set */
When SOCK_ACTION_ADD is used in a call to socket_events(), the event
interest flags passed in are added to the existing event interest
flags for the socket.
</macro>
<macro>
#define SOCK_ACTION_DEL 0x2000 /* remove from interest set */
When SOCK_ACTION_DEL is used in a call to socket_events(), the event
interest flags passed in are removed from the existing event interest
flags for the socket.
</macro>
<macro>
#define SOCK_ACTION_MASK 0x3000 /* mask out the actions */
SOCK_ACTION_MASK is used to isolate the socket action desired.
</macro>
<function>
enum SocketState s_state(struct Socket* sock);
This macro returns the state of the given socket.
</function>
<function>
unsigned int s_events(struct Socket* sock);
This macro returns the current event interest mask for a given
socket. Note that if the socket is in the SS_CONNECTING or
SS_LISTENING states, this mask has no meaning.
</function>
<function>
int s_fd(struct Socket* sock);
This macro simply returns the file descriptor for the given socket.
</function>
<function>
void* s_data(struct Socket* sock);
When a struct Socket is initialized, data that the call-back function
may find useful, such as a pointer to a struct Connection, is stored
in the struct Socket. This macro returns that pointer.
</function>
<function>
int s_ed_int(struct Socket* sock);
Engines may find it convenient to associate an integer with a struct
Socket. This macro may be used to retrieve that integer or, when used
as an lvalue, to assign a value to it. Engine data must be either an
int or a void*; use of both is prohibited.
</function>
<function>
void* s_ed_ptr(struct Socket* sock);
Engines may find it convenient to associate a void* pointer with a
struct Socket. This macro may be used to retrieve that pointer or,
when used as an lvalue, to assign a value to it. Engine data must be
either an int or a void*; use of both is prohibited.
</function>
<function>
int s_active(struct Socket* sock);
A socket's active flag is set when initialized by socket_add(), and is
cleared immediately prior to generating an event of type ET_DESTROY.
This may be used by the application to determine whether or not the
socket is still in use by the events subsystem. If it is, s_active()
returns a non-zero value; otherwise, its value is 0.
</function>
<function>
int socket_add(struct Socket* sock, EventCallBack call, void* data,
enum SocketState state, unsigned int events, int fd);
This function is called to add a socket to the list of sockets to be
monitored. The _sock_ parameter is a pointer to a struct Socket that
is allocated by the application. The _call_ parameter is a pointer to
a function to process any events on the socket. The _data_ parameter
is for use of the socket call-back and may be zero. The _state_
parameter must be one of the valid socket states. The _events_
parameter must be a valid events interest mask--0, or the binary OR of
SOCK_EVENT_READABLE or SOCK_EVENT_WRITABLE. Finally, the _fd_
parameter specifies the socket's file descriptor. This function
returns 1 if successful or 0 otherwise.
</function>
<function>
void socket_del(struct Socket* sock);
When the application is no longer interested in a particular socket,
it should call the socket_del() function. This function must be
called no later than when the socket has been closed, to avoid
attempting to call select() or similar functions on closed sockets.
</function>
<function>
void socket_state(struct Socket* sock, enum SocketState state);
Occasionally, a socket's state will change. This function is used to
inform the events subsystem of that change. Only certain state
transitions are valid--a socket in the SS_LISTENING or SS_CONNECTED
states cannot change states, nor can an SS_CONNECTING socket change to
some state other than SS_CONNECTED. Of course, SS_DATAGRAM sockets
may change state only to SS_CONNECTDG, and SS_CONNECTDG sockets may
only change states to SS_DATAGRAM.
</function>
<function>
void socket_events(struct Socket* sock, unsigned int events);
When the application changes the events it is interested in, it uses
socket_events() to notify the events subsystem of that change. The
_events_ parameter is the binary OR of one of SOCK_ACTION_SET,
SOCK_ACTION_ADD, or SOCK_ACTION_DEL with an events mask. See the
documentation for the SOCK_* macros for more information.
</function>
<function>
const char* state_to_name(enum SocketState state);
This function is defined only when DEBUGMODE is #define'd. It takes
the given _state_ and returns a string giving that state's name. This
function may safely be called from Debug() macros.
</function>
<function>
const char* sock_flags(unsigned int flags);
This function is defined only when DEBUGMODE is #define'd. It takes
the given event interest flags and returns a string naming each of
those flags. This function may safely be called from Debug() macros,
but may only be called once, since it uses function static storage to
store the flag strings.
</function>
<function>
int sig_signal(struct Signal* sig);
This macro returns the signal number for the given struct Signal.
</function>
<function>
void* sig_data(struct Signal* sig);
When a struct Signal is initialized, data that the call-back function
may find useful is stored in the struct Signal. This macro returns
that pointer.
</function>
<function>
int sig_ed_int(struct Signal* sig);
Engines may find it convenient to associate an integer with a struct
Signal. This macro may be used to retrieve that integer or, when used
as an lvalue, to assign a value to it. Engine data must be either an
int or a void*; use of both is prohibited.
</function>
<function>
void* sig_ed_ptr(struct Signal* sig);
Engines may find it convenient to associate a void* pointer with a
struct Signal. This macro may be used to retrieve that pointer or,
when used as an lvalue, to assign a value to it. Engine data must be
either an int or a void*; use of both is prohibited.
</function>
<function>
int sig_active(struct Signal* sig);
A signal's active flag is set when initialized by signal_add(). This
may be used by the application to determine whether or not the signal
has been initialized yet. If it is, sig_active() returns a non-zero
value; otherwise, its value is 0.
</function>
<function>
void signal_add(struct Signal* signal, EventCallBack call, void* data,
int sig);
This function is called to add a signal to the list of signals to be
monitored. The _signal_ parameter is a pointer is a pointer to a
struct Signal that is allocated by the application. The _call_
parameter is a pointer to a function to process any signal events.
The _data_ parameter is for use of the signal call-back and may be
zero. The _sig_ parameter is the integer value of the signal to be
monitored.
</function>
<function>
enum TimerType t_type(struct Timer* tim);
This macro returns the type of the given timer.
</function>
<function>
time_t t_value(struct Timer* tim);
This macro returns the value that was used when the given timer was
initialized by the events subsystem. It will contain an absolute time
if the timer type is TT_ABSOLUTE, and a relative time otherwise.
</function>
<function>
time_t t_expire(struct Timer* tim);
This macro returns the absolute time at which the timer will next
expire.
</function>
<function>
void* t_data(struct Timer* tim);
When a struct Timer is initialized, data that the call-back function
may find useful is stored in the struct Socket. This macro returns
that pointer.
</function>
<function>
int t_ed_int(struct Timer *tim);
Engines may find it convenient to associate an integer with a struct
Timer. This macro may be used to retrieve that integer or, when used
as an lvalue, to assign a value to it. Engine data must be either an
int or a void*; use of both is prohibited.
</function>
<function>
void* t_ed_ptr(struct Timer *tim);
Engines may find it convenient to associate a void* pointer with a
struct Timer. This macro may be used to retrieve that pointer or,
when used as an lvalue, to assign a value to it. Engine data must be
either an int or a void*; use of both is prohibited.
</function>
<function>
int t_active(struct Timer *tim);
A timer's active flag is set when initialized by timer_add(), and is
cleared immediately prior to generating an event of type ET_DESTROY.
This may be used by the application to determine whether or not the
timer is still in use by the events subsystem. If it is, s_active()
returns a non-zero value; otherwise, its value is 0.
</function>
<function>
void timer_add(struct Timer* timer, EventCallBack call, void* data,
enum TimerType type, time_t value);
This function is called to initialize and queue a timer. The _timer_
parameter is a pointer to a struct Timer that is allocated by the
application. The _call_ parameter is a pointer to a function to
process the timer's expiration. The _data_ parameter is for use of
the timer call-back and may be zero. The _type_ parameter must be one
of the valid timer types--TT_ABSOLUTE, TT_RELATIVE, or TT_PERIODIC.
Finally, _value_ is the value for the timer's expiration.
</function>
<function>
void timer_del(struct Timer* timer);
When the application no longer needs a TT_PERIODIC timer, or when it
wishes to stop a TT_ABSOLUTE or TT_RELATIVE timer before its
expiration, it should call the timer_del() function.
</function>
<function>
void timer_chg(struct Timer* timer, enum TimerType type, time_t value);
Occasionally, an application may wish to delay an existing TT_ABSOLUTE
or TT_RELATIVE timer; this may be done with the timer_chg() function.
The _type_ parameter must be one of TT_ABSOLUTE or
TT_RELATIVE--changing the values of TT_PERIODIC timers is not
supported. The _value_ parameter is the same as would be given to
timer_add() for that particular type of timer.
</function>
<function>
void timer_run(void);
When an engine has finished processing the results of its socket and
signal checks--just before it loops around to test for more events--it
should call the timer_run() function to expire any waiting timers.
</function>
<function>
time_t timer_next(struct Generators* gen);
Most engines will use a blocking call with a timeout to check for
socket activity. To determine when the next timer needs to be run,
and thus to calculate how long the call should block, the engine
should call timer_next() with the _gen_ parameter passed to the
_EngineLoop_ function. The timer_next() function returns an absolute
time, which may have to be massaged into a relative time before the
engine may use it.
</function>
<function>
const char* timer_to_name(enum TimerType type);
This function is defined only when DEBUGMODE is #define'd. It takes
the given _type_ and returns a string giving that type's name. This
function may safely be called from Debug() macros.
</function>
<function>
enum EventType ev_type(struct Event* ev);
This macro simply returns the type of the event _ev_.
</function>
<function>
int ev_data(struct Event* ev);
When an event is generated, a single integer can be passed along as a
piece of extra information. This can be used, for instance, to carry
an errno value when an ET_ERROR is generated. This macro simply
returns that integer.
</function>
<function>
struct Socket* ev_socket(struct Event* ev);
If the event was generated by a socket, this macro returns a pointer
to the struct Socket that generated the event. The results are
undefined if the event was not generated by a socket.
</function>
<function>
struct Signal* ev_signal(struct Event* ev);
If the event was generated by a signal, this macro returns a pointer
to the struct Signal that generated the event. The results are
undefined if the event was not generated by a signal.
</function>
<function>
struct Timer* ev_timer(struct Event* ev);
If the event was generated by a timer, this macro returns a pointer to
the struct Timer that generated the event. The results are undefined
if the event was not generated by a timer.
</function>
<function>
void event_init(int max_sockets);
Before any of the functions or macros described here can be called,
the events subsystem must be initialized by calling event_init(). The
_max_sockets_ parameter specifies to the events subsystem how many
sockets it must be able to support; this figure may be used for memory
allocation by the engines.
</function>
<function>
void event_loop(void);
Once the initial sockets are open, signals added, and timers queued,
the application must call the event_loop() function in order to
actually begin monitoring those sockets, signals, and timers.
</function>
<function>
void event_generate(enum EventType type, void* arg, int data);
This is the function called by the events subsystem to generate
particular events. The _type_ parameter specifies the type of event
to generate, and the _arg_ parameter must be a pointer to the event's
generator. The _data_ parameter may be used for passing such things
as signal numbers or errno values.
</function>
<function>
const char* event_to_name(enum EventType type);
This function is defined only when DEBUGMODE is #define'd. It takes
the given _type_ and returns a string giving that event type's name.
This function may safely be called from Debug() macros.
</function>
<function>
const char* engine_name(void);
This function is used to retrieve the name of the engine presently
being used by the events subsystem.
</function>
<function>
void gen_ref_inc(void* gen);
This macro increments the reference count of the generator _gen_,
preventing it from simply disappearing without warning.
</function>
<function>
void gen_ref_dec(void* gen);
This macro decrements the reference count of the generator _gen_, and
releases the memory associated with it by generating at ET_DESTROY
event if the reference count falls to zero and the generator is marked
for destruction. No references should be made to the generator after
calling this macro.
</function>
<authors>
Kev <klmitch@mit.edu>
</authors>
<changelog>
[2001-6-14 Kev] Finished initial description of the events subsystem.
[2001-6-13 Kev] Initial description of the events subsystem.
</changelog>
+230
View File
@@ -0,0 +1,230 @@
As of u2.10.11, most of the compile-time configuration options present
in previous versions of ircu have been provided via the configuration
file as "features." This document is intended not only to give an
explanation of how to use the features subsystem in new code, but also
how to define new features.
In the ircd_features.h header file is an enum Feature that lists all
the features known to the features subsystem. The order of entries in
this list must match precisely the order of features as listed in the
features[] table in ircd_features.c. There are four kinds of
features, seven different flags that can be set for features, and
seven different call-backs for more complex features.
Types of Features
There are at present four different types of features: NONE, INT,
BOOL, and STR. Features of type "NONE" are complex features, such as
the logging subsystem, that have complicated behavior that's managed
through the use of call-backs. The call-backs available are set,
which is called to set the value of the feature; reset, which is
called to reset the value of the feature back to its default; get,
which is called to send the user a RPL_FEATURE to describe the feature
setting; unmark, which is called prior to reading the configuration
file; mark, which is called after reading the configuration file; and
report, which is used to send a user a list of RPL_STATSFLINE
replies.
In comparison to type "NONE," the other types are very simple. Type
"INT" is used for features that take an integer value; "BOOL" is for
those features that are boolean types; and "STR" is for those features
that take simple string values. The values for these feature types
are handled directly by the features subsystem, and can be examined
from code with the feature_int(), feature_bool(), and feature_str()
functions, described below. These features have a notify callback,
which is used to warn subsystems that use the values of particular
features that the value has changed.
Feature Flags
There are seven feature flags, one of which is used internally by the
feature subsystem. Three of these flags, FEAT_OPER, FEAT_MYOPER, and
FEAT_NODISP, are used to select who can see the settings of those
features; FEAT_OPER permits any operator anywhere on the network to
examine the settings of a particular feature, whereas FEAT_MYOPER only
permits operators local to a server to examine feature values, and
FEAT_NODISP prohibits display of the feature value altogether. If
none of these three flags are specified, then any user may examine
that feature's value.
Two other flags only have any meaning for string values; they are
FEAT_NULL, which is used to specify that a feature of type "STR" may
have a NULL value, and FEAT_CASE, which specifies that the feature is
case sensitive--this may be used on file names, for example. Note
that if you give "0" as the default value for a feature, you must also
set the FEAT_NULL flag.
The remaining non-internal flag is FEAT_READ, which simply sets the
feature to be read-only; a feature so marked may only be changed
through the configuration file.
Marking Features
When the configuration file is read, there must be some way to
determine if a particular Feature entry has been removed since the
last time the configuration file was read. The way this is done in
the features subsystem is to have a "mark" for each feature. Prior to
reading the configuration file, all marks are cleared for all features
(and all "unmark" call-backs are called). As each Feature entry is
encountered and processed, that feature's mark is set. Finally, when
the configuration file has been fully read, all remaining unmarked
features are reset to their default values (and all "mark" call-backs
are called).
Adding New Features
To add a new feature, first determine the feature's name (which must
begin with the string "FEAT_") and its type ("NONE," "INT," "BOOL," or
"STR"). Then add the feature to the enum Feature in an appropriate
place (i.e., it's good to group all features affecting operators
separate from those features affecting networking code), and a
corresponding entry in the features[] table in ircd_features.c. It
will be best to use one of the F_?() macros, which are documented
below. Then, whenever you need to refer to the value of a specific
feature, call the appropriate feature_<type>() function, as documented
below.
<enum>
enum Feature;
The "Feature" enum lists all of the features known to the feature
subsystem. Each feature name *must* begin with "FEAT_"; the portion
of the name following "FEAT_" will be what you use to set the feature
from the configuration file or with the "set" or "reset" commands.
</enum>
<function>
int feature_set(struct Client* from, const char* const* fields, int count);
The feature_set() function takes an array of strings and a count of
the number of strings in the array. The first string is a feature
name, and, for most features, the second string will be that feature's
value. The _from_ parameter is the struct Client describing the user
that issued the "set" command. This parameter may be NULL if
feature_set() is being called from the configuration file subsystem.
</function>
<function>
int feature_reset(struct Client* from, const char* const* fields, int count);
The feature_reset() function is very similar in arguments to the
feature_set() function, except that it may not be called from the
configuration file subsystem. It resets the named feature to its
default value.
</function>
<function>
int feature_get(struct Client* from, const char* const* fields, int count);
Again, feature_get() is very similar in arguments to the feature_set()
function, except that again it may not be called from the
configuration file subsystem. It reports the value of the named
feature to the user that issued the "get" command.
</function>
<function>
void feature_unmark(void);
This function is used to unmark all feature values, as described in
the subsection "Marking Features." It takes no arguments and returns
nothing.
</function>
<function>
void feature_mark(void);
The complement to feature_unmark(), feature_mark() resets all
unchanged feature settings to their defaults. See the subsection on
"Marking Features."
</function>
<function>
void feature_init(void);
This function initializes the feature interface by setting the default
values for all features correctly.
</function>
<function>
void feature_report(struct Client* to);
Reports all Feature entries to a user using RPL_STATSFLINE, except
those which the user is not permitted to see due to flag settings.
</function>
<function>
int feature_int(enum Feature feat);
To retrieve the values of integer features, call this function.
Calling this function on a different type of feature, such as a "BOOL"
feature, will result in an assertion failure.
</function>
<function>
int feature_bool(enum Feature feat);
This function is the complement of feature_int() for features of type
"BOOL."
</function>
<function>
const char *feature_str(enum Feature feat);
Use this function to retrieve strings values for features of type
"STR"; you may not modify nor free the string value.
</function>
<macro>
#define F_N(type, flags, set, reset, get, notify, unmark, mark, report)
This macro is used in the features[] table to simplify defining a
feature of type "NONE." The _type_ parameter is the name of the
feature excluding the "FEAT_" prefix, and MUST NOT be in
double-quotes. The _flags_ parameter may be 0, FEAT_OPER, or
FEAT_MYOPER--the bitwise OR of these two flags is permissible but
would not make sense. The rest of the arguments are pointers to
functions implementing the named call-back.
</macro>
<macro>
#define F_I(type, flags, v_int, notify)
To define integer features, use the F_I() macro. The _type_ and
_flags_ parameters are as for F_N(), and the _v_int_ parameter
specifies the default value of the feature. The _notify_ parameter,
if non-zero, will be called whenever the value of the feature changes.
</macro>
<macro>
#define F_B(type, flags, v_int, notify)
This macro is used for defining features of type "BOOL"; it is very
similar to F_I(), but _v_int_ should either 0 (for a "FALSE" value) or
1 (for a "TRUE" value). The _notify_ parameter, if non-zero, will be
called whenever the value of the feature changes.
</macro>
<macro>
#define F_S(type, flags, v_str, notify)
Also similar to F_I(), F_S() defines features of type "STR." The
_flags_ argument may be the bitwise OR of one of FEAT_OPER or
FEAT_MYOPER with the special string flags FEAT_NULL and FEAT_CASE,
which are described above in the section "Feature Flags." The
_notify_ parameter, if non-zero, will be called whenever the value of
the feature changes. Note that FEAT_NULL *must* be set if the default
string _v_str_ is set to NULL.
</macro>
<authors>
Kev <klmitch@mit.edu>
</authors>
<changelog>
[2001-06-13 Kev] Mention notify with the other callbacks
[2001-01-02 Kev] Add documentation for new flags and for the notify
mechanism
[2000-12-18 Kev] Document the features API
</changelog>
+283
View File
@@ -0,0 +1,283 @@
Some users can be very annoying, as any IRC operator can attest. Some
can in fact be downright abusive. Sometimes the best way of dealing
with these users is to ban them from the entire network. The G-line
system permits this.
G-lines are fairly complicated. A G-line can be active or inactive,
either locally or globally. It can be a purely local G-line, or
global. It could be based on IP address or on host name. In short,
there are many variations on the basic G-line. Worse, there is also
the concept of a "bad channel," or BADCHAN, that has been tacked onto
the G-line subsystem, when it should have been a separate command in
the first place.
Different types of G-lines are differentiated from each other through
the use of various flags. Some of these flags are maintained solely
by the G-line subsystem, where as others are passed to various
functions in the API.
<macro>
#define GLINE_MAX_EXPIRE 604800 /* max expire: 7 days */
This macro lists the maximum expire time a G-line is permitted to
have. This value is limited to 7 days to prevent abuse of the system.
</macro>
<macro>
#define GLINE_ACTIVE 0x0001
This flag is used to indicate that a given G-line is globally active.
</macro>
<macro>
#define GLINE_IPMASK 0x0002
This flag is used to indicate that a given G-line is an IP mask. This
flag is maintained internally by the G-line subsystem.
</macro>
<macro>
#define GLINE_BADCHAN 0x0004
This flag is used to indicate that a given G-line specifies a BADCHAN,
a channel that users are not permitted to join. This flag is
maintained internally, but is also used in gline_find() to search for
a BADCHAN for a particular channel.
</macro>
<macro>
#define GLINE_LOCAL 0x0008
This flag is used to indicate that a given G-line is a local G-line.
Local G-lines do not affect users on other servers.
</macro>
<macro>
#define GLINE_ANY 0x0010
This flag is passed to gline_find() to signal that function to return
any G-line or BADCHAN that matches the passed mask string. It is
never set on a real G-line.
</macro>
<macro>
#define GLINE_FORCE 0x0020
This flag is passed to gline_add() to force the server to accept an
expire time that might be out of bounds. It is never set on a real
G-line.
</macro>
<macro>
#define GLINE_EXACT 0x0040
This flag is passed to gline_find() to signal that function to return
only G-lines that exactly match the passed mask string. That is, the
ircd_strcmp() function is called to compare the G-line to the mask,
rather than the match() function. This flag is never set on a real
G-line.
</macro>
<macro>
#define GLINE_LDEACT 0x0080 /* locally deactivated */
This flag is set on global G-lines that have been locally
deactivated. This flag is maintained internally by the G-line
subsystem.
</macro>
<macro>
#define GLINE_GLOBAL 0x0100 /* find only global glines */
This flag is passed to gline_find() or gline_lookup() to specify that
the caller is only interested in global G-lines. This flag is never
set on a real G-line.
</macro>
<macro>
#define GLINE_LASTMOD 0x0200 /* find only glines with non-zero lastmod */
This flag is passed to gline_find() or gline_lookup() to specify that
the caller is only interested in G-lines with a non-zero lastmod time,
that is, G-lines that were not set by a U-lined service. This flag is
never set on a real G-line.
</macro>
<struct>
struct Gline;
The struct Gline describes everything about a given G-line. None of
its fields may be directly accessed by the application; use the
functions and macros described below instead.
</struct>
<function>
int GlineIsActive(struct Gline* g);
This macro returns a non-zero value if the G-line is active, or 0
otherwise. If a G-line is locally deactivated, this macro will always
return 0.
</function>
<function>
int GlineIsRemActive(struct Gline* g);
This macro returns a non-zero value if the G-line is active, ignoring
whether or not it is locally deactivated.
</function>
<function>
int GlineIsIpMask(struct Gline* g);
This macro returns a non-zero value if the G-line is an IP mask.
</function>
<function>
int GlineIsBadChan(struct Gline* g);
This macro returns a non-zero value if a G-line actually represents a
BADCHAN.
</function>
<function>
int GlineIsLocal(struct Gline* g);
This macro returns a non-zero value if a G-line is local only.
</function>
<function>
char* GlineUser(struct Gline* g);
This macro returns the user name associated with the G-line. If the
G-line represents a BADCHAN, this will contain the channel name.
</function>
<function>
char* GlineHost(struct Gline* g);
This macro returns the host name associated with the G-line. If the
G-line represents a BADCHAN, this will be a NULL pointer.
</function>
<function>
char* GlineReason(struct Gline* g);
This macro returns the reason that was given when the G-line was set.
</function>
<function>
time_t GlineLastMod(struct Gline* g);
G-lines that were not set by a U-lined service have a modification
time that must be monotonically increasing. This macro simply returns
that modification time.
</function>
<function>
int gline_propagate(struct Client *cptr, struct Client *sptr,
struct Gline *gline);
When a global G-line is set or modified, all other servers must be
notified of the new G-line. This function takes care of propagating
the G-line specified by _gline_, originated by the client _sptr_, to
all servers except _cptr_ (which may be a NULL pointer).
</function>
<function>
int gline_add(struct Client *cptr, struct Client *sptr, char *userhost,
char *reason, time_t expire, time_t lastmod, unsigned int flags);
This function simply adds a G-line, set by _sptr_ and with a
_userhost_, _reason_, _expire_, and _lastmod_ as specified. The
_flags_ parameter is a bit mask consisting of the binary OR of
GLINE_FORCE, GLINE_LOCAL, or GLINE_ACTIVE, as appropriate. The
gline_add() function also calls gline_propagate() to propagate the
G-line, and kills off any local users matching the G-line if it is
active.
</function>
<function>
int gline_activate(struct Client *cptr, struct Client *sptr,
struct Gline *gline, time_t lastmod, unsigned int flags);
This function activates the G-line specified by _gline_, setting its
_lastmod_ time as specified. If _flags_ is GLINE_LOCAL and if the
G-line is locally deactivated, this function will turn off the local
deactivation flag, but will not modify _lastmod_. If the G-line is
globally deactivated, passing this function the GLINE_LOCAL flag will
have no effect.
</function>
<function>
int gline_deactivate(struct Client *cptr, struct Client *sptr,
struct Gline *gline, time_t lastmod, unsigned int flags);
This function is similar to gline_activate() except that it
deactivates the G-line. If the given G-line is local, or if it was
set by a U-lined service (and GLINE_LOCAL was not passed via _flags_),
then the G-line is deleted from memory. In all other cases, the
G-line is simply deactivated, either locally (if GLINE_LOCAL was
passed via _flags_) or globally. Global deactivation will update the
_lastmod_ time.
</function>
<function>
struct Gline *gline_find(char *userhost, unsigned int flags);
This function looks up a G-line matching the given _userhost_ value,
under control of the _flags_ parameter. Valid _flags_ that may be
passed are: GLINE_BADCHAN, GLINE_ANY, GLINE_GLOBAL, GLINE_LASTMOD, or
GLINE_EXACT, each described above.
</function>
<function>
struct Gline *gline_lookup(struct Client *cptr, unsigned int flags);
This function looks up a G-line matching the given client, specified
by _cptr_, under the control of the _flags_. Valid values for _flags_
are GLINE_GLOBAL and GLINE_LASTMOD, as described above.
</function>
<function>
void gline_free(struct Gline *gline);
This function releases all storage associated with a given G-line.
</function>
<function>
void gline_burst(struct Client *cptr);
This function generates a burst of all existing global G-lines and
BADCHANs and sends them to the server specified by _cptr_.
</function>
<function>
int gline_resend(struct Client *cptr, struct Gline *gline);
This function resends the _gline_ to a server specified by _cptr_.
This may be used if, for instance, it is discovered that a server is
not synchronized with respect to a particular G-line.
</function>
<function>
int gline_list(struct Client *sptr, char *userhost);
This function sends the information about a G-line matching _userhost_
to the client specified by _sptr_. If _userhost_ is a NULL pointer, a
list of all G-lines is sent.
</function>
<function>
void gline_stats(struct Client *sptr);
This function generates a list of all G-lines, sending them to the
user _sptr_ by a /STATS G response.
</function>
<authors>
Kev <klmitch@mit.edu>
</authors>
<changelog>
[2001-6-15 Kev] Initial documentation for the G-line API.
</changelog>
+268
View File
@@ -0,0 +1,268 @@
These functions are intended to be a complete replacement for sprintf
and sprintf_irc. They are a (nearly) complete reimplementation, and
of course they're snprintf clones, making it more difficult for
accidental buffer overflows to crop up.
First off, what's missing? These functions support all ANSI C
conversion specifiers and selected ones from ISO 9x, with the
exception of all floating-point conversions. The floating-point
conversions are tricky, and will likely be dependent on the
representation of a floating-point number on a particular
architecture. While that representation is likely to conform to some
standard, it is not currently used in ircu, so seemed like a good
thing to omit, given the difficulty of implementing it.
There are two more things missing from this implementation that would
be required by ANSI; the first is support for multibyte character
strings, and the second is support for locales, neither of which have
any relevance for ircu, so again omission seemed to be a good policy.
Additionally, %#x always causes '0x' (or '0X') to be printed, even if
the number is zero.
These functions also have some extensions not seen in a
standards-compliant implementation; technically, the ISO 9x extensions
fall into this category, for instance. The ISO 9x extensions
supported are type extensions--%ju, %tu, and %zu, for instance; %qu
and %hhu are also supported. The extensions added for use in ircu are
%Tu, which takes a time_t, and the new %C conversion, which inserts
either a numeric or a nick, dependent on the <dest> parameter. The
GNU %m extension, which inserts the strerror() string corresponding to
the current value of errno, is also supported, as is a special %v
extension, which essentially does a recursive call to ircd_snprintf.
The following description is descended from the Linux man page for the
printf family of functions.
The format string is composed of zero or more directives: ordinary
characters (not %), which are copied unchanged to the output stream;
and conversion specifications, each of which results in fetching zero
or more subsequent arguments. Each conversion specification is
introduced by the character %. The arguments must correspond properly
(after type promotion) with the conversion specifier. After the %,
the following appear in sequence:
* Zero or more of the following flags:
# specifying that the value should be converted to an "alternate
form." For c, d, i, n, p, s, and u conversions, this option
has no effect. For o conversions, the precision of the number
is increased to force the first character of the output string
to a zero (except if a zero value is printed with an explicit
precision of zero). For x and X conversions, the string '0x'
(or '0X' for X conversions) is prepended to it. For e, E, f,
g, and G conversions, the result will always contain a decimal
point, even if no digits follow it (normally, a decimal point
appears in the results of those conversions only if a digit
follows). For g and G conversions, trailing zeros are not
removed from the result as they would otherwise be. For C
conversions, if the destination is local and the origin is a
user, the nick!user@host form is used.
0 specifying zero padding. For all conversions except n, the
converted value is padded on the left with zeros rather than
blanks. If a precision is given with a numeric conversion (d,
i, o, u, i, x, and X), the 0 flag is ignored.
- (a negative field width flag) indicates the converted value is
to be left adjusted on the field boundary. Except for n
conversions, the converted value is padded on the right with
blanks, rather than on the left with blanks or zeros. A -
overrides a 0 if both are given.
' ' (a space) specifying that a blank should be left before a
positive number produced by a signed conversion (d, e, E, f,
g, G, or i).
+ specifying that a sign always be placed before a number
produced by a signed conversion. A + overrides a space if
both are used.
: specifying that a struct Client name should be preceded by a
':' character if the destination is a user
* An optional decimal digit string specifying a minimum field width.
If the converted value has fewer characters than the field width, it
will be padded with spaces on the left (or right, if the
left-adjustment flag has been given) to fill out the field width.
* An optional precision, in the form of a period (`.') followed by an
optional digit string. If the digit string is omitted, the
precision is taken as zero. This gives the minimum number of digits
to appear for d, i, o, u, x, and X conversions, the number of digits
to appear after the decimal-point for e, E, and f conversions, the
maximum number of significant digits for g and G conversions, or the
maximum number of characters to be printed from a string for s
conversions.
* The optional character h, specifying that a following d, i, o, u, x,
or X conversion corresponds to a short int or unsigned short int
argument, or that a following n conversion corresponds to a pointer
to a short int argument. If the h character is given again, char is
used instead of short int.
* The optional character l (ell) specifying that a following d, i, o,
u, x, or X conversion applies to a pointer to a long int or unsigned
long int argument, or that a following n conversion corresponds to a
pointer to a long int argument.
* The character L specifying that a following e, E, f, g, or G
conversion corresponds to a long double argument, or a following d,
i, o, u, x, or X conversion corresponds to a long long argument.
Note that long long is not specified in ANSI C and therefore not
portable to all architectures.
* The optional character q. This is equivalent to L.
* A j character specifying that the following integer (d, i, o, u, x,
or X) conversion corresponds to an intmax_t argument.
* A t character specifying that the following integer (d, i, o, u, x,
or X) conversion corresponds to a ptrdiff_t argument.
* A z character specifying that the following integer (d, i, o, u, x,
or X) conversion corresponds to a size_t argument.
* A T character specifying that the following integer (d, i, o, u, x,
or X) conversion corresponds to a time_t argument.
* A character that specifies the type of conversion to be applied.
A field width or precision, or both, may be indicated by an asterisk
`*' instead of a digit string. In this case, an int argument supplies
the field width or precision. A negative field width is treated as a
left adjustment flag followed by a positive field width; a negative
precision is treated as though it were missing.
The conversion specifiers and their meanings are:
diouxX The int (or appropriate variant) argument is converted
to signed decimal (d and i), unsigned octal (o),
unsigned decimal (u), or unsigned hexadecimal (x and
X) notation. The letters abcdef are used for x
conversions; the letters ABCDEF are used for X
conversions. The precision, if any, gives the minimum
number of digits that must appear; if the converted
value requires fewer digits, it is padded on the left
with zeros.
eE [NOT IMPLEMENTED] The double argument is rounded and
converted in the style [-]d.dddedd where there is one
digit before the decimal-point character and the
number of digits after it is equal to the precision;
if the precision is missing, it is taken as 6; if the
precision is zero, no decimal-point character
appears. An E conversion uses the letter E (rather
than e) to introduce the exponent. The exponent
always contains at least two digits; if the value is
zero, the exponent is 00.
f [NOT IMPLEMENTED] The double argument is rounded and
converted to decimal notation in the style
[-]ddd.ddd, where the number of digits after the
decimal-point character is equal to the precision
specification. If the precision is missing, it is
taken as 6; if the precision is explicitly zero, no
decimal-point character appears. If a decimal point
appears, at least one digit appears before it.
g [NOT IMPLEMENTED] The double argument is converted in
style f or e (or E for G conversions). The precision
specifies the number of significant digits. If the
precision is missing, 6 digits are given; if the
precision is zero, it is treated as 1. Style e is
used if the exponent from its conversion is less than
-4 or greater than or equal to the precision.
Trailing zeros are removed from the fractional part of
the result; a decimal point appears only if it is
followed by at least one digit.
c The int argument is converted to an unsigned char, and
the resulting character is written.
s The "char *" argument is expected to be a pointer to
an array of character type (pointer to a string).
Characters from the array are written up to (but not
including) a terminating NUL character; if a precision
is specified, no more than the number specified are
written. If a precision is given, no null character
need be present; if the precision is not specified, or
is greater than the size of the array, the array must
contain a terminating NUL character.
p The "void *" pointer argument is printed in
hexadecimal (as if by %#x or %#lx).
n The number of characters written so far is stored into
the integer indicated by the ``int *'' (or variant)
pointer argument. No argument is converted.
m The error message associated with the current value of
errno is printed as if by %s.
C The client argument identifier is printed under the
control of the <dest> argument; if <dest> is NULL or
is a user, the client's name (nickname or server name)
is printed; otherwise, the client's network numeric is
printed.
H The channel argument identifier (channel name) is
printed.
v The argument given must be a pointer to a struct
VarData with vd_format and vd_args must be initialized
appropriately. On return, vd_chars will contain the
number of characters added to the buffer, and
vd_overflow will contain the number of characters that
could not be added due to buffer overflow or due to a
precision.
% A `%' is written. No argument is converted. The
complete conversion specification is `%%'.
In no case does a non-existent or small field width cause truncation
of a field; if the result of a conversion is wider than the field
width, the field is expanded to contain the conversion result.
<struct>
struct VarData {
size_t vd_chars; /* number of characters inserted */
size_t vd_overflow; /* number of characters that couldn't be */
const char *vd_format; /* format string */
va_list vd_args; /* arguments for %v */
};
This structure is used by the %v conversion specification. The
_vd_format_ element must contain a format string, and the _vd_args_
element must be a variable argument list. Upon return from
ircd_snprintf() or ircd_vsnprintf(), the _vd_chars_ element will
contain the number of characters that were able to be inserted, and
the _vd_overflow_ element will contain the number of characters that
could not be inserted.
</struct>
<function>
int ircd_snprintf(struct Client *dest, char *buf, size_t buf_len,
const char *format, ...);
This formats the argument list, under control of the _format_, into
the buffer specified by _buf_, the size of which is specified by
_buf_len_. The _dest_ parameter is used to determine whether to use a
numeric or a nickname for %C conversions.
</function>
<function>
int ircd_vsnprintf(struct Client *dest, char *buf, size_t buf_len,
const char *format, va_list args);
This function is identical to the ircd_snprintf() function except for
the variable argument list given by _args_.
</function>
<authors>
Kev <klmitch@mit.edu>
</authors>
<changelog>
[2001-6-15 Kev] Initial documentation of the ircd_snprintf family of
functions.
</changelog>
+92
View File
@@ -0,0 +1,92 @@
IRC wouldn't be of much interest without the ability for users to join
channels. Of course, they must also be able to leave those channels
when they get bored of the conversation there. Users can join or
leave multiple channels at once. Sometimes these JOIN and PART
messages can be ganged together into a single message. This is
facilitated by the JoinBuf system.
<struct>
struct JoinBuf;
This structure is used to accumulate and describe several channel
joins or parts. None of its fields are directly or indirectly
accessible to the application; a struct JoinBuf is only suitable for
passing to the joinbuf_*() suite of functions. JoinBuf structures
must be allocated by the caller.
</struct>
<macro>
#define JOINBUF_TYPE_JOIN 0 /* send JOINs */
This macro tells joinbuf_init() that the JoinBuf is being used to
generate several channel joins.
</macro>
<macro>
#define JOINBUF_TYPE_CREATE 1 /* send CREATEs */
This macro tells joinbuf_init() that the JoinBuf is being used to
generate several channel creations.
</macro>
<macro>
#define JOINBUF_TYPE_PART 2 /* send PARTs */
This macro tells joinbuf_init() that the JoinBuf is being used to
generate several channel parts.
</macro>
<macro>
#define JOINBUF_TYPE_PARTALL 3 /* send local PARTs, but not remote */
This macro tells joinbuf_init() that the JoinBuf is being used to
record PARTs for all the user's channels. That fact is communicated
to servers through a more efficient means than sending several PARTs,
but local clients can only be made aware of it with standard PART
messages.
</macro>
<function>
void joinbuf_init(struct JoinBuf *jbuf, struct Client *source,
struct Client *connect, unsigned int type, char *comment,
time_t create);
This function is used to initialize a caller allocated JoinBuf,
specified by _jbuf_. The originating user is specified by _source_;
the connection on which the message was received is specified by
_connect_; the type (one of the JOINBUF_TYPE_* macros described above)
is specified by _type_. PART messages may have an optional comment,
which is passed through the _comment_ parameter. JOIN and CREATE
messages require a timestamp, passed through the _create_ parameter.
</function>
<function>
void joinbuf_join(struct JoinBuf *jbuf, struct Channel *chan,
unsigned int flags);
This function adds a channel to the JoinBuf. The _chan_ parameter
specifies the channel, and may only be NULL if the JoinBuf type is
JOINBUF_TYPE_JOIN--this will cause a "JOIN 0" message to be sent to
all servers. The _flags_ parameter is used to specify the user's
current channel flags. For JOINBUF_TYPE_PART and JOINBUF_TYPE_PARTALL
JoinBufs, passing CHFL_ZOMBIE will inhibit sending the PART to all
channel users, and CHFL_BANNED will inhibit sending the user's
specified PART comment. For JOINBUF_TYPE_JOIN or JOINBUF_TYPE_CREATE
JoinBufs, the _flags_ parameter is used to set the initial channel
modes for the user.
</function>
<function>
int joinbuf_flush(struct JoinBuf *jbuf);
This function simply flushes the contents of the struct JoinBuf to the
appropriate destinations.
</function>
<authors>
Kev <klmitch@mit.edu>
</authors>
<changelog>
[2001-6-15 Kev] Initial documentation of the JoinBuf subsystem.
</changelog>
+161
View File
@@ -0,0 +1,161 @@
Occasionally, a server will become incorrectly configured or will
start behaving incorrectly. Even more rarely, a server will be
compromised, and a modified version of the server put in place to
cause problems. These cases are the reason for the _jupe_, a
temporary server ban. This is similar to the G-line, which is a
temporary user ban, and indeed, the jupe API is very similar to the
G-line API.
<macro>
#define JUPE_MAX_EXPIRE 604800 /* max expire: 7 days */
This macro lists the maximum expire time a jupe is permitted to have.
This value is limited to 7 days to prevent abuse of the system.
</macro>
<macro>
#define JUPE_ACTIVE 0x0001
This flag is used to indicate that a given jupe is globally active.
</macro>
<macro>
#define JUPE_LOCAL 0x0002
This flag is used to indicate that a given jupe is a local one. Local
jupes do not affect users on other servers.
</macro>
<macro>
#define JUPE_LDEACT 0x0004 /* locally deactivated */
This flag is set on global jupes that have been locally deactivated.
This flag is maintained internally by the jupe subsystem.
</macro>
<struct>
struct Jupe;
The struct Jupe describes everything about a given jupe. None of its
fields may be directly accessed by the application; use the functions
and macros described below instead.
</struct>
<function>
int JupeIsActive(struct Jupe* j);
This macro returns a non-zero value if the jupe is active, or 0
otherwise. If a jupe is locally deactivated, this macro will always
return 0.
</function>
<function>
int JupeIsRemActive(struct Jupe* j);
This macro returns a non-zero value if the jupe is active, ignoring
whether or not it is locally deactivated.
</function>
<function>
int JupeIsLocal(struct Jupe* j);
This macro returns a non-zero value if the jupe is local only.
</function>
<function>
char* JupeServer(struct Jupe* j);
This macro returns the server name associated with the jupe.
</function>
<function>
char* JupeReason(struct Jupe* j);
This macro returns the reason that was given when the jupe was set.
</function>
<function>
time_t JupeLastMod(struct Jupe* j);
Jupes have a modification time that must be monotonically increasing.
This macro simply returns that modification time.
</function>
<function>
int jupe_add(struct Client *cptr, struct Client *sptr, char *server,
char *reason, time_t expire, time_t lastmod, unsigned int flags);
This function simply adds a jupe, set by _sptr_ and with a _server_,
_reason_, _expire_, and _lastmod_ as specified. The _flags_ parameter
is a bit mask consisting of the binary OR of JUPE_LOCAL and
JUPE_ACTIVE, as appropriate. The jupe_add() function will propagate
the jupe to all servers (assuming JUPE_LOCAL was not passed), and will
break its link to the server specified by _server_ (assuming that the
JUPE_ACTIVE flag _was_ passed).
</function>
<function>
int jupe_activate(struct Client *cptr, struct Client *sptr, struct Jupe *jupe,
time_t lastmod, unsigned int flags);
This function activates the jupe specified by _jupe_, setting its
_lastmod_ time as specified. If _flags_ is JUPE_LOCAL and if the jupe
is locally deactivated, this function will turn off the local
deactivation flag, but will not modify _lastmod_. If the jupe is
globally deactivated, passing this function the JUPE_LOCAL flag will
have no effect.
</function>
<function>
int jupe_deactivate(struct Client *cptr, struct Client *sptr,
struct Jupe *jupe, time_t lastmod, unsigned int flags);
This function is similar to jupe_activate() except that it deactivates
the jupe. If the given jupe is local, then the jupe is deleted from
memory. In all other cases, the jupe is simply deactivated, either
locally (if JUPE_LOCAL was passed via _flags_) or globally. Global
deactivation will update the _lastmod_ time.
</function>
<function>
struct Jupe* jupe_find(char *server);
This function searches for a jupe matching the given _server_.
</function>
<function>
void jupe_free(struct Jupe *jupe);
This function releases all storage associated with a given jupe.
</function>
<function>
void jupe_burst(struct Client *cptr);
This function generates a burst of all existing global jupes and sends
them to the server specified by _cptr_.
</function>
<function>
int jupe_resend(struct Client *cptr, struct Jupe *jupe);
This function resends the _jupe_ to a server specified by _cptr_.
This may be used if, for instance, it is discovered that a server is
not synchronized with respect to a particular jupe.
</function>
<function>
int jupe_list(struct Client *sptr, char *server);
This function sends the information about a jupe matching _server_ to
the client specified by _sptr_. If _server_ is a NULL pointer, a list
of all jupes is sent.
</function>
<authors>
Kev <klmitch@mit.edu>
</authors>
<changelog>
[2001-6-15 Kev] Initial documentation of the jupe API.
</changelog>
+240
View File
@@ -0,0 +1,240 @@
Old versions of ircu did not have very good means of dealing with
logging. In u2.10.11, an entirely new logging subsystem was written,
allowing a server administrator much more power in determining what
actions are to be logged where. The new logging subsystem permits log
messages to go to syslog, to a file, and to server operators via
server notices, simultaneously (though having output to multiple log
files is not presently supported).
All log messages have two values that are passed in with them: the
logging level, which must be one of the values in enum LogLevel, and a
logging subsystem, which must be one of the values in enum LogSys;
these values are used as indexes into arrays within ircd_log.c, so be
careful should you change them.
In addition to the LogLevel and LogSys, there is also a set of three
flags that may be passed to the log_write() logging function; these
flags may be used to suppress certain types of logging that may be
undesirable. For instance, when a server links, a log may be written
containing the server's IP address; to prevent this IP address from
ever showing up in a server notice, that invocation of log_write() is
passed the LOG_NOSNOTICE flag.
<enum>
enum LogLevel {
L_CRIT,
L_ERROR,
L_WARNING,
L_NOTICE,
L_TRACE,
L_INFO,
L_DEBUG,
L_LAST_LEVEL
};
This enum describes the severity levels of a log message. The
severity decreases as you proceed downwards in the list, so L_DEBUG is
less severe than L_INFO, and L_CRIT in the most severe of all. The
special value L_LAST_LEVEL should never be used; it merely marks the
end of the list.
</enum>
<enum>
enum LogSys {
LS_SYSTEM, LS_CONFIG, LS_OPERMODE, LS_GLINE, LS_JUPE, LS_WHO, LS_NETWORK,
LS_OPERKILL, LS_SERVKILL, LS_USER, LS_OPER, LS_RESOLVER, LS_SOCKET,
LS_DEBUG, LS_OLDLOG,
LS_LAST_SYSTEM
};
These are the various logging subsystems recognized by the logging
subsystem. Again, order is important, and again, LS_LAST_SYSTEM
should never be used.
</enum>
<function>
void log_debug_init(int usetty);
This initializes the special-purpose debug logging code in the
server. If the _usetty_ parameter is non-zero, then all debugging
output will go to the terminal regardless of file settings for the
LS_DEBUG subsystem. This function is not defined unless the server is
compiled with -DDEBUGMODE.
</function>
<function>
void log_init(const char *process_name);
This initializes the entire logging subsystem, including special
things such as storing the process name and opening syslog with the
open_log() function. It may only be called once.
</function>
<function>
void log_reopen(void);
All log files are persistently open, in order to avoid the overhead of
re-opening the log file each time. This function is used to close all
the log files and to close and reopen syslog. (Log files are opened
again only when there is something to write to them.)
</function>
<function>
void log_close(void);
This closes all log files and the syslog prior to the server
terminating. Should logs need to be reopened after calling this
function, call log_reopen() instead of log_init().
</function>
<function>
void log_write(enum LogSys subsys, enum LogLevel severity,
unsigned int flags, const char *fmt, ...);
This is the actual logging function. The _flags_ parameter is 0 or
the bitwise OR of LOG_NOSYSLOG (suppresses syslogging), LOG_NOFILELOG
(suppresses logging to a file) and LOG_NOSNOTICE (suppresses logging
via server notices). The _fmt_ parameter is a format string
acceptable to ircd_snprintf(), which is the function called to
actually format the log message.
</function>
<function>
void log_vwrite(enum LogSys subsys, enum LogLevel severity,
unsigned int flags, const char *fmt, va_list vl);
This is similar to log_write() except that it takes a va_list
parameter.
</function>
<function>
char *log_cannon(const char *subsys);
This returns the canonical name for logging subsystem. This probably
should not be exposed here, but it is needed in ircd_features.c at
present.
</function>
<function>
int log_set_file(const char *subsys, const char *filename);
This sets the file name for the specified logging subsystem to
_filename_; returns 2 if the subsystem was undefined, 1 if the value
of _filename_ was not understood, or 0 if there was no error.
</function>
<function>
char *log_get_file(const char *subsys);
This returns the current log file name for the given subsystem.
</function>
<function>
int log_set_facility(const char *subsys, const char *facility);
This sets the syslog facility for the specified logging subsystem to
_facility_; returns 2 if the subsystem was undefined, 1 if the value
of _facility_ was not understood, or 0 if there was no error. Two
special facility names may be given; "NONE" specifies that no
syslogging should be performed, and "DEFAULT" specifies that ircd's
default syslog facility should be used.
</function>
<function>
char *log_get_facility(const char *subsys);
This returns the current syslog facility for the given subsystem. See
the documentation for log_set_facility() for a description of the
special facility names "NONE" and "DEFAULT."
</function>
<function>
int log_set_snomask(const char *subsys, const char *snomask);
This sets the server notice type for the specified logging subsystem
to _snomask_; returns 2 if the subsystem was undefined, 1 if the value
of _snomask_ was not understood, or 0 if there was no error. The
special server notice type "NONE" indicates that no server notices
should be generated. The other valid values for _snomask_ are:
"OLDSNO," "SERVKILL," "OPERKILL," "HACK2," "HACK3," "UNAUTH,"
"TCPCOMMON," "TOOMANY," "HACK4," "GLINE," "NETWORK," "IPMISMATCH,"
"THROTTLE," "OLDREALOP," "CONNEXIT," and "DEBUG."
</function>
<function>
char *log_get_snomask(const char *subsys);
This returns the current server notice type for the given subsystem.
See the documentation for log_set_snomask() for a description of the
return values.
</function>
<function>
int log_set_level(const char *subsys, const char *level);
This function is used to set the minimum log level for a particular
subsystem; returns 2 if the subsystem was undefined, 1 if the value of
_level_ was not understood, or 0 if there was no error. Any log
notices generated with lower severity than that set with this function
will not be logged. Valid values are "CRIT," "ERROR," "WARNING,"
"NOTICE," "TRACE," "INFO," and "DEBUG."
</function>
<function>
char *log_get_level(const char *subsys);
This returns the current minimum log level for the given subsystem.
See the documentation for log_set_level() for a description of the
return values.
</function>
<function>
int log_set_default(const char *facility);
This function sets the default syslog facility for all of ircd. Valid
values for _facility_ are as described for log_set_facility() with the
exclusion of the "NONE" and "DEFAULT" facilities; returns 1 if the
facility name was unrecognized (or proscribed) or 0 if there was no
error.
</function>
<function>
char *log_get_default(void);
This simply returns ircd's default syslog facility.
</function>
<function>
void log_feature_unmark(void);
This function is called by the ircd_features.c subsystem and should
not be called by any other part of ircd. See the features API
documentation for notes on what this function does.
</function>
<function>
void log_feature_mark(int flag);
This function is called by the ircd_features.c subsystem and should
not be called by any other part of ircd. See the features API
documentation for notes on what this function does.
</function>
<function>
void log_feature_report(struct Client *to, int flag);
This function is called by the ircd_features.c subsystem and should
not be called by any other part of ircd. See the features API
documentation for notes on what this function does.
</function>
<authors>
Kev <klmitch@mit.edu>
</authors>
<changelog>
[2001-06-13 Kev] Fix a minor typo.
[2000-12-18 Kev] Wrote some documentation on how to use the logging
subsystem.
</changelog>
+282
View File
@@ -0,0 +1,282 @@
Generating and parsing channel mode strings is often a very
complicated process. The ModeBuf interface, along with the associated
mode parsing functions, attempt to make this much more programmatic.
The interface to the functions in this suite is itself very
complicated, unfortunately, though most of the complication is in the
effects of various flags on the operation of the functions.
<struct>
struct ModeBuf;
This structure is used to accumulate and describe several mode
changes. None of its fields are directly or indirectly accessible to
the application; a struct ModeBuf is only suitable for passing to the
modebuf_*() suite of functions. ModeBuf structures must be allocated
by the caller.
</struct>
<function>
void modebuf_init(struct ModeBuf *mbuf, struct Client *source,
struct Client *connect, struct Channel *chan,
unsigned int dest);
This function initializes a caller-allocated ModeBuf, _mbuf_, with the
given parameters. If the mode should not be sent to a particular
server, perhaps because it was received from that server, that server
should be specified by the _connect_ parameter. The channel the mode
change will take place on is given by the _chan_ parameter, and the
disposition of the mode is given by the _dest_ parameter, which is the
binary OR of the MODEBUF_DEST_* flags described below.
</function>
<macro>
#define MODEBUF_DEST_CHANNEL 0x0001 /* Mode is flushed to channel */
This flag, when set in a call to modebuf_init(), causes the accumulated
mode change to be sent to the channel (in client<->server protocol, of
course).
</macro>
<macro>
#define MODEBUF_DEST_SERVER 0x0002 /* Mode is flushed to server */
If other servers should be made aware of the mode change, this flag
should be passed to modebuf_init(). One time when the mode change may
not be passed is when processing the mode in a BURST message.
</macro>
<macro>
#define MODEBUF_DEST_OPMODE 0x0100 /* Send server mode as OPMODE */
This flag is used to tell the modebuf_*() suite to send an OPMODE
message to other servers, rather than an ordinary MODE message.
</macro>
<macro>
#define MODEBUF_DEST_DEOP 0x0200 /* Deop the offender */
When bouncing a mode change, giving this flag to modebuf_init() causes
the originating user to be deopped on the channel as part of the mode
bounce.
</macro>
<macro>
#define MODEBUF_DEST_BOUNCE 0x0400 /* Bounce the modes */
When a mode change is illegitimate, that is, when it originates from a
user that is not (as far as this server knows) a channel operator, the
mode change should be bounced. This involves reversing the sense of
the mode and sending it back to the originating server. This flag is
used to tell the modebuf_*() suite to do just that.
</macro>
<macro>
#define MODEBUF_DEST_LOG 0x0800 /* Log the mode changes to OPATH */
The OPMODE command is reserved for IRC operators. When it is used,
the server should log the command for accountability purposes. This
flag, given to modebuf_init(), will cause the ModeBuf system to log
the exact mode change to a log file.
</macro>
<macro>
#define MODEBUF_DEST_HACK2 0x2000 /* Send a HACK(2) notice, reverse */
When a remote user that this server does not think is a channel
operator proceeds to change a channel mode, that mode must be
bounced. In addition, in order to provide some debugging capability,
a server notice may be sent, called a "HACK(2)" notice. Passing
modebuf_init() this flag causes that notice to be sent.
</macro>
<macro>
#define MODEBUF_DEST_HACK3 0x4000 /* Send a HACK(3) notice, TS == 0 */
When the origin of a mode change is a server, we should always accept
the mode change. To provide accountability, however, a server notice
should be sent. This flag will cause the server to generate a
"HACK(3)" notice.
</macro>
<macro>
#define MODEBUF_DEST_HACK4 0x8000 /* Send a HACK(4) notice, TS == 0 */
Some servers are special. When a server that has a Uworld entry
issues a mode change, we send a "HACK(4)" message to differentiate it
from an ordinary server changing a channel mode. This is the flag
that must be passed to modebuf_init() to cause that behavior.
</macro>
<function>
void modebuf_mode(struct ModeBuf *mbuf, unsigned int mode);
Certain channel modes take no arguments. Those mode changes can be
fed to the ModeBuf system using modebuf_mode(). The _mode_ parameter
is a bit mask of the mode changes, and must have one of MODE_ADD or
MODE_DEL set.
</function>
<function>
void modebuf_mode_uint(struct ModeBuf *mbuf, unsigned int mode,
unsigned int uint);
One channel mode, the "limit" mode ("+l"), takes a single integer
argument. This limit can be fed to the ModeBuf system with the
modebuf_mode_uint() function. The _mode_ parameter must be the binary
OR of one of MODE_ADD or MODE_DEL with the MODE_LIMIT flag. The
_uint_ parameter specifies the limit.
</function>
<function>
void modebuf_mode_string(struct ModeBuf *mbuf, unsigned int mode,
char *string, int free);
Some channel modes take a string parameter. These can be fed to
ModeBuf with modebuf_mode_string(). The _mode_ parameter should be
the binary OR of one of MODE_ADD or MODE_DEL with the flag for the
mode. The _string_ parameter specifies the string, and the _free_
parameter indicates whether the ModeBuf system should call MyFree() on
the string once it is done with it.
</function>
<function>
void modebuf_mode_client(struct ModeBuf *mbuf, unsigned int mode,
struct Client *client);
The remaining channel modes take a parameter specifying a client.
These can be fed to ModeBuf with modebuf_mode_client(). The _mode_
parameter should be the binary OR of one of MODE_ADD or MODE_DEL with
the flag for the mode. The _client_ parameter should be a pointer to
a struct Client specifying which client the mode is supposed to act
upon.
</function>
<function>
int modebuf_flush(struct ModeBuf *mbuf);
This function simply flushes the contents of the struct ModeBuf
specified by _mbuf_ to the appropriate destinations, as was specified
by the _dest_ parameter in the call to modebuf_init(). This function
returns 0 for the convenience of callers that must return an integer.
</function>
<function>
void modebuf_extract(struct ModeBuf *mbuf, char *buf);
One use of the ModeBuf within ircd requires the ability to pull a
simple mode string out of the struct ModeBuf for use elsewhere. This
can be accomplished with this function. The _buf_ parameter should be
large enough to accommodate the simple mode string.
</function>
<function>
void mode_ban_invalidate(struct Channel *chan);
Looking up bans affecting a particular user can be a fairly expensive
operation, so the server caches the result of the lookup. Should the
ban list for a channel change, all the cached results must be
invalidated to force rechecking. This may be done with the
mode_ban_invalidate() function, which acts upon the channel given by
_chan_.
</function>
<function>
void mode_invite_clear(struct Channel *chan);
When a channel that was invite-only has the "+i" channel mode removed,
the invite list that the server keeps is no longer necessary. The
mode_invite_clear() function flushes that invite list for the channel
given by _chan_, reclaiming the memory used by the invite list.
</function>
<function>
int mode_parse(struct ModeBuf *mbuf, struct Client *cptr, struct Client *sptr,
struct Channel *chptr, int parc, char *parv[],
unsigned int flags);
This function parses a mode change command, given by the contents of
_parv[]_, and under the control of _flags_. The channel being modified
is given by _chptr_, the source of the change is given by _sptr_, and
the connection the change was received from is given by _cptr_. The
_parc_ parameter gives the count of the number of elements in the
_parv[]_ array. The ModeBuf must have already been initialized by a
call to modebuf_init(), described above. For more information on
_flags_, see the MODE_PARSE_* macros described below. This function
returns an integer indicating the number of elements of _parv[]_ it
used. The modebuf_flush() function must be called upon return from
mode_parse() to flush the mode changes to the channel.
</function>
<macro>
#define MODE_PARSE_SET 0x01 /* actually set channel modes */
When this flag is passed to mode_parse(), the channel mode being
parsed will actually be effected on the channel.
</macro>
<macro>
#define MODE_PARSE_STRICT 0x02 /* +m +n +t style not supported */
Users are permitted to send complicated mode commands like "MODE #foo
+m +n +t +k foo +i"; servers are not. Passing this flag to
mode_parse() causes it to strictly enforce this restriction.
</macro>
<macro>
#define MODE_PARSE_FORCE 0x04 /* force the mode to be applied */
Some mode changes are not permitted under normal circumstances. When
this flag is passed to mode_parse(), these mode changes will be
accepted.
</macro>
<macro>
#define MODE_PARSE_BOUNCE 0x08 /* we will be bouncing the modes */
This flag warns mode_parse() that the mode is to be bounced. This
will cause it to systematically feed each mode into ModeBuf in order
for that interface to generate the proper bounce messages.
</macro>
<macro>
#define MODE_PARSE_NOTOPER 0x10 /* send "not chanop" to user */
This flag is used to warn mode_parse() that the user generating the
mode change is not a channel operator. If the user attempts to change
a mode, an appropriate error message will be sent to the user (once).
</macro>
<macro>
#define MODE_PARSE_NOTMEMBER 0x20 /* send "not member" to user */
This flag is used to warn mode_parse() that the user generating the
mode change is not even on the channel. If the user attempts to
change a mode, an appropriate error message will be sent to the user
(once).
</macro>
<macro>
#define MODE_PARSE_WIPEOUT 0x40 /* wipe out +k and +l during burst */
When this flag is passed to mode_parse(), the channel key and limit
will be reversed if the mode string doesn't update them. This is used
for processing BURST messages.
</macro>
<macro>
#define MODE_PARSE_BURST 0x80 /* be even more strict w/extra args */
The BURST message is even more strict than a standard MODE message.
Processing *must* stop after reading the mode string itself, or
mode_parse() could gobble up arguments not intended for it. This flag
tells mode_parse() about this restriction.
</macro>
<authors>
Kev <klmitch@mit.edu>
</authors>
<changelog>
[2001-6-15 Kev] Initial documentation of the ModeBuf and mode parsing
subsystems.
</changelog>
+76
View File
@@ -0,0 +1,76 @@
The server has a Message of the Day (MOTD) which is often used for
describing the Acceptable Usage Policy, where to get help if you have
problems, and so on. Older versions of ircd had a lot of duplicated
code, as well as some inefficiencies, all related to sending the
MOTD. As of u2.10.11, there is an API specifically for MOTDs. This
API caches the MOTDs in memory for efficiency. Sending a MOTD to a
client is as simple as calling a single function.
<function>
void motd_init(void);
This function initializes the MOTD subsystem. It will also read in
the default MOTD (usually ircd.motd) and the remote MOTD (usually
remote.motd) files.
</function>
<function>
int motd_send(struct Client* cptr);
This function sends an appropriate MOTD to the client specified by
_cptr_. If _cptr_ is not a local client, the remote MOTD will be
sent; otherwise, an attempt will be made to find a Motd entry in the
configuration file that matches the client. If no Motd entry can be
found, the default MOTD will be sent to the client. This function
returns 0 for the convenience of other functions that must have an
integer return value. </function>
<function>
void motd_signon(struct Client* cptr);
This function is similar to motd_send(), described above, except that
it will only send a message to the client indicating when the MOTD was
last modified if the FEAT_NODEFAULTMOTD feature is set to TRUE.
</function>
<function>
void motd_recache(void);
The MOTD system will not automatically detect when MOTD files have
been modified. This function causes the MOTD system to clear the MOTD
cache and re-read the files.
</function>
<function>
void motd_add(const char *hostmask, const char *path, isgeoip);
This function is used to add a MOTD to be sent to clients possessing a
given _hostmask_. If _hostmask_ is a numerical string, it is
interpreted as a connection class. If _isgeoip_ is 0 then _hostmask_
is treated as described above. If _isgeoip_ is 1 then _hostmask_ is
treated as a 2 letter country code and if _isgeoip_ is 2 then
_hostmask_ is treated as a 2 letter continent code.
</function>
<function>
void motd_clear(void);
This function clears the list of special MOTDs. Only the default MOTD
and remote MOTD are not affected by this function.
</function>
<function>
void motd_report(struct Client *to);
The motd_report() function sends a list of the Motd entries stored in
memory to the client specified by _to_. Access control should be
handled by the caller.
</function>
<authors>
Kev <klmitch@mit.edu>
</authors>
<changelog>
[2001-6-15 Kev] Initial documentation of the MOTD interface.
</changelog>
+195
View File
@@ -0,0 +1,195 @@
Many messages generated by an IRC server are sent to multiple
recipients. Previous versions of ircd used DBuf to store these
messages until they could actually be sent. The problem with using a
DBuf for this, though, is that there are multiple copies of the same
message hanging around. Another problem is that there is at least one
strcpy() or equivalent call for each destination the message is sent
to. A simple solution to this problem is to use messages queues.
This file documents the MsgQ interface for ircd.
The MsgQ interface is loosely based on the API for DBuf. Although the
structures are vastly different, most calls, including several of the
macros, are similar to certain pieces of the DBuf API. This made
retrofitting ircd with MsgQ support much simpler.
<struct>
struct MsgCounts {
int alloc;
int used;
};
The MsgCounts structure may be used for determining how much memory is
in use by the MsgQ system. The _alloc_ element is a count of the
total number of structures (of whatever type) that have been
allocated; the _used_ element is a count of how many are actually in
use. MsgQ never releases any of its allocated memory; instead, it
places unused structures onto a free list.
</struct>
<struct>
struct MsgBuf;
The MsgBuf structure contains the actual message, along with a
reference count and the message's length. None of its fields are
directly accessible by the application.
</struct>
<struct>
struct MsgQ;
The MsgQ structure is a structure allocated by the application that is
used by the MsgQ system to describe an entire message queue, including
both normal and priority queues. None of its fields are directly
accessible by the application.
</struct>
<global>
struct MsgCounts msgBufCounts; /* resource count for struct MsgBuf */
This global variable counts the number of MsgBuf structures that have
been allocated. This may be used to determine how much memory is in
use by the MsgQ system.
</global>
<global>
struct MsgCounts msgCounts; /* resource count for struct Msg */
This global variable counts the number of Msg structures that have
been allocated. The Msg structure describes the link between a queue
and a message. It is not accessible to the application, and so not
further documented here.
</global>
<function>
unsigned int MsgQLength(struct MsgQ* mq);
This macro returns the number of bytes in a particular user's message
queue.
</function>
<function>
unsigned int MsgQCount(struct MsgQ* mq);
This macro returns the number of messages in a particular user's
message queue.
</function>
<function>
void MsgQClear(struct MsgQ* mq);
This macro simply clears the content of a particular message queue.
NOTE: This macro evaluates its argument twice.
</function>
<function>
void msgq_init(struct MsgQ *mq);
This function initializes a caller-allocated message queue to be
empty. Calling this function on a message queue with messages in it
WILL RESULT IN A MEMORY LEAK.
</function>
<function>
void msgq_delete(struct MsgQ *mq, unsigned int length);
This function removes the given number of bytes from the message
queue. If entire messages have been sent, they will be unlinked from
the queue. The _length_ parameter does not need to correspond to a
given message's length; the MsgQ system is able to deal with messages
that have only partially been sent.
</function>
<function>
int msgq_mapiov(const struct MsgQ *mq, struct iovec *iov, int count,
unsigned int *len);
The msgq_mapiov() function takes a struct MsgQ (specified by the _mq_
parameter) and a caller allocated struct iovec array (specified by the
_iov_ parameter) and maps the contents of the message into the struct
iovec array. The _count_ parameter must indicate the total number of
elements available for msgq_mapiov() to use. The _len_ parameter must
be a pointer to an unsigned int, and upon return from the function
will contain the total number of bytes that have been mapped into the
struct iovec array. This function returns the number of struct iovec
elements that have been filled. For more information about the
purpose of struct iovec, see your system's man page for the writev()
function.
</function>
<function>
struct MsgBuf *msgq_make(struct Client *dest, const char *format, ...);
This function allocates a struct MsgBuf and calls ircd_vsnprintf()
with the _dest_ and _format_ parameters to fill it in. Most callers
should use the send_buffer() function (declared in send.h) to attach
the struct MsgBuf to a client's message queue.
</function>
<function>
struct MsgBuf *msgq_vmake(struct Client *dest, const char *format, va_list vl);
This function is identical to msgq_make() except that it takes a
va_list (given by the _vl_ parameter) and calls ircd_vsnprintf() to
format the message.
</function>
<function>
void msgq_append(struct Client *dest, struct MsgBuf *mb, const char *format,
...);
Occasionally a caller is not able to completely compute a message
before calling msgq_make(). When this happens, the msgq_append()
function may be called to append more text onto the struct MsgBuf
specified by the _mb_ parameter. As with msgq_make(), the _dest_ and
_format_ parameters are passed to ircd_vsnprintf(), along with the
additional arguments.
</function>
<function>
void msgq_clean(struct MsgBuf *mb);
As mentioned above, struct MsgBuf includes a reference count. When
that reference count reaches zero, the structure is released. The
reference count is set to 1 by msgq_make() and msgq_vmake(). Once a
given message has been attached to all the queues it needs to be, the
caller should call the msgq_clean() function to decrement this
reference count. This function will place the struct MsgBuf back onto
the free list if it did not get attached to any message queues. The
msgq_delete() function calls msgq_clean() internally, so the
application need not call msgq_clean() explicitly afterwards.
</function>
<function>
void msgq_add(struct MsgQ *mq, struct MsgBuf *mb, int prio);
This function is used to attach a given struct MsgBuf, as specified by
the _mb_ parameter, to a given message queue. The _prio_ parameter,
if non-zero, specifies that the message should be placed on the
priority queue. This function is called by send_buffer(), defined in
send.h; most applications should call that function, rather than this
one.
</function>
<function>
void msgq_count_memory(size_t *msg_alloc, size_t *msg_used,
size_t *msgbuf_alloc, size_t *msgbuf_used);
This function simply takes the counts kept in msgBufCounts and
msgCounts and multiplies them by the appropriate structure sizes,
storing the resulting sizes into its parameters.
</function>
<function>
unsigned int msgq_bufleft(struct MsgBuf *mb);
This function is for use in conjunction with msgq_append(). It
returns the total number of bytes of free storage in the given _mb_.
</function>
<authors>
Kev <klmitch@mit.edu>
</authors>
<changelog>
[2001-6-15 Kev] Initial documentation for the MsgQ functions.
</changelog>
+91
View File
@@ -0,0 +1,91 @@
Access control becomes more of a problem as you have more and more
users that need to access certain features. As it stands, ircu has
only 3 access levels: ordinary user, local operator, and global
operator. This is hardly enough control, especially over some of the
more advanced and powerful features, such as G-lines.
Since u2.10.11, ircu includes the concept of privileges. Privileges
are basically an arbitrarily long bit string. Access to particular
features is governed by the value of a particular bit of that bit
string--in other words, privileges are a form of Access Control List.
This document covers the basic structures and macros used by the
privileges system.
<struct>
struct Privs;
The Privs structure stores a privileges bit string and represents a
user's entire privilege set. This is implemented as a structure,
rather than as an array of integers, in order to leverage C's
structure copy.
</struct>
<function>
void PrivSet(struct Privs pset, int priv);
This macro sets the privilege specified by _priv_ in the privileges
structure. This macro evaluates the _priv_ argument twice.
</function>
<function>
void PrivClr(struct Privs pset, int priv);
This macro clears the privilege specified by _priv_ in the privileges
structure. This macro evaluates the _priv_ argument twice.
</function>
<function>
int PrivHas(struct Privs pset, int priv);
This macro tests whether the privilege specified by _priv_ is set in
the privileges structure, returning non-zero if it is. This macro
evaluates the _priv_ argument twice.
</function>
<function>
void GrantPriv(struct Client* cli, int priv);
This macro grants a particular client, specified by _cli_, the
privilege specified by _priv_. This macro evaluates the _priv_
argument twice.
</function>
<function>
void RevokePriv(struct Client* cli, int priv);
This macro revokes the privilege specified by _priv_ from the client.
This macro evaluates the _priv_ argument twice.
</function>
<function>
int HasPriv(struct Client* cli, int priv);
This macro tests whether the client specified by _cli_ has the
privilege specified by _priv_, returning non-zero if so. This macro
evaluates the _priv_ argument twice.
</function>
<function>
void client_set_privs(struct Client* client);
The ircu configuration file does not yet support privileges. This
function thus sets the appropriate privileges for an operator, based
upon various feature settings. It should be called whenever there is
a change in a user's IRC operator status.
</function>
<function>
int client_report_privs(struct Client *to, struct Client *client);
This function sends the client specified by _to_ a list of the
privileges that another client has. It returns a value of 0 for the
convenience of other functions that must return an integer value.
</function>
<authors>
Kev <klmitch@mit.edu>
</authors>
<changelog>
[2001-6-15 Kev] Initial documentation of the privileges system.
</changelog>
+231
View File
@@ -0,0 +1,231 @@
The send functions are perhaps the most important API in all of ircd;
without them, communications would not be possible. Most of these
functions are pretty much stand-alone, although one or two are
intended for use in conjunction with the MsgQ interface. The send
functions use the MsgQ interface internally, but for the most part,
this fact is hidden from the caller.
Command tokenization provides the greatest complication. The
functions do use ircd_snprintf() internally, so the use of numerics
doesn't increase that complication. The tokenization issue is dealt
with by making each function accept two char* pointers, _cmd_ and
_tok_, in that order, and then defining a CMD_* macro in msg.h that
contains the message string and the token string in that order. When
one of these functions is called, it determines whether the
destination will be a server or a user, then selects the correct one,
either _cmd_ or _tok_, for that message.
The MsgQ interface provides the concept of a priority queue; messages
which must be sent as soon as possible, regardless of what other
messages may already be in the queue. The sendcmdto_prio_one() and
sendcmdto_flag_butone() functions make use of this priority queue.
The function send_buffer() also takes a _prio_ argument that should be
non-zero if the message passed to it should be placed in the priority
queue.
<macro>
#define SKIP_DEAF 0x01 /* skip users that are +d */
This flag may be passed to sendcmdto_channel_butone() to cause a
message passed by that function to skip users that are +d. See the
documentation for sendcmdto_channel_butone() for more information.
</macro>
<macro>
#define SKIP_BURST 0x02 /* skip users that are bursting */
This is another flag that may be passed to
sendcmdto_channel_butone(). Its purpose is to cause the server to not
send the message across a link that is still in the "burst" stage of
network junction. See the documentation for
sendcmdto_channel_butone() for more information.
</macro>
<macro>
#define SKIP_NONOPS 0x04 /* skip users that aren't chanops */
Some messages may need to be passed only to channel operators. This
flag is passed to sendcmdto_channel_butone() when that is the case.
See the documentation for sendcmdto_channel_butone() for more
information.
</macro>
<function>
void send_buffer(struct Client* to, struct MsgBuf* buf, int prio);
Some applications may need to build a message piece by piece, directly
utilizing the MsgQ interface. The function send_buffer() is used when
that message has been completed to place the message on a client's
queue. See the documentation for the MsgQ interface for more
information about struct MsgBuf and the _buf_ parameter.
</function>
<function>
void flush_connections(struct Client* cptr);
This function attempts to send all queued data to a client specified
by _cptr_. If _cptr_ is 0, all clients with non-empty send queues
will have their queues flushed.
</function>
<function>
void send_queued(struct Client *to);
This function attempts to send all queued data to a client specified
by _to_. The _to_ parameter is not permitted to be 0. This is the
function called by flush_connections().
</function>
<function>
void sendrawto_one(struct Client *to, const char *pattern, ...);
Most of the actual send functions in this API send their data with a
prefix--the numeric of the origin. This function is used when a
message should be sent _without_ that prefix. The caller must specify
the complete message, including the exact command, with the _pattern_
argument and the variable argument list following it.
</function>
<function>
void sendcmdto_one(struct Client *from, const char *cmd, const char *tok,
struct Client *to, const char *pattern, ...);
This function is used for sending messages to specific clients. The
origin of the message is specified using the _from_ parameter; this
will be used to formulate the origin. As mentioned above, _cmd_ and
_tok_ are used to determine the command and token to be used. The
_to_ parameter specifies which client the message should be sent to.
The origin and command will be formatted and followed by a space; the
given _pattern_ and the following arguments are passed to
ircd_snprintf() for formatting.
</function>
<function>
void sendcmdto_prio_one(struct Client *from, const char *cmd, const char *tok,
struct Client *to, const char *pattern, ...);
This function is identical to sendcmdto_one() except that messages
formatted using it will be placed onto the priority queue.
</function>
<function>
void sendcmdto_serv_butone(struct Client *from, const char *cmd,
const char *tok, struct Client *one,
const char *pattern, ...);
This function treats its arguments similar to sendcmdto_one() does.
Messages passed created with this function are sent to all directly
linked servers except for the _one_ passed. If _one_ is 0, the
message is sent to all linked servers.
</function>
<function>
void sendcmdto_common_channels(struct Client *from, const char *cmd,
const char *tok, const char *pattern, ...);
When a user quits IRC, all of the other users on the channels that the
user is on must receive a single QUIT message. This function formats
the message, under control of _from_ (for the origin prefix), _cmd_
and _tok_, and _pattern_ and the variable argument list, and sends
that message to all local users on the same channels as the user
specified by _from_. This function does not send any messages across
server<->server links.
</function>
<function>
void sendcmdto_channel_butserv(struct Client *from, const char *cmd,
const char *tok, struct Channel *to,
const char *pattern, ...);
This function is used to send a command to every local user on a
particular channel, specified by _to_. No messages are sent across
the server<->server links.
</function>
<function>
void sendcmdto_channel_butone(struct Client *from, const char *cmd,
const char *tok, struct Channel *to,
struct Client *one, unsigned int skip,
const char *pattern, ...);
This function is used mostly for sending PRIVMSG commands to
particular channels. The users that receive the message are under the
control of the _skip_ parameter, which is a binary OR of the
SKIP_DEAF, SKIP_BURST, and SKIP_NONOPS flags, depending on what
channel users should see the message. This function sends messages
across both client<->server and server<->server links, as needed. The
client specified by _one_ will not receive a copy of the message.
</function>
<function>
void sendcmdto_flag_butone(struct Client *from, const char *cmd,
const char *tok, struct Client *one,
unsigned int flag, const char *pattern, ...);
This function is used for sending messages to clients with specific
user modes set (specified by the _flag_ parameter). Three flags make
sense for this function: FLAGS_WALLOP (user mode +w), FLAGS_DEBUG
(user mode +g), and FLAGS_OPER. FLAGS_OPER has a special meaning that
further restricts distribution of the message only to IRC operators.
For the purposes of this function, no distinction is made between
global operators and local operators.
</function>
<function>
void sendcmdto_match_butone(struct Client *from, const char *cmd,
const char *tok, const char *to,
struct Client *one, unsigned int who,
const char *pattern, ...);
Certain kinds of global messages may be sent by IRC operators. This
function implements those global messages. The _to_ parameter is used
to specify a pattern by which to filter users, while _who_ specifies
whether that pattern is to be applied to the user's server name or to
the user's host name. The _who_ parameter may be one of MATCH_SERVER
or MATCH_HOST; these two macros are defined in s_user.h. The _one_
parameter will not receive a copy of the message.
</function>
<function>
void sendto_opmask_butone(struct Client *one, unsigned int mask,
const char *pattern, ...);
The sendto_opmask_butone() function sends a server notice to all
subscribing users except for _one_. The _mask_ parameter is one of
the SNO_* values defined in client.h and is used for selection of
subscribing users.
</function>
<function>
void vsendto_opmask_butone(struct Client *one, unsigned int mask,
const char *pattern, va_list vl);
The vsendto_opmask_butone() function is identical to the
sendto_opmask_butone() function except that instead of a variable
argument list, it takes a va_list, specified by _vl_.
</function>
<macro>
#define SND_EXPLICIT 0x40000000 /* first arg is a pattern to use */
When this flag, defined in ircd_reply.h, is combined with the _reply_
argument to the send_reply() function, the format string send_reply()
uses is obtained from the first argument in the variable argument list
passed to that function, rather than from the table of replies.
</macro>
<function>
int send_reply(struct Client* to, int reply, ...);
The send_reply() function, declared in ircd_reply.h, is used to send
clients numeric replies. Unless SND_EXPLICIT is used, the pattern
will be extracted from a table of replies.
</function>
<authors>
Kev <klmitch@mit.edu>
</authors>
<changelog>
[2001-6-15 Kev] Initial documentation for the send functions.
</changelog>