IRC Services Manual

6. Adding to and modifying Services

6-1. Writing modules
    6-1-1. Overview
    6-1-2. Module loading and unloading
    6-1-3. Inter-module dependencies
    6-1-4. Callbacks
    6-1-5. Handling messages from the network
    6-1-6. Special types of modules
    6-1-7. Compilation and installation
6-2. Callbacks provided by Services and standard modules
    6-2-1. Services core callbacks
    6-2-2. OperServ callbacks
    6-2-3. NickServ callbacks
    6-2-4. ChanServ callbacks
    6-2-5. MemoServ callbacks
    6-2-6. StatServ callbacks
    6-2-7. HTTP server callbacks
6-3. Submitting additions or changes to Services
6-4. Coding guidelines for Services

Table of Contents

6-1. Writing modules

IRC Services 5.0 introduces a new "module" system allowing features to be added to and removed from Services at will with no changes to the core Services code.

Note that this section is not a complete "how-to" for writing modules; please read the source code for existing modules for detailed information. In particular, the "protocol/unreal" module (modules/protocol/unreal.c) is extensively documented and is intended to serve as an example of how modules should be written.

6-1-1. Overview

Services modules are based on, and in fact use the same system as, standard dynamic-link libraries. Upon startup or reloading of the configuration file, Services will load specified modules into memory and execute each module's initialization function. This function should set up any data structures necessary and register all callback functions needed (see below). At shutdown, or when the module is otherwise unloaded, its cleanup function will be called; this function should free all resources in use and perform other necessary cleanup functions, or return an error if the module cannot unload itself for some reason.

Module interaction with Services takes place primarily through the use of callbacks. These are functions which the module registers with Services to be called when a particular event occurs, such as a message arriving from the remote server or a certain amount of time passing. Typically, a module will register callbacks for events it is interested in in its initialization routine, and remove them when the module is unloaded.

Modules are manipulated using the functions provided by modules.c in the Services core. They are as followed:

Module *load_module(const char *modulename)

Loads the given module and returns a pointer to a data structure (Module *) for the module. The contents of this data structure are private, and the pointer should only be considered as a "handle" that indicates a particular module. If the module could not be loaded, returns NULL. See section 6-1-2 below for details on the module loading process.

int unload_module(Module *module)

Unloads the given module. Returns nonzero if the module was successfully unloaded, zero if not. See section 6-1-2 below for details on the module unloading process.

Module *find_module(const char *modulename)

Returns a handle for the module whose name is given by "modulename". If no such module has been loaded, returns NULL.

void use_module(Module *module)

Increments the "use count" for the given module. A module whose use count is nonzero is not permitted to be unloaded. This function is typically called by modules which depend on other modules to function properly; see section 6-1-3 for details on inter-module dependencies. A module may call use_module() on itself only if the global variable modules_allow_use_self is nonzero; otherwise, a "BUG" message will be logged and the call will fail. Modules may never call use_module() in such a way as to create a dependency loop of two or more modules, regardless of the setting of modules_allow_use_self (doing so will likewise cause a "BUG" message to be logged).

void unuse_module(Module *module)

The opposite of use_module(): decrements the "use count" for the given module. As with use_module(), a module may not call unuse_module() on itself unless the global variable modules_allow_use_self is nonzero.

void *get_module_symbol(Module *module, const char *symname)

Looks up the value of the symbol "symname" in the given module, and returns its value; if the symbol cannot be found, returns NULL. If the symbol is not defined in the given module but is defined by another module, the return value of this function is undefined. If "module" is NULL, then the main program and all modules are searched for the symbol, and NULL is only returned if the symbol does not exist (if the symbol is defined more than once, then a random one will be returned).

Note that the "value" of a symbol as returned by this function is the address of the symbol. In particular, using this function to look up a variable in another module will return the address of the variable, not not the value it actually contains; thus, if a module declares

int intvar;

then code similar to the following should be used to access it:

int *p_intvar = get_module_symbol(mod, "intvar"); if (p_intvar) printf("Value of `intvar' is %d\n", *p_intvar); else printf("Unable to resolve symbol `intvar'\n");

const char *get_module_name(Module *module)

Returns the name of the given module. This is usully the path used to load the module (passed to load_module()), but may be different if the module defines a module_name symbol. If NULL is passed for the "module" parameter, returns the string "core".

MODULE_NAME

This preprocessor macro is a shortcut for get_module_name(module) (where "module" is assumed to be a variable pointing to the current module's handle). It can be used just like any other string constant or macro, except that it cannot be inserted into literal string constants; in other words,

printf("Module name: " MODULE_NAME "\n");

will not compile.

int register_callback(Module *module, const char *name)

Registers a new callback list. The calling module should pass its own module information structure (as passed to init_module() or obtained from find_module()). Returns an ID value, which is a non-negative integer.

int call_callback(Module *module, int id) int call_callback_1(Module *module, int id, void *arg1) int call_callback_2(Module *module, int id, void *arg1, void *arg2) int call_callback_3(Module *module, int id, void *arg1, void *arg2, void *arg3) int call_callback_4(Module *module, int id, void *arg1, void *arg2, void *arg3, void *arg4) int call_callback_5(Module *module, int id, void *arg1, void *arg2, void *arg3, void *arg4, void *arg5)

Calls each function in the given callback list, optionally passing additional arguments to the callback function. If a function in the list returns a nonzero value, that value is returned immediately to the caller without calling any additional callback functions. If all callback functions return zero (or there are no functions to call), returns 0; returns -1 on error (the given callback ID does not exist for the given module).

int unregister_callback(Module *module, int id)

Deletes a callback list. Returns nonzero on success, zero on failure (given callback does not exist).

int add_callback_pri(Module *module, const char *name, callback_t callback, int priority)

Adds the given callback function to the given list with the given priority (a higher priority value means the function is called sooner). The priority must be between CBPRI_MIN and CBPRI_MAX inclusive. Returns nonzero on success, zero on failure (given callback does not exist or priority out of range). An error will not be returned if the same function is registered more than once, but this behavior is not supported and may change in the future.

int add_callback(Module *module, const char *name, callback_t callback)

Adds the given callback function to the given list with priority zero. This is a shortcut for add_callback_pri(module,name,callback,0), and the two forms are exactly equivalent.

int remove_callback(Module *module, const char *name, callback_t callback)

Removes the given callback function from the given list. Returns nonzero on success, zero on failure (given callback does not exist, or given function is not on callback list).

6-1-2. Module loading and unloading

Modules are loaded through the load_module() function in modules.c, which is called for each module listed in ircservices.conf at Services startup (and when an OperServ REHASH command is given after adding a new module to ircservices.conf). load_module() takes one parameter, the name of the module to load, and performs the following steps (assuming dynamically-compiled modules on a system with the dlXXX() family of functions):

Calls dlopen() for the module (the filename is the module name passed to load_module() with ".so" appended). If dlopen() fails, load_module() returns NULL.
Creates a module information structure (Module *) for the module and initializes it.
Checks the module's version code against the version code of the Services core; if the two do not match or a version number is not present in the module, load_module() frees the module information structure, calls dlclose() on the module and returns NULL. The version code is declared as
int32 module_version = MODULE_VERSION_CODE;
and must be exported by every module.
Parses the section of the modules.conf file for the module (if any), using the configuration directives in module_config[]. module_config[] must be defined as an array of ConfigDirective elements, terminated by an element with name == NULL. If any errors occur during parsing, load_module() frees the module information structure, calls dlclose() on the module and returns NULL.
Calls the module's init_module() function, passing the allocated module information structure. This function should return nonzero on success and zero on failure. If the function returns failure, load_module() frees the module information structure, calls dlclose() on the module and returns NULL.
Calls the load module callback, passing the module pointer to each function in the callback list.
Links the module information structure into the global module list and returns it.

The unload_module() function takes a pointer to the module structure (handle) for the module to unload, and performs the following steps:

Calls the module's exit_module() function. This function takes a single parameter, `int shutdown', which is 0 for a regular module unload and 1 if the program is shutting down. The function should return nonzero on success and zero on failure; if it returns failure, unload_module() returns zero (failure).
Calls the unload module callback, passing the module pointer to each function in the callback list.
Calls dlclose() for the module.
Unlinks the module information structure from the global list and returns nonzero (success).

6-1-3. Inter-module dependencies

Some modules may require functions from other modules to work correctly; for example, a module adding a new command to NickServ would obviously require NickServ itself to be loaded first. Such modules can use the find_module() function from modules.c to check whether the module has been loaded. An example might look like this:

    static Module *module_nickserv;
    ...
    int init_module(Module *me)
    {
        module_nickserv = find_module("nickserv/main");
        if (!module_nickserv)
            return 0;
        ...
        return 1;
    }

find_module() returns a pointer to the module found, so this can be saved and used in other function calls as needed.

Note that modules should not attempt to load other modules themselves, as the administrator may have deliberately chosen not to include such modules. Instead, the module should fail to load, optionally writing a log message explaining the problem.

If symbols, such as exported functions, from another module are needed, they can be looked up using the get_module_symbol function. This function takes a module pointer and a symbol name and returns the address of the symbol (see the function documentation for details). For example, to access the variable s_NickServ, which contains the NickServ pseudoclient's nickname, from the nickserv/main module, code such as the following could be used:

    static char **s_NickServ_ptr;
    #define s_NickServ (*s_NickServ_ptr)
    ...
    int init_module(Module *me)
    {
        ...
        s_NickServ_ptr = get_module_symbol(module_nickserv, "s_NickServ");
        if (!s_NickServ_ptr) {
            module_log("Unable to resolve symbol `s_NickServ'");
            return 0;
        }
        ...
    }
    ...
    static void send_message(User *user)
    {
        notice(s_NickServ, user->nick, "message");
    }

This code would retrieve the address of the s_NickServ variable during module initialization, then dereference it to obtain the contents of the variable (the nickname itself), using a macro to make the code easier to read. (This macro would have to be defined after any #include directives to avoid errors in header declarations.) If the symbol was not found, the module would fail to load.

When using variables from other modules, be aware that while the address of the variable will always remain constant, the value of the variable may change at any time, so you should always access the value by dereferencing a pointer to it, rather than by saving the value locally. The macro used in the example above provides a way to do this which still allows the symbol to be used as if it was an ordinary variable. (However, in the example above the pointer variable is guaranteed not to be NULL, because the module returns failure from init_module() if the symbol is not found. If the module does not do this or take other steps to ensure that the pointer is valid, the macro would need to be modified to provide a default value in case the pointer is NULL.)

A second, though not recommended, method of importing symbols from other modules is to simply reference them as you would ordinary external symbols. This will create an unresolved reference to the symbol in the module object file, which will be resolved at load time. This approach is slightly more efficient than using get_module_symbol(), since there is no need to store or retrieve the symbol's address separately. However, if the symbol is not found at load time, then load_module() will log an error message and return failure without calling the module's init_module() function, so there is no way for the module to log a more informative error message or take other action. This method should only be used when it can be assumed that the module being used will always be loaded first; for example, the NickServ sub-modules (such as nickserv/autojoin and nickserv/link) take this approach with respect to the main NickServ module (nickserv/main). It is still necessary to retrieve the module pointer using find_module() if it is needed for other module-related function calls.

One thing to keep in mind, whichever method is used, is that modules can only reference symbols in modules loaded earlier. If your module depends on symbols from another, make certain you document that so that people who use the module put it in the right place in ircservices.conf.

In certain cases, circular references may arise—a case where module A depends on a symbol from module B, while module B depends on a symbol from module A. In such a case, at least one of the modules must use get_module_symbol() to access the other module's symbol, and must do it after the module has been loaded (i.e. not failing in init_module()), so that the other module has a chance to load as well. This can be accomplished using the load module callback in the Services core, which allows the module to take action when subsequent modules are loaded.

Finally, modules which export symbols to be used with other modules must explicitly declare them to be exported, using the EXPORT_VAR(), EXPORT_ARRAY(), or EXPORT_FUNC() macros in modules.h; for example:

    EXPORT_VAR(int,variable)
    int variable = 123;

    EXPORT_ARRAY(char,string)
    char string[] = "Hello world";

    EXPORT_FUNC(function)
    int function(int x) { return x*x+x; }

These macros do not have any actual effect on compilation, but they are used by a script which prepares the modules for static linking. Without these declarations, modules will be unable to access any symbols in the module when compiled statically. Note, however, that the init_module() and exit_module() functions and the module_version and module_config variables are automatically exported, and should not be explicitly listed this way (in fact, listing them will cause an error when compiling statically).

6-1-4. Callbacks

modules.c provides an interface for registering and calling callback functions; these are functions which are called from a separate module or function when a certain event occurs, such as a module being loaded or a user connecting to IRC. Callbacks are referred to by a combination of module and callback name or ID (callbacks in the Services core use a module pointer of NULL).

The type of a callback function is defined by callback_t: int (*)(...). The parameters passed to the function depend on the particular callback. If a callback function desires to terminate processing of the callback list, it should return a nonzero value; returning zero will allow the next function in the list to be called. Any pointer parameters should be considered "const" (unmodifiable) unless the function processes the event and returns nonzero.

To add a callback function to a callback list registered by another module (or a callback list defined by the Services core), use the add_callback() function (or add_callback_pri() if you want to use a priority other than zero; priorities are used to determine the order in which the functions are called, as described below). To remove a function previously added to a callback list, use the remove_callback() function. It is legal to attempt to remove a callback function which was not added in the first place, or to attempt to remove a callback function from a nonexistent callback; remove_callback() will return failure in these cases. Warning: if you forget to remove callbacks before or when your module exits, Services will crash!

To create your own callback list, use the register_callback() function; to delete it, call the unregister_callback() function, passing in the callback ID returned from register_callback(). To call a list of callback functions, use the call_callback_X() set of functions, where X is the number of parameters passed to each callback function (the _X is omitted if no parameters are passed). This syntax is used to help module creators double-check that the right number of parameters are being passed to callback functions, since such functions cannot be checked against prototypes.

Callback functions are called in descending order of priority (so, for example, a function with a priority of 1 is called before one with a priority of 0); functions with the same priority are called in the same order they were added to the callback list.

See section 6-2 below for a list of available callbacks.

6-1-5. Handling messages from the network

Most modules will need to be able to process messages received from the IRC network to perform any useful functions. There are four main ways of doing this:

Through one of the pseudoclients' "command" callbacks. If your module adds functionality to one of the existing pseudoclients (NickServ, ChanServ, etc.), you can hook into the "command" callback provided by that pseudoclient to receive each command (other than a CTCP PING) sent to the pseudoclient, and process the commands that apply to you. You will probably also want to hook into the "HELP" and "HELP COMMANDS" callbacks to provide help information about the commands your module implements. See the section below on the particular pseudoclient's callbacks for details.
Through the m_privmsg callback. This callback is designed for handling user interaction with pseudoclients; if you hook into this callback, you will be able to check each PRIVMSG (/msg) message received by Services and take appropriate action. (Naturally, you should leave alone any PRIVMSG addressed to a nickname your module doesn't use.)
By registering a message list. This method is intended for use by protocol modules to implement protocol-specific features, but can be used by any module. Set up an array of Message structures (see the messages.h file) terminated by an entry with name == NULL, then call register_messages(table) (where table is the array of Message structures). When a message with a name listed in your message table arrives, the routine given in the func member associated with that name will be called with the message source (char *) and an argument count (int) and array (char **); if you specify NULL instead of a function pointer, the message will be silently ignored. As with callbacks, make certain you call unregister_messages() on your message table when your module is unloaded, or Services will crash on the next message it receives when it tries to access your (nonexistent) table.
Note that if a particular message is listed in more than one message table, only the function in the most recently registered table will be called; this allows you to override the default behavior for a particular message. If you do this, however, be aware that there is no way to call the previously registered function--if you want to allow the previous handler to run, you will need to use the receive message callback, discussed below.
Through the receive message callback. This is the lowest-level method of handling messages; your callback function will be called for each message received from the remote server, and you can decide whether to process the message or pass it on.

6-1-6. Special types of modules

While callbacks are used for most inter-module interactions, to improve performance, some types of modules are integrated more tightly with Services. These include protocol modules, database modules, and mail modules.

Protocol modules

Protocol modules allow Services to communicate with different types of IRC servers. Services calls several routines in these modules directly; each protocol module must set the following function pointers to point to appropriate routines:

void (*send_nick)(const char *nick, const char *user, const char *host, const char *server, const char *name, const char *modes): Sends an appropriate combination of NICK/USER/MODE messages (or their equivalents) to introduce a new nickname onto the network.
void (*send_nickchange)(const char *nick, const char *newnick): Sends a NICK message to change an existing user's nickname.
void (*send_namechange)(const char *nick, const char *newname): Sends a message to change an existing user's "real name", if possible. (If the protocol does not support it, this can be a do-nothing routine, but it must be defined.)
void (*send_server)(void): Sends the initial server registration message (typically a SERVER message) for Services itself.
void (*send_server_remote)(const char *server, const char *reason): Sends a server registration message for a "remote" server (used for jupes).
void (*wallops)(const char *source, const char *fmt, ...): Sends a message to "all IRC operators" (the definition of which may vary between protocols). This is implemented as a WALLOPS for RFC1459, but as a GLOBOPS for DALnet-compatible servers, for example. This function takes printf()-style parameters.
void (*notice_all)(const char *source, const char *fmt, ...): Sends a notice to all users on the IRC network, typically using "NOTICE $*" or equivalent (protocols which do not support $* by itself may require a common domain name to be set in the configuration file, as the RFC1459 and most other current protocols do). This function takes printf()-style parameters.
void (*send_channel_cmd)(const char *source, const char *fmt, ...): Sends a command which modifies channel status. This is used where "source" is a nickname introduced by Services (such as "ChanServ"); some protocols do not allow arbitrary clients, even those from Services, to change channel commands, so those protocols would need to change "source" to "ServerName" or take other measures to get the command recognized. If possible, the command should be sent on as is, for example:
va_list args; va_start(args, fmt); vsend_cmd(source, fmt, args); va_end(args);
This command takes printf()-style parameters.
void (*send_nickchange_remote)(const char *nick, const char *newnick): Forcibly changes a remote client's nickname. The client's current nickname is given by "nick", and the nickname to change to by "newnick". Note: This routine must not be called if the PF_CHANGENICK flag is not set in protocol_features (see below).

The two strings "pseudoclient_modes" and "enforcer_modes" should also be set to the user modes which pseudoclients and enforcers, respectively, should receive.

Furthermore, the module must set the following four variables (defined in send.c) to appropriate values:

const char *protocol_name: The name of the protocol (e.g. RFC1459, Dreamforge, etc.)
const char *protocol_version: A string which identifies what versions of the protocol are supported. If the protocol does not have "versions", the variable should be set to the empty string ("").
uint32 protocol_features: A bitmask indicating what features (PF_* constants defined in services.h) are supported by the protocol; if none of the listed features are supported, the value should be 0.
int protocol_nickmax: The actual maximum length of a nickname, not including the trailing null byte used when storing the string internally; for example, RFC1459-compliant servers would use a value of 9 here. The module should check that NICKMAX (defined in defs.h) is strictly greater than this value, and refuse to load if it is less or equal. (Remember that NICKMAX includes the trailing null byte, so it must be at least 1 byte greater than protocol_nickmax, which does not include the trailing null.)

For examples of how protocol modules should be designed, see the Unreal module (modules/protocol/unreal.c), which is fairly well documented.

Database modules

Database modules provide the means for Services to store non-volatile data (data which will be saved between runs), such as the nickname and channel databases. These modules must provide the functions to open, read, write, and close databases for each of the major Services module groups (OperServ, NickServ, ChanServ, MemoServ, and StatServ).

Details of database modules are still in flux; to be defined later.

Mail modules

Mail modules provide the low-level functionality to actually send E-mail, and are called by the high-level mail module (mail/main) when mail is to be sent. When loaded (i.e. in the init_module() function), mail modules must set the "low_send" symbol (exported from the mail/main module) to point to a function with the following prototype:

    int low_send(const char *from, const char *fromname, const char *to,
                 const char *subject, const char *body)

"from" and "fromname" are the address and name, respectively, to be used in the From: line; "to" is the address for the To: line, "subject" is the text for the Subject: line, and "body" is the body text. Except for "body", none of the strings will contain newlines, and the "from" and "to" strings will be valid E-mail addresses (as determined by valid_email()). The function should return 0 on success, -1 on failure.

6-1-7. Compilation and installation

In order to compile and install a new module, you should do the following:

Place your module in a new subdirectory under the modules directory.
Create a Makefile for your new subdirectory.
Run make and make install (or gmake and gmake install) as usual.

The Makefile in the modules directory will automatically detect the presence of your new subdirectory and call its Makefile as appropriate. Additionally, the modules/Makerules file contains rules for compiling modules both dynamically and statically, so in most cases you only need to set the variables it needs (see the comments at the top of that file) and add "include ../Makerules" at the end of your Makefile. See modules/mail/Makefile for a simple example of a module Makefile, or modules/protocol/Makefile for a more complex example.

Once your module has been successfully compiled and installed, you can load it into Services with a LoadModule directive in ircservices.conf, just as with any of the standard modules, and you can add configuration directives for your new module in modules.conf by enclosing them inside Module and EndModule:

Module directory/module-name (configuration directives go here)EndModule

6-2. Callbacks provided by Services and standard modules

The callbacks provided by Services are listed below under the names used to access them (e.g., with add_callback()). When using Services core callbacks, use a module parameter of NULL.

Note that where the descriptions below refer to "processing" a message, they refer to a message that is meant specifically for the callback in question and which is not to be passed on to other modules or the Services core.

Except as otherwise specified, callbacks which return zero must leave all arguments unchanged, and callbacks which return nonzero may modify any arguments which are not specified as const.

6-2-1. Services core callbacks

channel create Parameters: Channel *channel, User *user, int32 mode

Called when a channel is created (i.e. a user joins a nonexistent channel). The user that created the channel and that user's modes (CUMODE_*) are also passed to the callback (note that the user is not yet in the channel's user list). The callback routine should always return 0.

channel delete Parameters: Channel *channel

Called when a channel is about to be deleted (i.e. the last user has left the channel). The callback routine should always return 0.

channel JOIN Parameters: Channel *channel, struct c_userlist *u

Called when a user has joined a channel. The callback routine should always return 0.

channel JOIN check Parameters: const char *channel, User *user

Called when a user is about to join a channel. The callback routine should return 1 to refuse the user access to the channel or 0 to allow the JOIN to proceed normally.

channel KICK Parameters: Channel *channel, User *user, const char *reason

Called when a user has been kicked from a channel. The callback routine should always return 0.

channel MODE
Parameters: const char *source, Channel *channel, int modechar, int add, char **av

Called for each valid mode character in a MODE message, except for channel user modes (+o, +v, etc.). add is nonzero if adding modes, zero if removing them. av" points to the first argument for the mode; there are guaranteed to be enough arguments for the mode character (provided the number of parameters in the mode definition is set correctly). The callback routine should return 1 if it processes the mode, 0 otherwise.

channel mode change Parameters: Channel *channel

Called when a channel's modes have changed. The callback routine should always return 0.

channel umode change Parameters: Channel *channel, struct c_userlist *user

Called when a user's modes on a channel have changed. The callback routine should always return 0.

channel PART Parameters: Channel *channel, User *user, const char *reason

Called when a user parts from a channel. The callback routine should always return 0.

channel TOPIC Parameters: Channel *channel, const char *topic, const char *setter time_t topic_time

Called when a TOPIC command is received. The callback routine should return 0 to permit the topic change or 1 to refuse it. Note that setter may be in the form "nick!user@host" instead of just a nickname, depending on the remote server type; however, Services currently stores only the nickname, and discards the username and hostname if present.

clear channel Parameters: const char *source, Channel *channel, int what, const void *param

Called whenever the clear_channel() function (in actions.c) is called, before any other action is taken. The callback routine should return 1 to terminate clear_channel() processing or 0 to continue. Note that even if the callback routine returns 1, clear_channel() will still flush out any channel mode changes, so the routine does not need to do this itself. See the comments above clear_channel() in actions.c for the meaning of the parameters.

command line Parameters: char *option, char *value

Called at program startup for each command-line option. option is the name of the option (the part of the option string after the initial "-", up to and not including any "="), and value" is the text after the "=" (NULL if no "=" is present). option is guaranteed to be non-NULL. The callback routine should return 0 if it does not recognize the option, 1 if it successfully processes the option, 2 if there is an error processing the option, or 3 if no error occurred but Services should terminate successfully.

connect Parameters: none

Called when a connection to the remote server is established. Modules that want to send data to the remote server on startup should use this callback; attempting to send data to the server before the connection is established will cause the data to be lost. The callback routine should always return 0.

expire Parameters: none

Called whenever the expire timeout (for expiring nicknames, etc.) runs out, or another action, such as OperServ UPDATE, explicitly causes expiration to occur. The callback routine should always return 0.

introduce_user Parameters: char *nick

Called whenever Services may need to introduce a pseudoclient (at startup and when receiving a KILL message). The nick parameter is the nickname of the pseudoclient which should be introduced (if it exists), or NULL when introducing all pseudoclients. The callback routine should return 1 if nick is not NULL and the routine introduces a pseudoclient, 0 otherwise. (If nick is NULL, the routine should introduce any pseudoclients necessary and return 0.)

load module Parameters: Module *module, const char *modname

Called when a module is loaded, after its init_module() routine has been called. modname is the name of the module, either specified by the module (char module_name[]) or copied from the module's path. The callback routine should always return 0. This callback may be used, for example, to add callback routines to a new module's callbacks when the module is loaded.

m_privmsg Parameters: char *source, char *target, char *message

Called for every PRIVMSG which is not ignored by Services. The callback routine should return 1 if it processes the message, 0 otherwise.

m_whois Parameters: char *source, char *target, char *target_server

Called for every WHOIS command. The callback routine should return 1 if it processes the message, 0 otherwise.

receive message
Parameters: char *source, char *cmd, int ac, char **av

Called for every message received from the uplink server. The callback routine should return 1 if it processes the message, 0 otherwise. Note that it is acceptable for a callback routine to modify the parameters passed and return 0 to allow the next routine to continue, subject to the following constraints:

The number of message parameters (ac) is not changed.
None of the strings (source, cmd, or any element of av) are lengthened. (Shortening strings is allowed.)

reconfigure Parameters: int after_configure

Called twice when Services is signalled to re-read its configuration files. The first call is made before any module configuration data is changed (but after the main Services configuration settings have been updated), with after_configure set to 0; the second call is made after all configuration data has been successfully read and configuration variables have been updated, with after_configure set to 1. Callback routines should always return 0.

save data Parameters: none

Called whenever the save-data timeout runs out, or another action, such as OperServ UPDATE, explicitly causes data saving to occur. The callback routine should always return 0.

save data complete Parameters: int successful

Called when a save-data operation completes. The successful parameter indicates whether the operation succeeded or not. The callback routine should always return 0.

server create Parameters: Server *server

Called whenever a new server joins the network, after the server record is created. The callback routine should always return 0.

server delete Parameters: Server *server, const char *reason

Called whenever a server splits from the network, before the server record is deleted. The callback routine should always return 0.

set topic Parameters: const char *source, Channel *c, const char *topic, const char *setter, time_t t

Called twice whenever set_topic() (in actions.c) is called to set the topic of a channel from Services. Parameters are as for set_topic() (in actions.c), except as noted below; source will always be non-NULL. The first call is done before the channel structure is modified, and all callback routines must return 0 in this case. The second call is done after the channel structure is modified, but before c->topic_time is changed; in this call, topic and setter are both NULL. If the callback routine returns 1, no further processing is done. This is currently used to ensure that the topic time is set so that the IRC servers will acknowledge the change under certain protocols.

unload module Parameters: Module *module

Called when a module is unloaded, after its exit_module() routine has been called. The callback routine should always return 0. Note that it is not necessary to use this callback to remove callbacks from a module which is being unloaded, since those callback entries will be removed automatically.

user check
Parameters: int ac, char **av

Called whenever a user joins the network, before the user record is created. ac and av are the argument list to the NICK (or USER) command, as passed to users.c/do_nick(). The callback routine should return 0 to allow the user to connect or 1 to disallow (in this case the routine should take action to remove the user from the network, such as sending a KILL message).

user create
Parameters: User *user, int ac, char **av

Called whenever a user joins the network, after the user record is created. ac and av are the argument list to the NICK (or USER) command, as passed to users.c/do_nick(). The callback routine should always return 0.

user delete Parameters: User *user, char *reason, int is_kill

Called whenever a user leaves the network (whether by QUIT or KILL), before the user record is deleted. is_kill is 1 if the user is quitting because of a KILL, 0 if because of a QUIT. The callback routine should always return 0.

user MODE
Parameters: User *user, int modechar, int add, char **av

Called for every mode character given in a user MODE message. add is nonzero when adding modes and zero when subtracting. av points to the first argument for the mode; there are guaranteed to be enough arguments for the mode character (provided the number of parameters in the mode definition is set correctly). The callback routine should return 1 if it processes the mode, 0 otherwise.

user nickchange (after) Parameters: User *user, const char *oldnick

Called whenever a user changes nicks, after the nickname is actually changed. The callback routine should return 1 if it kills the user, 0 otherwise.

user nickchange (before) Parameters: User *user, const char *newnick

Called whenever a user changes nicks, before the nickname is actually changed. The callback routine should always return 0. Note that users should never be killed within this callback; use the "user nickchange (after)" callback for that.

user servicestamp change Parameters: User *user

Called when a user's Services stamp (the servicestamp field) is altered and the network should be informed of it. The callback routine should always return 0.

6-2-2. OperServ callbacks

command Parameters: User *user, char *command: Called for every message (other than a CTCP PING or empty message) received by OperServ. command is the first word in the message (where words are separated by spaces); the remaining text can be obtained through repeated calls to strtok() with a NULL first parameter. The callback routine should return 1 if it processes the message, 0 otherwise. If the routine does not process the message, it must not call strtok().
expire maskdata Parameters: uint32 type, MaskData *md: Called when a MaskData entry is about to be expired, just before it is actually deleted. The callback routine should always return 0.
HELP Parameters: User *user, char *param: Called when the HELP command is used with a parameter. The callback should return 1 if it processes the message, 0 otherwise.
HELP COMMANDS Parameters: User *user, int which: Called when the HELP COMMANDS command is used. The which parameter is 0 when called after the list of unprivileged (IRC operator) commands, 1 after the Services operator commands, 2 after the Services administrator commands, and 3 after the Services root commands. The callback routine should always return 0.
SET Parameters: User *u, char *option, char *param: Called when the SET command is used. All parameters are guaranteed to be valid (non-NULL); param may contain multiple words. The callback routine should return 1 if it processes the given option, 0 otherwise.
STATS Parameters: User *user, char *extra: Called for every STATS command that is not plain "STATS", "STATS ALL", or "STATS RESET". "extra" contains the remainder of the message (after STATS and any following whitespace). The callback routine should return 1 if it processes the command, 0 otherwise.
STATS ALL Parameters: User *user, const char *s_OperServ: Called for every STATS ALL command. s_OperServ is the OperServ pseudoclient nickname; the callback routine should send messages using this nick. The callback routine should always return 0.
cancel_akill ("operserv/akill" module) Parameters: const char *username, const char *host: Called when an autokill is to be removed from the uplink server. The callback routine should return 1 if it removes the autokill, 0 otherwise.
send_akill ("operserv/akill" module) Parameters: const char *username, const char *host, time_t expires const char *who, const char *reason: Called when an autokill is to be sent to the uplink server. The callback routine should return 1 if it sends the autokill, 0 otherwise.

6-2-3. NickServ callbacks

authed (module nickserv/mail-auth) Parameters: User *u, NickInfo *ni, NickGroupInfo *ngi, int authreason

Called when a user successfully authenticates their nickname with the AUTH command, after all normal processing has been performed. authreason is the value that the ngi->authreason field had before being cleared (one of the NICKAUTH_* constants). The callback routine should always return 0.

cancel_user Parameters: User *u, int old_status, int old_authstat

Called whenever the cancel_user() routine is called for a user with a registered nick. old_status is the value of the user's nick's status field while the nick was in use (when the callback is called, all temporary flags will have been cleared); old_authstat is likewise the value before clearing of the nick group's authstat field. The callback routine should always return 0.

check_expire Parameters: NickInfo *ni, NickGroupInfo *ngi

Called when a nickname is being checked for expiration, after the nickname's last-used time has been updated (if appropriate). The callback routine should return 1 if the nick should be expired, 0 otherwise. If returning 1, the callback routine should log an appropriate message.

check recognized Parameters: const User *u

Called whenever Services needs to check whether a user is recognized as being the owner of the nick they are using (e.g., when the user connects to the network). The User structure is guaranteed to have valid ni and ngi pointers. The callback routine should return:

0, to indicate that the user was not recognized;
1, to indicate that the user was recognized as the owner of the nick; or
2, to indicate that the user should not be recognized as the owner of the nick, regardless of any subsequent checks.

collide Parameters: User *u

Called whenever NickServ determines that a user should be "collided". The callback should return 1 if it handles colliding the user (for example, by forcibly changing the user's nick), or 0 to allow normal collide processing to continue.

command Parameters: User *user, char *command

Called for every message (other than a CTCP PING or empty message) received by NickServ. See the OperServ "command" callback for details.

HELP Parameters: User *user, char *param

Called when the HELP command is used with a parameter. The callback should return 1 if it processes the messages, 0 otherwise.

HELP COMMANDS Parameters: User *user, int which

Called when the HELP COMMANDS command is used. The which parameter is 0 when called after the list of unprivileged commands and 1 after the list of privileged commands (those shown to IRC operators). The callback routine should always return 0.

identified Parameters: User *u, int old_authstat

Called when a user identifies for their nick. old_authstat is the authorization status of the nick before the identify took place. The callback routine should always return 0.

IDENTIFY check Parameters: User *u, char *pass

Called when a user attempts to identify for their nick, after the standard checks (whether the nick exists, etc.) are done but before the password itself is checked. The callback routine should return 1 to disallow identification or 0 to allow processing to continue normally.

nick delete Parameters: NickInfo *ni

Called when a nick's registration is deleted. The callback routine should always return 0.

nickgroup delete Parameters: NickGroupInfo *ngi, const char *oldnick

Called when a nick group is deleted (i.e. when the last nick for the group is deleted), after the nick delete callback is called. oldnick is the nickname whose deletion caused this nickgroup to be deleted. The callback routine should always return 0.

REGISTER/LINK check Parameters: User *u, const char *nick, char *password, char *email

Called when a user attempts to register their nickname, after the validity of the parameters has been checked but before checking whether the nickname exists or the password is strong enough. u is the user who sent the REGISTER command, and nick is their nickname (the same as u->nick). email may be NULL (if the user did not provide an E-mail address), but password will always be non-NULL. The callback routine should return 0 to allow the registration to continue or 1 to disallow it.

Also called by the nickserv/link module when a user attempts to link a new nickname to their own. In this case nick is the requested target nickname (different from u->nick), and password and email are both NULL. The callback is called after the nickname is checked for validity (length and invalid characters), but before checking whether the user has registered their current nickname. The callback routine should return 0 to allow the link to be made or 1 to disallow it.

registered Parameters: User *u, NickInfo *ni, NickGroupInfo *ngi, int *replied

Called when a user registers their nickname, after the data structures have been set up. The integer pointed to by replied can be set to 1 to disable the standard "your nick has been registered" reply. The callback need not call put_xxx() even if it modifies ni or ngi, as the caller will do so afterwards. The callback routine should always return 0.

SET Parameters: User *u, NickInfo *ni, NickGroupInfo *ngi, char *option, char *param

Called when the SET command is used. All parameters are guaranteed to be valid (non-NULL), and standard permission checks will have been performed (so u either is identified for ni/ngi or is a Services admin). The callback routine should return 1 if it processes the given option, 0 otherwise.

SET EMAIL Parameters: User *u, NickGroupInfo *ngi

Called when the E-mail address associated with a nick group is set, changed, or unset. u is the user making the change; this may not necessarily be the owner of the nick if, for example, a Services admin is making the change. The new address is stored in ngi->email. The callback routine should always return 0.

UNSET Parameters: User *u, NickInfo *ni, NickGroupInfo *ngi, char *option

Called when the UNSET command is used. All parameters are guaranteed to be valid (non-NULL), and standard permission checks will have been performed (so u either is identified for ni/ngi or is a Services admin). The callback routine should return 1 if it processes the given option, 0 otherwise.

6-2-4. ChanServ callbacks

check_chan_user_modes Parameters: const char *source, User *user, Channel *c, int32 modes

Called when checking a user's modes on a channel, before any standard checks are performed. The mode change is being performed by source (NULL for a channel join) on user on channel c, and the user's current modes on the channel are modes. The callback routine should return 0 to allow normal checking to continue or 1 to abort further checks.

Note: source may be the empty string; this indicates an internal call to verify a user's current modes. In this case callback routines should not make any decisions about modes based on the value of source.

check_kick
Parameters: User *user, const char *chan, ChannelInfo *ci, char **mask_ret, const char **reason_ret

Called when checking whether a user should be kicked from a channel, before any standard checks are performed. All parameters are guaranteed to be non-NULL, except for ci, which will be NULL when the channel is not registered. The callback routine may return:

0, to allow normal processing to continue.
1, to cause the user to be kicked from the channel. In this case, the callback routine must set *mask_ret to a newly malloc()/smalloc()'d memory area containing the mask to be banned (create_mask() or sstrdup() may also be used) and *reason_ret to a string for use as the reason in the kick.
2, to abort further processing and allow the user to enter the channel.

check_modes Parameters: Channel *channel, ChannelInfo *ci, int add, int32 flag

Called when checking a channel's modes against its mode lock for every mode locked either on (add nonzero) or off (add zero). The callback routine should return 1 if it processes the mode, 0 if not. If a mode is not processed by any callback and is further not specially handled by Services (+k and +l modes), the default action is to simply modify the channel's current modes to match the mode lock (by calling set_cmode(...,"+X") or set_cmode(...,"-X") for mode X), so it is not necessary to add a callback for modes for which this behavior is sufficient.

CLEAR Parameters: User *user, Channel *channel, char *what

Called when a valid CLEAR command is received (i.e. from a user with permission to use the command on the given channel). The callback routine should return 1 if it processes the command, 0 if not.

command Parameters: User *user, char *command

Called for every message (other than a CTCP PING or empty message) received by ChanServ. See the OperServ "command" callback for details.

HELP Parameters: User *user, char *param

Called when the HELP command is used with a parameter. The callback should return 1 if it processes the message, 0 otherwise.

HELP COMMANDS Parameters: User *user, int which

INVITE Parameters: User *u, Channel *c, ChannelInfo *ci

Called whenever a valid INVITE command is received (i.e. the user has permission to use INVITE for the channel). The callback should return 0 to allow normal processing to continue or 1 to abort further processing.

SET Parameters: User *u, ChannelInfo *ci, char *option, char *param

Called when the SET command is used. All parameters are guaranteed to be valid (non-NULL), and standard permission checks will have been performed (so `u' either is identified for ci or is a Services admin). The callback routine should return 1 if it processes the given option, 0 otherwise.

SET MLOCK
Parameters: User *u, ChannelInfo *ci, int modechar, int add, char **av

Called for each valid mode character in a SET MLOCK command. add is nonzero if adding modes, zero if removing them. av points to the first argument for the mode; there are guaranteed to be enough arguments for the mode character (provided the number of arguments in the mode definition is set correctly. The new mode lock (currently being constructed) is stored in the ci->mlock_XXX fields. The callback routine should return 1 if it encounters an invalid parameter for a mode, 0 otherwise.

Also called with modechar set to zero when all modes have been processed. In this case, add and av are undefined, and the callback routine should return 1 if there is a problem with the mode lock, 0 otherwise.

UNBAN Parameters: User *u, Channel *c, ChannelInfo *ci

Called whenever a valid UNBAN command is received (i.e. the user has permission to use UNBAN for the channel). The callback should return 0 to allow normal processing to continue or 1 to abort further processing.

UNSET Parameters: User *u, ChannelInfo *ci, char *option

Called when the UNSET command is used. All parameters are guaranteed to be valid (non-NULL), and standard permission checks will have been performed (so `u' either is identified for ci or is a Services admin). The callback routine should return 1 if it processes the given option, 0 otherwise.

6-2-5. MemoServ callbacks

command Parameters: User *user, char *command

Called for every message (other than a CTCP PING or empty message) received by MemoServ. See the OperServ "command" callback for details.

HELP Parameters: User *user, char *param

Called when the HELP command is used with a parameter. The callback should return 1 if it processes the message, 0 otherwise.

HELP COMMANDS Parameters: User *user, int which

receive memo Parameters: int ischan, void *who, const char *whoname, const User *sender, char *text

Called when a user or channel receives a memo. ischan is zero if the recipient is a user, nonzero if a channel, and who is the NickGroupInfo * or ChannelInfo * for the recipient, respectively; whoname is the name corresponding to who (the one given in the MemoServ SEND command). The callback should return nonzero to terminate processing or zero to cause the memo to be received normally.

Callback routines for this callback should use one of the following two priorities (defined in memoserv.h): MS_RECEIVE_PRI_CHECK for routines which check whether the memo is allowed to be sent, or MS_RECEIVE_PRI_DELIVER for actually sending the memo.

SET Parameters: User *u, MemoInfo *mi, char *option, char *param

Called when the SET command is used. All parameters are guaranteed to be valid (non-NULL), and standard permission checks will have been performed. mi points to the MemoInfo for the user's nickname. The callback routine should return 1 if it handles the given option, 0 otherwise.

6-2-6. StatServ callbacks

command Parameters: User *user, char *command: Called for every message (other than a CTCP PING or empty message) received by StatServ. See the OperServ "command" callback for details.
HELP Parameters: User *user, char *param: Called when the HELP command is used with a parameter. The callback should return 1 if it processes the message, 0 otherwise.
HELP COMMANDS Parameters: User *user, int which: Called when the HELP COMMANDS command is used. The which parameter is currently always 0. The callback routine should always return 0.

6-2-7. HTTP server callbacks

auth Parameters: Client *c, int *close_ptr: Called for each valid request received by the server. c is the client from which the request was received; the request data is stored in the client structure (see http.h), and at a minimum the method, url, version_major, and version_minor fields will be set appropriately. If the request is denied and the connection should be closed after the reply is sent, the callback routine should set *close_ptr to a nonzero value (*close_ptr should not be modified if the request is not denied). The callback routine should return HTTP_AUTH_ALLOW to explicitly allow the request to proceed, HTTP_AUTH_DENY to deny the request (in which case the module must send an appropriate error message), or HTTP_AUTH_UNDECIDED to pass the request through to the next callback; if all authorization callbacks pass the request through, it is treated as allowed.
request Parameters: Client *c, int *close_ptr: Called for each valid request received by the server and either explicitly allowed or passed through by all authorization callbacks. c is the client from which the request was received; the request data is stored in the client structure (see http.h), and at a minimum the method, url, version_major, and version_minor fields will be set appropriately. If the connection should be closed after the reply is sent, the callback routine should set *close_ptr to a nonzero value. The callback routine should return 1 if it processes the request, 0 otherwise.

6-3. Submitting additions or changes to Services

As a rule, suggestions for improvement are generally preferred to submissions of source code, for reasons discussed in FAQ Z.8. However, if you would like to submit a module you have written for inclusion in the standard Services distribution, or you have made a modification to Services itself (or a standard module) that you feel would be useful to others and would like it included in Services, please observe the following guidelines:

Your code must follow the coding guidelines given below (section 6-4).
Your code should be reasonably well error-checked and robust. For example, the return value of any function call which can return an error should be checked, and appropriate action taken if an error occurs.
Your code should compile with no errors or warnings using the default Services compilation options (gcc -O2 -fno-strict-aliasing -Wall -Wmissing-prototypes).
You should use comments well, but not overuse them; you do not need to comment every single line of code, but on the other hand someone looking at your module should not have to decipher several hundred lines of code just to figure out what it does.
All comments and any accompanying documentation should be in English and use proper grammar, spelling, etc. (Partial sentences are acceptable for inline comments.)

Any submissions which do not meet the above requirements will be categorically rejected, although some leeway may be provided in terms of comment and documentation quality if your native language is not English.

Furthermore, any submissions of modules, code, documentation, or any other information (collectively "information") become the sole property of the author of IRC Services, and by submitting such information, you agree to transfer any and all rights under copyright law you may have in said information to said author. If you do not agree to the above, or you are not permitted (by law, contract, or otherwise) to transfer all of your rights in the information to the author(s) of IRC Services, then you may not submit the information. (This requirement is made to avoid the hassles which would accompany the inclusion of source code or other items owned by multiple people or groups; see also the note on the copyright page. If you cannot comply with this paragraph but would still like to submit something, please contact the author to discuss your situation.)

6-4. Coding guidelines for Services

In general, observe the same style as is used in the rest of Services and you should have no problems. Specific points follow:

Formatting

Lines must not be longer than 79 columns.
The basic indentation unit is four columns.
Tab stops are set at multiples of eight columns (i.e., a tab character is equivalent to two levels of indentation). Tabs should be used in place of sequences of space characters, but this is not required.
Only one statement is allowed per line. Statements (including the empty statement ";") may not be written on the same line as a control keyword (if, for, or while).
Spaces are placed between binary operators and their operands, except for the member-reference operators "->" and "."; spaces are not placed between unary operators and their operands. However, spaces may be omitted around binary operators when it would improve readability. Examples:
i = j * 2;
user->channelcount++;
result += i*60 + (j+59)/60;
Always use NULL, not 0, in pointer comparisons. For character comparisons, 0 is preferred to '\0', but the latter may also be used if it does not go against the style of the surrounding code. Do not use '\0' with variables declared as type int8 or uint8, even though these types are usually equivalent to char and unsigned char.
The construct "!!expression" should not be used. Use "expression != 0" (for characters or integers) or "expression != NULL" (for pointers) instead.
Parentheses are required when && and || are used in the same expression to explicitly indicate order of evaluation; do not rely on the default order of evaluation. (Not using parentheses will generate a warning when using gcc -Wall.)
Parentheses following the control statements "if", "for", and "while", as well as the macros LIST_FOREACH, LIST_FOREACH_SAFE, and ARRAY_FOREACH, are preceded by a space. Parentheses following function or macro calls (other than the above) are not preceded by a space. Example:
if (flag) function();
Spaces are placed after the comma of each parameter to a function or macro; however, they may be omitted in function calls which are themselves parameters to a function or macro, or when including them would make the line exceed 79 columns in length. Spaces are also placed after (but not before) the semicolons in a for statement. Spaces are not placed after the opening parenthesis or before the closing parenthesis of a function/macro call or control statement. Examples:
function(param1, param2);
function(param1, strchr(string,'/'), param3);
for (i = 0; i < count; i++) . . .
Opening braces of control statement blocks go on the same line as the control statement (if, for, etc.) associated with the block; function blocks and "naked blocks" (those not associated with any control statement or function) have the opening brace alone on a line, indented to the same level as the surrounding code. Closing braces are indented to the same level as the line containing the opening brace. Examples:
if (flag) { /* indented code goes here */ . . .}

int function(int param1, char *param2) { /* indented code goes here */ . . . /* start of a naked block */ { int foo; . . . } }
If an if statement is longer than one line, it should be broken at logical operators (&& or ||); the operator should be placed at the beginning of the next line, and should be indented to show which term the operator belongs with. The closing parenthesis for the if statement and the subsequent open brace should be alone on a line, aligned with the first line of the if statement. (Braces are required in this case.) Conditions for for and while statements should never span multiple lines, though a for statement may be broken at the semicolons if necessary. Examples:
if (ok && (strcmp(option, "option-name-1") == 0            || strcmp(option, "option-name-2") == 0) ) {     . . .}

if (!init_first() || !init_second() || !init_third() || !init_fourth() ) {     /* This example outdents the || by three spaces      * to make the terms line up. */     . . .}

for (exception = first_maskdata(MD_EXCEPTION); exception != NULL;      exception = next_maskdata(MD_EXCEPTION) ) {     . . .}
An else followed by an if is considered to be a single keyword, "else if". The if part should always be placed on the same line as and immediately following the else; the else if should never be split up onto two lines, nor should braces be used around the if block. The exception to this is when the else and if refer to two conceptually distinct sets of conditions, in which case the if block should be enclosed by braces and indented. Example:
res = check_password( /* ... */ ); if (res == 0) { . . .} else if (res == 1) { /* "else if" on a single line */ . . .} else { if (user->ni != NULL) { /* "if" condition is different from "else" * condition, thus separate */ . . . } }
Braces are always placed around the body of a control statement (if, for, etc.). The one exception, aside from the case of else if mentioned above, is a statement for which the body, as well as the bodies of any else if or else statements for an if statement, are all one statement in length and do not contain any nested control statements; in this case braces are optional (but recommended if any of the statements span multiple lines). Examples:
for (i = 0; i < count; i++)     function(i);

while (!done) {     /* Braces required because of the nested "if" */     if (do_stuff())         done = 1; }

if (state == 0) {     a = b; } else if (state == 1) {     /* Every if/else body gets braces because this body      * has two statements */     b += a;     a = 0; } else {     state = 0; }
When using multiply-nested control statements, or a single control statement which has a long block, the closing brace of the block should be followed by a comment indicating what control statement the block belongs to. This should usually be the content of the control statement, but may be abbreviated as long as its meaning is clear. If a long if block is followed by an else clause, the else should likewise be documented. Examples:
while (i < count) {     . . .}  /* while (i < count) */

if (flag) {     . . .} else {  /* !flag */     . . .}  /* if (flag) */

for (node = first; node != NULL; node = node->next) {     . . .}  /* for all nodes */
Case labels for a switch should be indented half of a normal indentation unit (two columns) from the line containing the switch with which they are associated; statements associated with a case should be indented a full unit from the line containing the switch (half a unit from the case). If a case requires its own block, such as when it declares its own local variables, the opening brace is placed after the colon on the case line. Example:
switch (variable) { case 123: { int foo; . . . break; } /* case 123 */ default: . . . return -1; }
When a case in a switch block does not contain a break (or return) statement and deliberately "falls through" to the next case, a comment to this effect should be made at the bottom of the case. Example:
switch (state) { case 0: . . . /* fall through */ case 1: . . . break; }
Inline comments (comments placed to the right of a line of code) should be aligned to start on the same column, when this does not place too much space between the comment and the code or cause the line to exceed 79 columns in length. Inline comments after unusually long lines (such as long field declarations in structures) should be placed alone on the following line, indented the proper amount.
The goto statement should not be used except in error handling situations where it will help avoid multiple levels of if nesting or other awkward code. Labels for goto should be outdented half of an indentation unit from the surrounding code (i.e., indented two columns less than the surrounding code).

Identifier naming

Global variables and type names should use mixed upper- and lower-case, with an upper-case letter at the beginning of each distinct word in the name.
Preprocessor constants and macros should use all upper-case letters, with an underscore between distinct words in the name.
Structure names and local variables should use all lower-case letters, with an underscore between distinct words in the name.
Structure names for structures with an associated type name (i.e., from typedef) should be given the same name as the type, except with all letters in lowercase and followed by an underscore. Example:
typedef struct mytype_ MyType; struct mytype_ { MyType *next, *prev; . . .};
Names should be descriptive. For global variables, preprocessor macros and constants, type names, and structure names, names should generally consist of one or more full words. For local variables, short names and abbreviations are permitted as long as it is clear what the variables are used for. In general, one-letter local variable names should not be used other than the following:
- c: character
- f: file pointer (FILE *)
- i, j, k: integers (usually counters)
- n, p, q: integers (p may also be a pointer variable)
- s: string
- t: string or temporary variable
- x, y, z: integers (usually position variables)
Two-letter variable names are often formed from initials of type names, such as NickInfo *ni; see the source code for examples.

Table of Contents | Previous section: Importing and exporting databases | Top | Next section: Contacting the author