# $EPIC: floodinfo.txt,v 1.2 2007/03/03 18:29:38 jnelson Exp $
======Synopsis======
$[[floodinfo]](*)
$[[floodinfo]]("user@host channel level server min-hits min-duration min-rate" ...)

======Description:=======
This function returns information about the flooders who are currently 
being tracked by the [[flood control]] system.

The [[floodinfo]] system takes a list of dword patterns, where each dword 
pattern is expected to match a string of 7 words, which are:

^ Word Number ^ Description ^
| 0 | The user@host of the flooder; if [[set flood_maskuser]] is 1 or 2, then this word is something you can ban or kline. |
| 1 | The channel the flood is occurring on. |
| 2 | The level of the messages being flooded. |
| 3 | The server the flood is occurring through |
| 4 | The minimum number of messages in the flood |
| 5 | The minimum duration (in seconds) of the flood |
| 6 | The minimum messages-per-second rate of the flood |

Wildcards are permitted.  The function will return all flood entries that
match the wildcard pattern.

This function returns dwords containing 7 words, as described above.
This intentionally allows you to feed the return value of $floodinfo()
back in as the argument to $floodinfo() later.

======Original description:======
$floodinfo() will now accept as input the same list of lists it
outputs.  The lists themselves don't have to be complete.  Any
unspecified arguments will match all records.  For example: 

$floodinfo("% #chan joins")  # Return all join records for #chan.
$floodinfo(*)                # This still works.
$floodinfo($floodinfo(*))    # Same output as above.

Feeding $floodinfo() output back into its input is useful for tuning
the flood /sets by seeing which non-flooders are being caught long term
in the system.

The fields are these:

|0 |u@h mask that matches the flooder.  Defaults to "*".|
|1 |channel mask.  Defaults to "*".  |
|2 |flood type mask.  Defaults to "*". |
|3 |Server number.  Defaults to -1, which matches all. |
|4 |Numeric minimum number of flood hits. |
|5 |Numeric minimum duration of flood. |
|6 |Numeric minimum flood rate. |

The last three numeric arguments may be negative, in which case, they
specify the _maximum_ values.  These fields make it possible to deal
with different kinds of floods in different ways _after_ they occur.
For example, a join flood may be falsely triggered by a net join, but
it is reasonable to expect that if you have join and part flood records
for the same u@h, then it is participating in a join/part flood.

/on "% parts % 5" {
	if (floodinfo("$userhost() $2 joins $servernum() 5")) {
		mode $2 +b *!*@$after(@ $userhost()) 
	}
}

Or alternately:

/on "% joins % 5" {
	if (floodinfo("$userhost() $2 parts $servernum() 5")) {
		mode $2 +b *!*@$after(@ $userhost())
	}
}

======Returns:======
A sequence of 7 word qwords describing the floods being monitored.

======History:======
This function first appeared in EPIC4-1.1.8.