Mercurial > irccd
view man/libirccd-rule.3 @ 1091:52be05336310
irccdctl: misc cleanups
author | David Demelier <markand@malikania.fr> |
---|---|
date | Wed, 21 Jul 2021 16:06:36 +0200 |
parents | f18988efb96b |
children | f06e9761cc90 |
line wrap: on
line source
.\" .\" Copyright (c) 2013-2021 David Demelier <markand@malikania.fr> .\" .\" 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]; struct irc_rule *next; struct irc_rule *prev; }; .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 next Pointer to the next rule. .It Va perv Pointer to the previous rule. .El .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. .\" EXAMPLES .Sh EXAMPLES Create a rule that matches servers .Dq example or .Dq wanadoo on channel .Dq #staff for the plugin .Dq hangman and drop it. .Bd -literal -offset indent struct irc_rule *r; r = irc_rule_new(IRC_RULE_DROP); irc_rule_add(r->servers, "example"); irc_rule_add(r->servers, "wanadoo"); irc_rule_add(r->channels, "#staff"); irc_rule_add(r->plugins, "hangman"); .Ed .\" 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