[IRC-Dev CVS] [CVS] Module ircd-ircdev: Change committed

[Toni G. <zo...@us...>]

CVSROOT    : /cvsroot/irc-dev
Module     : ircd-ircdev
Commit time: 2005-01-05 16:39:44 UTC

Added files:
     doc/en/api/api.txt doc/en/api/log.txt

Log message:

Documentacion API en inglés

---------------------- diff included ----------------------
Index: ircd-ircdev/doc/en/api/api.txt
diff -u /dev/null ircd-ircdev/doc/en/api/api.txt:1.1
--- /dev/null	Wed Jan  5 08:39:44 2005
+++ ircd-ircdev/doc/en/api/api.txt	Wed Jan  5 08:39:34 2005
@@ -0,0 +1,107 @@
+$Id: api.txt,v 1.1 2005/01/05 16:39:34 zolty Exp $
+
+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 <kl...@mi...>
+</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>
Index: ircd-ircdev/doc/en/api/log.txt
diff -u /dev/null ircd-ircdev/doc/en/api/log.txt:1.1
--- /dev/null	Wed Jan  5 08:39:44 2005
+++ ircd-ircdev/doc/en/api/log.txt	Wed Jan  5 08:39:34 2005
@@ -0,0 +1,242 @@
+$Id: log.txt,v 1.1 2005/01/05 16:39:34 zolty Exp $
+
+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 <kl...@mi...>
+</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>
----------------------- End of diff -----------------------