userhost [-direct] [-count <number>] [-extra <stuff>] [<nickname> [<nickname> …] [-cmd <command>]]

This asks the server for the address (user@hostname) of each of the specified nicknames. You may query as many nicknames as you wish, however the irc protocol limits any one request to 5 nicknames; the client will break your list into groups of 5 and request each group separately. If you query too many nicknames, you may flood yourself off the server.

If you specify the -cmd option, then anything that follows that option will be taken as a block that shall be executed for each and every nickname in the list IN THE SAME ORDER AS THE LIST. If any of the nicknames in the list are not on irc, a placeholder userhost will be passed to the -cmd block in that nickname's turn. (further described below)

The traditional behavior of USERHOST was to execute the -cmd option asynchronously. Asynchronous execution means that execution of code is postponed until the future, when the server replies to the query. When USERHOST behaves asynchronously, the USERHOST command simply submits a request for userhosts to the server and returns immediately. The -cmd option will not have been executed – not even once – and will not be executed until the next time EPIC checks for data from the server.

However, if all of the nicknames in the list are present in the client's internal userhost cache, then this command behaves synchronously. The -cmd option will be executed for all nicknames in the list before the USERHOST command returns. If you do not want this behavior, you can use the -direct option to force USERHOST to send the request to the server instead of looking in the cache.

However, EPIC cannot cache the “away status” or “oper status” that is provided by a userhost request and whenever it behaves synchronously, the away status and oper status will be wrong. If you need the away status or oper status, you should use the -direct option to get this information from the server.

The use of the wait command arranges for synchronous behavior after the execution of an asynchronous command.

Sometimes you want to pass extra data to the -cmd callback, and because of the asynchronous behavior of userhost, it's difficult to arrange this without waiting. The userhost command supports an -extra flag that takes a variable name and saves the contents of that variable at the time you do the request, and then appends that value when the userhost callbacks are executed. The variable is only used at the time you make the userhost request, so you can change it (or use a local variable) and that won't affect the value passed to the callbacks.

The extra data is appended to $* in the /on 303 numeric as well.

USERHOST passes the following arguments to -cmd:

$0  - nickname
$1  - a '+' if the user is an irc operator, a '-' otherwise
$2  - a '+' if the user is marked as away, a '-' otherwise
$3  - username
$4  - hostname
$5- - The extra data, if any.

To get the userhosts of JoeBob and Jimbo:

    /userhost joebob jimbo

To use their userhost output as another command's input in a script:

    userhost joebob jimbo -cmd {
       echo $0 is $3@$4
       if ( [$1] == [+] ) echo $0 is an irc operator
       if ( [$2] == [+] ) echo $1 is away
    }

To pass extra data to a userhost callback:

    @ var = [This is" a compli\cat\\ed string"]
    userhost -extra var joebob jimbo -cmd {
       xecho -b $0 is $3@$4 ($5-)
    }