1 Some users can be very annoying, as any IRC operator can attest. Some
2 can in fact be downright abusive. Sometimes the best way of dealing
3 with these users is to ban them from the entire network. The G-line
6 G-lines are fairly complicated. A G-line can be active or inactive,
7 either locally or globally. It can be a purely local G-line, or
8 global. It could be based on IP address or on host name. In short,
9 there are many variations on the basic G-line. Worse, there is also
10 the concept of a "bad channel," or BADCHAN, that has been tacked onto
11 the G-line subsystem, when it should have been a separate command in
14 Different types of G-lines are differentiated from each other through
15 the use of various flags. Some of these flags are maintained solely
16 by the G-line subsystem, where as others are passed to various
20 #define GLINE_MAX_EXPIRE 604800 /* max expire: 7 days */
22 This macro lists the maximum expire time a G-line is permitted to
23 have. This value is limited to 7 days to prevent abuse of the system.
27 #define GLINE_ACTIVE 0x0001
29 This flag is used to indicate that a given G-line is globally active.
33 #define GLINE_IPMASK 0x0002
35 This flag is used to indicate that a given G-line is an IP mask. This
36 flag is maintained internally by the G-line subsystem.
40 #define GLINE_BADCHAN 0x0004
42 This flag is used to indicate that a given G-line specifies a BADCHAN,
43 a channel that users are not permitted to join. This flag is
44 maintained internally, but is also used in gline_find() to search for
45 a BADCHAN for a particular channel.
49 #define GLINE_LOCAL 0x0008
51 This flag is used to indicate that a given G-line is a local G-line.
52 Local G-lines do not affect users on other servers.
56 #define GLINE_ANY 0x0010
58 This flag is passed to gline_find() to signal that function to return
59 any G-line or BADCHAN that matches the passed mask string. It is
60 never set on a real G-line.
64 #define GLINE_FORCE 0x0020
66 This flag is passed to gline_add() to force the server to accept an
67 expire time that might be out of bounds. It is never set on a real
72 #define GLINE_EXACT 0x0040
74 This flag is passed to gline_find() to signal that function to return
75 only G-lines that exactly match the passed mask string. That is, the
76 ircd_strcmp() function is called to compare the G-line to the mask,
77 rather than the match() function. This flag is never set on a real
82 #define GLINE_LDEACT 0x0080 /* locally deactivated */
84 This flag is set on global G-lines that have been locally
85 deactivated. This flag is maintained internally by the G-line
90 #define GLINE_GLOBAL 0x0100 /* find only global glines */
92 This flag is passed to gline_find() or gline_lookup() to specify that
93 the caller is only interested in global G-lines. This flag is never
98 #define GLINE_LASTMOD 0x0200 /* find only glines with non-zero lastmod */
100 This flag is passed to gline_find() or gline_lookup() to specify that
101 the caller is only interested in G-lines with a non-zero lastmod time,
102 that is, G-lines that were not set by a U-lined service. This flag is
103 never set on a real G-line.
109 The struct Gline describes everything about a given G-line. None of
110 its fields may be directly accessed by the application; use the
111 functions and macros described below instead.
115 int GlineIsActive(struct Gline* g);
117 This macro returns a non-zero value if the G-line is active, or 0
118 otherwise. If a G-line is locally deactivated, this macro will always
123 int GlineIsRemActive(struct Gline* g);
125 This macro returns a non-zero value if the G-line is active, ignoring
126 whether or not it is locally deactivated.
130 int GlineIsIpMask(struct Gline* g);
132 This macro returns a non-zero value if the G-line is an IP mask.
136 int GlineIsBadChan(struct Gline* g);
138 This macro returns a non-zero value if a G-line actually represents a
143 int GlineIsLocal(struct Gline* g);
145 This macro returns a non-zero value if a G-line is local only.
149 char* GlineUser(struct Gline* g);
151 This macro returns the user name associated with the G-line. If the
152 G-line represents a BADCHAN, this will contain the channel name.
156 char* GlineHost(struct Gline* g);
158 This macro returns the host name associated with the G-line. If the
159 G-line represents a BADCHAN, this will be a NULL pointer.
163 char* GlineReason(struct Gline* g);
165 This macro returns the reason that was given when the G-line was set.
169 time_t GlineLastMod(struct Gline* g);
171 G-lines that were not set by a U-lined service have a modification
172 time that must be monotonically increasing. This macro simply returns
173 that modification time.
177 int gline_propagate(struct Client *cptr, struct Client *sptr,
178 struct Gline *gline);
180 When a global G-line is set or modified, all other servers must be
181 notified of the new G-line. This function takes care of propagating
182 the G-line specified by _gline_, originated by the client _sptr_, to
183 all servers except _cptr_ (which may be a NULL pointer).
187 int gline_add(struct Client *cptr, struct Client *sptr, char *userhost,
188 char *reason, time_t expire, time_t lastmod, unsigned int flags);
190 This function simply adds a G-line, set by _sptr_ and with a
191 _userhost_, _reason_, _expire_, and _lastmod_ as specified. The
192 _flags_ parameter is a bit mask consisting of the binary OR of
193 GLINE_FORCE, GLINE_LOCAL, or GLINE_ACTIVE, as appropriate. The
194 gline_add() function also calls gline_propagate() to propagate the
195 G-line, and kills off any local users matching the G-line if it is
200 int gline_activate(struct Client *cptr, struct Client *sptr,
201 struct Gline *gline, time_t lastmod, unsigned int flags);
203 This function activates the G-line specified by _gline_, setting its
204 _lastmod_ time as specified. If _flags_ is GLINE_LOCAL and if the
205 G-line is locally deactivated, this function will turn off the local
206 deactivation flag, but will not modify _lastmod_. If the G-line is
207 globally deactivated, passing this function the GLINE_LOCAL flag will
212 int gline_deactivate(struct Client *cptr, struct Client *sptr,
213 struct Gline *gline, time_t lastmod, unsigned int flags);
215 This function is similar to gline_activate() except that it
216 deactivates the G-line. If the given G-line is local, or if it was
217 set by a U-lined service (and GLINE_LOCAL was not passed via _flags_),
218 then the G-line is deleted from memory. In all other cases, the
219 G-line is simply deactivated, either locally (if GLINE_LOCAL was
220 passed via _flags_) or globally. Global deactivation will update the
225 struct Gline *gline_find(char *userhost, unsigned int flags);
227 This function looks up a G-line matching the given _userhost_ value,
228 under control of the _flags_ parameter. Valid _flags_ that may be
229 passed are: GLINE_BADCHAN, GLINE_ANY, GLINE_GLOBAL, GLINE_LASTMOD, or
230 GLINE_EXACT, each described above.
234 struct Gline *gline_lookup(struct Client *cptr, unsigned int flags);
236 This function looks up a G-line matching the given client, specified
237 by _cptr_, under the control of the _flags_. Valid values for _flags_
238 are GLINE_GLOBAL and GLINE_LASTMOD, as described above.
242 void gline_free(struct Gline *gline);
244 This function releases all storage associated with a given G-line.
248 void gline_burst(struct Client *cptr);
250 This function generates a burst of all existing global G-lines and
251 BADCHANs and sends them to the server specified by _cptr_.
255 int gline_resend(struct Client *cptr, struct Gline *gline);
257 This function resends the _gline_ to a server specified by _cptr_.
258 This may be used if, for instance, it is discovered that a server is
259 not synchronized with respect to a particular G-line.
263 int gline_list(struct Client *sptr, char *userhost);
265 This function sends the information about a G-line matching _userhost_
266 to the client specified by _sptr_. If _userhost_ is a NULL pointer, a
267 list of all G-lines is sent.
271 void gline_stats(struct Client *sptr);
273 This function generates a list of all G-lines, sending them to the
274 user _sptr_ by a /STATS G response.
278 Kev <klmitch@mit.edu>
282 [2001-6-15 Kev] Initial documentation for the G-line API.