# HG changeset patch # User David Demelier # Date 1613582179 -3600 # Node ID efeb73a9918b9809eae26d08f30f20fa3b49b6c1 # Parent 027ef1952696b8de46485a8961e99ed0442ecc02 man: add C API for what is mostly stabilized diff -r 027ef1952696 -r efeb73a9918b man/CMakeLists.txt --- a/man/CMakeLists.txt Wed Feb 17 12:52:20 2021 +0100 +++ b/man/CMakeLists.txt Wed Feb 17 18:16:19 2021 +0100 @@ -35,6 +35,13 @@ set( MAN3 + ${man_SOURCE_DIR}/libirccd-compat.3 + ${man_SOURCE_DIR}/libirccd-event.3 + ${man_SOURCE_DIR}/libirccd-hook.3 + ${man_SOURCE_DIR}/libirccd-log.3 + ${man_SOURCE_DIR}/libirccd-rule.3 + ${man_SOURCE_DIR}/libirccd-util.3 + ${man_SOURCE_DIR}/libirccd.3 ) if (IRCCD_WITH_JS) diff -r 027ef1952696 -r efeb73a9918b man/libirccd-channel.3 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/libirccd-channel.3 Wed Feb 17 18:16:19 2021 +0100 @@ -0,0 +1,23 @@ +.\" +.\" Copyright (c) 2013-2021 David Demelier +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd @IRCCD_MAN_DATE@ +.Dt LIBIRCCD-CHANNEL 3 +.Os +.\" NAME +.Sh NAME +.Nm libirccd-channel +.Nd server joined channels + diff -r 027ef1952696 -r efeb73a9918b man/libirccd-compat.3 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/libirccd-compat.3 Wed Feb 17 18:16:19 2021 +0100 @@ -0,0 +1,132 @@ +.\" +.\" Copyright (c) 2013-2021 David Demelier +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd @IRCCD_MAN_DATE@ +.Dt LIBIRCCD-COMPAT 3 +.Os +.\" NAME +.Sh NAME +.Nm libirccd +.Nd compatibility layer +.\" SYNOPSIS +.Sh SYNOPSIS +.In irccd/compat.h +.\" DESCRIPTION +.Sh DESCRIPTION +While +.Xr irccd 1 +daemon focuses on POSIX systems, it also uses various BSD extensions that may +not be shipped on every platform. Therefore, it transparently incorporate glue +code with the same signature or headers files when these functions are missing. +This means that a user is able to call many BSD extensions without any user +requirement but including this header file. +.Pp +For example, +.Xr irccd 1 +uses the BSD +.Xr err 3 +set of functions and if functions are unavailable then a empty stub +.In err.h +file is provided in a private irccd directory and declarations are present in +the +.In irccd/compat.h file . +This means that the user may include the +.In err.h +file even though it is not present in the platform include directories. +.Pp +The following BSD functions are available: +.Bl -bullet -compact -offset indent +.Pp +.It +.Fn err +.It +.Fn errc +.It +.Fn errx +.It +.Fn getprogname +.It +.Fn pledge +.It +.Fn reallocarray +.It +.Fn recallocarray +.It +.Fn setprogname +.It +.Fn strlcat +.It +.Fn strlcpy +.It +.Fn strtonum +.It +.Fn verr +.It +.Fn verrc +.It +.Fn verrx +.It +.Fn vsyslog +.It +.Fn vwarn +.It +.Fn vwarnc +.It +.Fn vwarnx +.It +.Fn warn +.It +.Fn warnc +.It +.Fn warnx +.El +.Pp +The following POSIX functions are also available if the platform don't +implement them: +.Bl -bullet -compact -offset indent +.Pp +.It +.Fn basename +.It +.Fn dirname +.It +.Fn getopt +.It +.Fn strdup +.It +.Fn strndup +.It +.Fn strnlen +.It +.Fn strtok_r +.El +.Pp +And in addition to that, the following headers files are either provided as +compatibility shims or as empty stubs: +.Bl -bullet -compact -offset indent +.Pp +.It +.In sys/queue.h +.It +.In dirent.h +.It +.In err.h +.It +.In libgen.h +.It +.In unistd.h +.El +.Sh SEE ALSO +.Xr libirccd 3 diff -r 027ef1952696 -r efeb73a9918b man/libirccd-event.3 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/libirccd-event.3 Wed Feb 17 18:16:19 2021 +0100 @@ -0,0 +1,257 @@ +.\" +.\" Copyright (c) 2013-2021 David Demelier +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd @IRCCD_MAN_DATE@ +.Dt LIBIRCCD-EVENT 3 +.Os +.\" NAME +.Sh NAME +.Nm libirccd-event +.Nd IRC events +.\" SYNOPSIS +.Sh SYNOPSIS +.In irccd/event.h +.\" DESCRIPTION +.Sh DESCRIPTION +The event structure is defined as a generic IRC event that contains every +supported events into a anonymous union. +.Pp +It is passed through the plugin upon reception of a new IRC event. The user must +not modify the event. +.Pp +The +.Vt "struct irc_event" +is declared as: +.Bd -literal +struct irc_event { + enum irc_event_type type; + struct irc_server *server; + union { + struct irc_event_invite invite; + struct irc_event_join join; + struct irc_event_kick kick; + struct irc_event_message message; + struct irc_event_mode mode; + struct irc_event_names names; + struct irc_event_nick nick; + struct irc_event_notice notice; + struct irc_event_part part; + struct irc_event_topic topic; + struct irc_event_whois whois; + }; +}; +.Ed +.Pp +The fields of +.Vt "struct irc_event" +are: +.Bl -tag -width server +.It Va type +The IRC event generated. Depending on this value you may access one of the event +in the anonymous union. +.It Va server +The server object that generated the event. +.El +.Pp +The +.Vt "enum irc_event_type" +is declared as: +.Bd -literal +enum irc_event_type { + IRC_EVENT_UNKNOWN, /* Unknown or private use. */ + IRC_EVENT_COMMAND, /* Use irc_event_message. */ + IRC_EVENT_CONNECT, /* No specific data. */ + IRC_EVENT_DISCONNECT, /* No specific data. */ + IRC_EVENT_INVITE, /* Use irc_event_invite. */ + IRC_EVENT_JOIN, /* Use irc_event_join. */ + IRC_EVENT_KICK, /* Use irc_event_kick. */ + IRC_EVENT_ME, /* Use irc_event_message */ + IRC_EVENT_MESSAGE, /* Use irc_event_message. */ + IRC_EVENT_MODE, /* Use irc_event_mode. */ + IRC_EVENT_NAMES, /* Use irc_event_names. */ + IRC_EVENT_NICK, /* Use irc_event_nick. */ + IRC_EVENT_NOTICE, /* Use irc_event_notice. */ + IRC_EVENT_PART, /* Use irc_event_part. */ + IRC_EVENT_TOPIC, /* Use irc_event_topic. */ + IRC_EVENT_WHOIS /* Use irc_event_whois. */ +}; +.Ed +.Pp +The following enumerators are available: +.Bl -tag -width IRC_EVENT_DISCONNECT +.It Dv IRC_EVENT_UNKNOWN +An IRC event was received but not usable for plugins. Plugins usually never get +called when this is generated. +.It Dv IRC_EVENT_COMMAND +Specific plugin invocation. This is happening when a user invoke a plugin by +combining the server prefix and plugin identifier like +.Dq !plugin list . +The +.Va message +field may be used with this event. +.It Dv IRC_EVENT_CONNECT +Generated when a server was successfully connected. +.It Dv IRC_EVENT_DISCONNECT +When a server got disconnected. +.It Dv IRC_EVENT_INVITE +Received upon reception of an invite. The +.Va invite +field may be used. +.It Dv IRC_EVENT_JOIN +When someone (including the daemon) joined a channel. The +.Va join +field may be used. +.It Dv IRC_EVENT_KICK +When someone was kicked from a channel. The +.Va kick +field may be used. +.It Dv IRC_EVENT_ME +Event about CTCP ACTION (also known as /me) received. The +.Va message +field may be used. +.It Dv IRC_EVENT_MESSAGE +Message event from a channel or a nickname. The +.Va message +field may be used. +.It Dv IRC_EVENT_MODE +When a channel mode or the daemon own modes were changed. The +.Va mode +field may be used. +.It Dv IRC_EVENT_NAMES +Upon reception of a channel name listing. The +.Va names +field may be used. +.It Dv IRC_EVENT_NICK +When someone (including the daemon) changed its nickname. The +.Va nick +field may be used. +.It Dv IRC_EVENT_NOTICE +Notice message received either from a channel or a direct nickname. The +.Va notice +field may be used. +.It Dv IRC_EVENT_PART +When someone (including the daemon) leaves a channel. The +.Va part +field may be used. +.It Dv IRC_EVENT_TOPIC +If a channel topic was changed. The +.Va topic +field may be used. +.It Dv IRC_EVENT_WHOIS +When a whois information about a user was received. This event is usually never +generated from the server itself but mostly from client requests. The +.Va whois +field may be used. +.El +.Pp +Then, for each event that has arguments, the anonymous union contains one of the +following declared structures with their self explanatory commented fields: +.Bd -literal +struct irc_event_invite { + char *origin; + char *channel; +}; +.Ed +.Bd -literal +struct irc_event_join { + char *origin; + char *channel; +}; +.Ed +.Bd -literal +struct irc_event_kick { + char *origin; + char *channel; + char *target; + char *reason; +}; +.Ed +.Bd -literal +struct irc_event_message { + char *origin; + char *channel; + char *message; +}; +.Ed +.Bd -literal +struct irc_event_mode { + char *origin; + char *channel; + char *mode; + char **args; +}; +.Ed +.Bd -literal +struct irc_event_names { + char *channel; + char *names; /* Space separated list of nicknames. */ +}; +.Ed +.Bd -literal +struct irc_event_nick { + char *origin; + char *nickname; +}; +.Ed +.Bd -literal +struct irc_event_notice { + char *origin; + char *channel; + char *notice; +}; +.Ed +.Bd -literal +struct irc_event_part { + char *origin; + char *channel; + char *reason; +}; +.Ed +.Bd -literal +struct irc_event_topic { + char *origin; + char *channel; + char *topic; +}; +.Ed +.Bd -literal +struct irc_event_whois { + char *nickname; + char *username; + char *realname; + char *hostname; + struct { + char *name; /* Channel name joined from this user. */ + int modes; /* Bitmask of modes applied for the user. */ + } *channels; + size_t channelsz; /* The number of items in channels. */ +}; +.Ed +.Pp +The +.Va modes +field contains a bit mask of modes because +.Xr irccd 1 +separates the prefixes from channel and nicknames from +.Dq @+#staff +to +.Dq #staff +but to offer the possibility to know which modes are applied, they are marked as +bitmask of indices and stored in the server information. See the +.Xr libirccd-server 3 +manual page for more information about how to use it. +.\" SEE ALSO +.Sh SEE ALSO +.Xr libirccd 3 diff -r 027ef1952696 -r efeb73a9918b man/libirccd-hook.3 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/libirccd-hook.3 Wed Feb 17 18:16:19 2021 +0100 @@ -0,0 +1,85 @@ +.\" +.\" Copyright (c) 2013-2021 David Demelier +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd @IRCCD_MAN_DATE@ +.Dt LIBIRCCD-HOOK 3 +.Os +.\" NAME +.Sh NAME +.Nm libirccd-hook +.Nd manipulate hooks +.\" SYNOPSIS +.Sh SYNOPSIS +.In irccd/hook.h +.Ft struct irc_hook * +.Fn irc_hook_new "const char *name, const char *path" +.Ft void +.Fn irc_hook_invoke "struct irc_hook *hook, const struct irc_event *ev" +.Ft void +.Fn irc_hook_finish "struct irc_hook *" +.\" DESCRIPTION +.Sh DESCRIPTION +This header provides functions to create new hook or to invoke them. +.Pp +The +.Vt "struct irc_hook" +is declared as: +.Bd -literal +struct irc_hook { + char name[IRC_ID_LEN]; + char path[PATH_MAX]; + LIST_ENTRY(irc_hook) link; +}; +.Ed +.Pp +The fields of +.Vt "struct irc_hook" +are: +.Bl -tag -width name +.It Va name +Name to identify this hook. +.It Va path +Absolute path to the hook. +.It Va link +Abstract entry to be used with the +.Xr queue 3 +macros. +.El +.Pp +The +.Fn irc_hook_new +allocates a new hook with the identifer +.Fa name +on the given +.Fa path . +Those arguments will be copied into the returned structure fields of the same +name. +.Pp +The +.Fn irc_hook_invoke +will invoke the +.Fa hook +with the current IRC event pointed by +.Fa ev . +.Pp +The +.Fn irc_hook_finish +clears resources allocated for the +.Fa hook . +Make sure to remove it from the linked list where it is attached to before +calling this function. +.\" SEE ALSO +.Sh SEE ALSO +.Xr libirccd 3 diff -r 027ef1952696 -r efeb73a9918b man/libirccd-log.3 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/libirccd-log.3 Wed Feb 17 18:16:19 2021 +0100 @@ -0,0 +1,99 @@ +.\" +.\" Copyright (c) 2013-2021 David Demelier +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd @IRCCD_MAN_DATE@ +.Dt LIBIRCCD-LOG 3 +.Os +.\" NAME +.Sh NAME +.Nm libirccd-log +.Nd loggers +.\" SYNOPSIS +.Sh SYNOPSIS +.In irccd/log.h +.Ft void +.Fn irc_log_to_syslog "void" +.Ft void +.Fn irc_log_to_console "void" +.Ft void +.Fn irc_log_to_file "const char *path" +.Ft void +.Fn irc_log_to_null "void" +.Ft void +.Fn irc_log_set_verbose "int verbose" +.Ft void +.Fn irc_log_info "const char *fmt, ..." +.Ft void +.Fn irc_log_warn "const char *fmt, ..." +.Ft void +.Fn irc_log_debug "const char *fmt, ..." +.Ft void +.Fn irc_log_finish "void" +.\" DESCRIPTION +.Sh DESCRIPTION +This header provides functions to log messages into the configured +.Xr irccd 1 +loggers. +.Pp +Messages should always be prefixed by its component. For example, server +messages start with +.Dq server : +and plugins +.Dq plugin : . +.Pp +The +.Fn irc_log_to_syslog , +.Fn irc_log_to_console +and +.Fn irc_log_to_null +set the logger to the +.Xr syslog 3 +mechanism, standard output/error and completely quiet respectively. The +.Fn irc_log_to_file +uses the file specified by +.Pa path +to log everything. All those functions will close the current adapter before +changing it. +.Pp +The +.Fn irc_log_set_verbose +change the verbosity to on if +.Fa verbose +is greater than 0 (which is the default). +.Pp +The +.Fn irc_log_info +uses the +.Xr printf 3 +like format to log information messages. Thoses messages are ignored if the +verbosity is null. +.Pp +The +.Fn irc_log_warn +function logs a warning message, it is always written even if verbosity is null. +.Pp +The +.Fn irc_log_debug +only write messages if the daemon was built in +.Dq debug +mode, it also ignores the verbosity level. +.Pp +The +.Fn irc_log_finish +function closes the current adapter. It is usually not required from the user +itself. +.\" SEE ALSO +.Sh SEE ALSO +.Xr libirccd 3 diff -r 027ef1952696 -r efeb73a9918b man/libirccd-rule.3 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/libirccd-rule.3 Wed Feb 17 18:16:19 2021 +0100 @@ -0,0 +1,205 @@ +.\" +.\" Copyright (c) 2013-2021 David Demelier +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd @IRCCD_MAN_DATE@ +.Dt LIBIRCCD-RULE 3 +.Os +.\" NAME +.Sh NAME +.Nm libirccd-rule +.Nd create and match rules +.\" SYNOPSIS +.Sh SYNOPSIS +.In irccd/rule.h +.Ft struct irc_rule * +.Fn irc_rule_new "enum irc_rule_action action" +.Ft int +.Fn irc_rule_add "char *list, const char *value" +.Ft void +.Fn irc_rule_remove "char *list, const char *value" +.Ft int +.Fo irc_rule_match +.Fa "const struct irc_rule *rule" +.Fa "const char *server" +.Fa "const char *channel" +.Fa "const char *origin" +.Fa "const char *plugin" +.Fa "const char *event" +.Fc +.Ft int +.Fo irc_rule_matchlist +.Fa "const struct irc_rule_list *list" +.Fa "const char *server" +.Fa "const char *channel" +.Fa "const char *origin" +.Fa "const char *plugin" +.Fa "const char *event" +.Fc +.Ft void +.Fn irc_rule_finish "struct irc_rule *rule" +.\" DESCRIPTION +.Sh DESCRIPTION +The function in this header provides rule matching for filtering plugins +depending on IRC events. +.Pp +Rules are defined in the +.Vt "struct irc_rule" +declared as following: +.Bd -literal +struct irc_rule { + enum irc_rule_action action; + char servers[IRC_RULE_LEN]; + char channels[IRC_RULE_LEN]; + char origins[IRC_RULE_LEN]; + char plugins[IRC_RULE_LEN]; + char events[IRC_RULE_LEN]; + TAILQ_ENTRY(irc_rule) link; +}; +.Ed +.Pp +The fields of +.Vt "struct irc_rule" +are: +.Bl -tag -width channels +.It Va action +One of the +.Vt enum irc_rule_action +enumeration. +.It Va servers +A colon separated list of servers identifiers to match. +.It Va channels +A colon separated list of channels to match. +.It Va origins +A colon separated list of origins to match. +.It Va plugins +A colon separated list of plugins to match. +.It Va events +A colon separated list of events to match. +.It Va link +Abstract entry to be used with the +.Xr sys/queue 3 +macros. +.El +.Pp +The +.Vt "struct irc_rule_list" +is an abstract type declared with +.Fn TAILQ_HEAD +from +.Xr queue 3 +macros. +.Pp +The +.Vt "enum irc_rule_action" +is declared as: +.Bd -literal +enum irc_rule_action { + IRC_RULE_ACCEPT, + IRC_RULE_DROP +}; +.Ed +.Pp +The following enumerators are available: +.Bl -tag -width IRC_RULE_ACCEPT +.It Dv IRC_RULE_ACCEPT +Allows the current event. +.It Dv IRC_RULE_DROP +Drop the current event. +.El +.Pp +The +.Fn irc_rule_new +allocates a new rule with the given +.Fa action +and return it. +.Pp +The +.Fn irc_rule_add +function adds the new +.Fa value +to the char array +.Fa list +which should be one of the member field from the +.Vt struct irc_rule . +.Pp +The +.Fn irc_rule_remove +removes the existing +.Fa value +from the char array +.Fa list . +.Pp +The +.Fn irc_rule_match +function tests if the criteria given as arguments is allowed for this +.Fa rule . +All of +.Fa server , +.Fa channel , +.Fa origin , +.Fa plugin , +and +.Fa event +can be NULL, in that case the rule is considered as not matching only if the +rule does not contain a criterion for one of each. For example, if the rule must +match a server +.Dq example +and argument +.Fa server +is NULL, then the rule will not match. Otherwise, if the rule does not have a +server criterion then argument +.Fa server +is ignored entirely and this specific server criterion matches. +.Pp +The +.Fn irc_rule_matchlist +function is similar to +.Fn irc_rule_match +except that it analyze the whole linked +.Fa list +instead. +.Pp +The +.Fn irc_rule_finish +clears resources allocated for the +.Fa rule . +Make sure to remove it from the linked list where it is attached to before +calling this function. +.\" RETURN VALUES +.Sh RETURN VALUES +The function +.Fn irc_rule_add +returns 0 on success and -1 on errors. In that case +.Va errno +is set to indicate the error. +.Pp +The functions +.Fn irc_rule_match +and +.Fn irc_rule_matchlist +returns non-zero if the rule is allowed. +.\" ERRORS +.Sh ERRORS +The function +.Fn irc_rule_add +may set one of the following error: +.Bl -tag -width Er +.It Bq Er ENOMEM +When the limit of a rule criterion has been reached, which is +.Dv IRC_RULE_LEN . +.El +.\" SEE ALSO +.Sh SEE ALSO +.Xr libirccd 3 diff -r 027ef1952696 -r efeb73a9918b man/libirccd-util.3 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/libirccd-util.3 Wed Feb 17 18:16:19 2021 +0100 @@ -0,0 +1,187 @@ +.\" +.\" Copyright (c) 2013-2021 David Demelier +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd @IRCCD_MAN_DATE@ +.Dt LIBIRCCD-UTIL 3 +.Os +.\" NAME +.Sh NAME +.Nm libirccd-util +.Nd various utilities +.\" SYNOPSIS +.Sh SYNOPSIS +.In irccd/util.h +.Fd #define IRC_UTIL_SIZE(array) +.Ft void * +.Fn irc_util_malloc "size_t size" +.Ft void * +.Fn irc_util_calloc "size_t n, size_t width" +.Ft void * +.Fn irc_util_realloc "void *ptr, size_t size" +.Ft void * +.Fn irc_util_reallocarray "void *ptr, size_t n, size_t width" +.Ft char * +.Fn irc_util_strdup "const char *src" +.Ft char * +.Fn irc_util_strndup "const char *src, size_t len" +.Ft void * +.Fn irc_util_memdup "const void *ptr, size_t size" +.Ft char * +.Fn irc_util_basename "const char *path" +.Ft char * +.Fn irc_util_dirname "const char *path" +.Ft size_t +.Fn irc_util_split "char *str, const char **args, size_t max, char delimiter" +.Ft char * +.Fn irc_util_printf "char *str, size_t strsz, const char *fmt, ..." +.\" DESCRIPTION +.Sh DESCRIPTION +This header provides several function for memory management and basic string +handling. +.Pp +Every memory allocation function exits on error and are usually recommended for +small piece of data that should never fail and where the out of memory +consequence is unrecoverable. They are not recommended for reading large piece +of data where the standard C functions are preferred in this place. +.Pp +The +.Fn IRC_UTIL_SIZE +macro expands the compile time size of the argument +.Fa array +which must be constant array. +.Pp +The +.Fn irc_util_malloc , +.Fn irc_util_calloc , +.Fn irc_util_realloc , +are exactly the same as the standard C functions except they write an error +message if allocation fails. +.Pp +The +.Fn irc_util_reallocarray +function is similar to the OpenBSD +.Fn reallocarray +function which should reallocate the pointer +.Fa ptr +of +.Fa n +elements of given +.Fa width +size each. It always returns the new region otherwise writes an error message +and exits. +.Pp +The +.Fn irc_util_strdup , +.Fn irc_util_strndup +are similar to the POSIX functions but also write an error message if fails to +allocate the required size. +.Pp +The +.Fn irc_util_memdup +function allocate +.Fa size +bytes and copy the verbatim +.Fa ptr +into a new region returned. +.Pp +The +.Fn irc_util_basename +and +.Fn irc_util_dirname +are similar to the POSIX function of the same names but they don't modify the +original +.Fa path +argument and returns an independent string instead. The returned string is +static to each function and will be overwritten by subsequent calls. +.Pp +The +.Fn irc_util_split +function tokenize the +.Fa str +string input and store them into the array of string +.Fa args +according to the +.Fa delimiter . +The array +.Fa args +must be at least +.Fa max +long to store every tokens. The original +.Fa str +argument will be modified by this function to avoid dynamic allocation and as +such never fails. If the number of tokens parsed was greater than +.Fa max +then the last value is left +.Dq uncut +otherwise if the number of tokens is smaller than +.Fa max +then the +.Fa args +values will not be initialized. The user must make sure to initialize the array +itself or to check the return value of this function. +.Pp +Example, +.Fa max +argument is smaller than available tokens. +.Bd -literal +char str[] = "hello world what's up?"; +const char *args[3] = {0}; + +/* Will return 3. */ +irc_util_split(str, args, 3, ' '); +/* args[0] == "hello" */ +/* args[1] == "world" */ +/* args[2] == "what's up?" */ +.Ed +.Pp +Now, the same example while requesting more token than available. +.Bd -literal +char str[] = "hello world what's up?"; +const char *args[16] = {0}; + +/* Will return 4. */ +irc_util_split(str, args, 16, ' '); +/* args[0] == "hello" */ +/* args[1] == "world" */ +/* args[2] == "what's" */ +/* args[3] == "up?" */ +.Ed +.Pp +In the above case, arguments from 4 to 15 are set to NULL because we explicitly +did before calling +.Fn irc_util_split . +.Pp +The +.Fn irc_util_printf +is similar to standard C +.Xr snprintf 3 +signature except that it returns the +.Fa str +argument for convenience. +.\" RETURN VALUES +.Sh RETURN VALUELS +All memory functions +.Fn irc_util_malloc , +.Fn irc_util_calloc , +.Fn irc_util_realloc , +.Fn irc_util_reallocarray , +.Fn irc_util_strdup , +.Fn irc_util_strndup +and +.Fn irc_util_memdup +never return NULL. +.\" SEE ALSO +.Sh SEE ALSO +.Xr libirccd 3 diff -r 027ef1952696 -r efeb73a9918b man/libirccd.3 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/libirccd.3 Wed Feb 17 18:16:19 2021 +0100 @@ -0,0 +1,213 @@ +.\" +.\" Copyright (c) 2013-2021 David Demelier +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd @IRCCD_MAN_DATE@ +.Dt LIBIRCCD 3 +.Os +.\" NAME +.Sh NAME +.Nm libirccd +.Nd irccd C interface +.\" SYNOPSIS +.Sh SYNOPSIS +.Vt const char *_author; +.Vt const char *_description; +.Vt const char *_version; +.Vt const char *_license; +.Ft void +.Fn _set_option "const char *key, const char *value" +.Ft void +.Fn _set_template "const char *key, const char *value" +.Ft void +.Fn _set_path "const char *key, const char *value" +.Ft const char * +.Fn _get_option "const char *key" +.Ft const char * +.Fn _get_template "const char *key" +.Ft const char * +.Fn _get_path "const char *key" +.Ft const char ** +.Fn _get_options "void" +.Ft const char ** +.Fn _get_templates "void" +.Ft const char ** +.Fn _get_paths "void" +.Ft void +.Fn _load "void" +.Ft void +.Fn _reload "void" +.Ft void +.Fn _unload "void" +.Ft void +.Fn _event "const struct irc_event *ev" +.\" DESCRIPTION +.Sh DESCRIPTION +The +.Nm +library is a set of functions available from the +.Xr irccd 1 +daemon when writing native C plugins. It isn't shipped as a library because it +opens plugins dynamically and exports its own set of symbols through it. Plugins +don't need any kind of link when built. +.Pp +The API offers various utilities to control the daemon by inspecting servers, +rules, plugins or hooks. It also offers various miscellaneous utilities along +with some compatibility shims. +.Pp +This documentation only shows a quick overview of what is available, +documentation of very modules is done through the set of +.Xr libirccd-MODULE-NAME 3 +manual pages. +.Pp +For +.Dq namespace +issue, every symbol or macros are prefixed by irc_ or IRC_. +.Pp +An example of plugin can be found at +.Pa @CMAKE_INSTALL_FULL_DATADIR@/irccd/sample-plugin.c +.\" PLUGIN INTERFACE +.Sh PLUGIN INTERFACE +To be opened by +.Xr irccd 1 +the plugin has to match a specific ABI. Several variables and functions should +be exported using a specific prefix and variable names. +.Pp +The +.Em +as shown in the +.Xr SYNOPSIS +section is computed using the plugin base file name and translating every non C +character to an +.Dq _ . +For example, if the plugin is named +.Pa irc-notify.so +then the prefix will be +.Em irc_notify +and subsequent function to implement should be named +.Fn irc_notify_event , +.Fn irc_notify_get_option +and so on. +.Pp +Every variable and function are completely optional. +.Pp +.\" Variables +.Ss Variables +The +.Va _author , +.Va _description , +.Va _version , +and +.Va _license +variables can be declared as plugin metadata to inform about the plugin author, +a short description, its version and the license respectively. +.\" Functions +.Ss Functions +The following functions can be implemented in the plugin and called from +.Xr irccd 1 +upon certain circumstances. +.Pp +The +.Fn _set_option , +.Fn _set_template +and +.Fn _set_path +are called when the user wants to change the property +.Fa key +to the new +.Fa value . +If the key isn't supported by the plugin, no action should be taken. They alter +the plugin options, user templates and predefined paths respectively. +.Pp +The +.Fn _get_option , +.Fn _get_template +and +.Fn _get_path +are the exact opposite of their +.Em set_* +counterparts, they should return the value associated with the +.Fa key +argument. If the plugin does not support the given +.Fa key +it should return NULL to indicate it. +.Pp +The +.Fn _get_options , +.Fn _get_templates +and +.Fn _get_paths +should return a NULL terminated array of strings that the plugin supports for +options, templates and paths respectively. The returned array isn't free'd so +the user may return a static array for convenience. +.Pp +The +.Fn _load +function is called when the plugin is being loaded and add to the daemon. +.Pp +The +.Fn _reload +is called when the user requests to reload the plugin. +.Pp +The +.Fn _unload +is called when the plugin is about to be removed. +.Pp +The +.Fn _event +is called upon reception of a new IRC server message. See the +.Xr libirccd-event 3 +module about how to use the argument +.Fa ev . +.\" MODULES +.Sh MODULES +The following APIs are available +.Bl -tag +.It Xr libirccd-server 3 +Manipulate servers. This module is probably the one you will use the most while +writing plugins. It lets you send messages through an IRC server. +.It Xr libirccd-channel 3 +Channel information. +.It Xr libirccd-compat 3 +Compatibility layer offered for various BSD and POSIX extensions if not +available on your system. +.It Xr libirccd-event 3 +Information about an IRC event received. +.It Xr libirccd-hook 3 +Create new hooks. +.It Xr libirccd-irccd 3 +General functions to manipulate the running daemon. +.It Xr libirccd-log 3 +Functions for logging messages through the configured logger adapter. +.It Xr libirccd-plugin 3 +Create new plugins. +.It Xr libirccd-rule 3 +Create or match rules. +.It Xr libirccd-subst 3 +The substitution mechanism to create user plugin templates. +.It Xr libirccd-util 3 +Various utilities. +.El +.\" SEE ALSO +.Sh SEE ALSO +.Xr libirccd-channel 3 , +.Xr libirccd-compat 3 , +.Xr libirccd-event 3 , +.Xr libirccd-hook 3 , +.Xr libirccd-irccd 3 , +.Xr libirccd-log 3 , +.Xr libirccd-plugin 3 , +.Xr libirccd-rule 3 , +.Xr libirccd-server 3 , +.Xr libirccd-util 3