shithub: ircs

ref: a90d1130f47c07132f1816366b05f18929911e60
dir: /ircs.man/

View raw version
.TH IRCS 1
.SH NAME
ircs, ircx \- internet relay chat client and ui
.SH SYNOPSIS
ircs [ -deprTU ] [ -s srvname ] [ -f file ] nick[!user] addr

ircx [ -eprTU ] [ -s srvname ] [ -f file ] [ -t target ] [ -b
lines ] [ nick[!user] addr ]

irctime [ file ... ]

.SH DESCRIPTION
Ircs is a persistent, logging IRC client inspired by the classic
Plan 9 IRC client irc7.  Its usage is similar to irc7's "ircsrv":
it makes a connection to an IRC server, posts its command pipe in
srv(3), and logs incoming and outgoing messages to a log
directory, or to a given file.

Ircs dials the IRC server at addr and uses nick as the IRC
nickname.  The addr is a network address understood by dial(2).
The default port number is 6667 unless the -e option (enable TLS
encryption) is given, in which case the default port is 6697.
The username user can be specified by separating the nick and the
user with an exclamation mark ('!').  If no user is given the
nick is used also as the username.

The user's (raw) IRC commands are read via a command pipe which
by default is posted to service file /srv/ircs.  The log is
written by default to files under /tmp/ircs directory; server and
private messages are written to the main log file /tmp/ircs/log,
and messages related to channels are written to files named
/tmp/ircs/#channel, where "#channel" is the name of the channel.

The -s option changes the service file to /srv/srvname and the
log directory to /tmp/srvname.  The -f option causes all logs to
be written to a given file instead of a directory.

All messages are logged apart from PING/PONG; when a PING is
received the modification time of the (main) log file is set to
the current time.

When logging to a directory, ircs attempts to keep track of all
users (i.e.  nicks) on joined channels in order to log incoming
NICK/QUIT messages to related channel log files.  When ircs
cannot determine the channel(s) a particular user is on, or if
the option -U (disable user tracking) is given, incoming
NICK/QUIT messages are logged to the main log file.

The -d option causes some debug info to be printed to standard
error.

The -p option causes a password to be sent to the server.  The
password is read via the authentication agent factotum(4) which
must be mounted in the same namespace.  The -p option can only be
used with the -e (use TLS) option.

By default the logs are formatted so that they can easily be
processed with Plan 9 tools, like cat(1) or grep(1).  The log
lines are preceded with timestamps in a human-readable format.
The -r option disables this formatting and enables raw logging
with timestamps in the Unix time format.  The -T option disables
timestamps altogether.

Normally a user need not deal with ircs directly, but can use the
ircx wrapper script, whose usage is nearly identical to ircs.

Ircx is a simple rc(1) user interface to ircs, similar to irc7's
client program "irc".  It makes use of the service provided by an
ircs instance, and provides an interface for starting and
stopping ircs and for sending and displaying messages.  Unlike in
irc7, where the most functionality is in the client part, in ircs
the main functionality is intended to be in the service part.

With nick and addr arguments ircx attempts to start an ircs
instance; if the ircs starts successfully, ircx then runs the
user interface: the related log file is printed to standard
output as it accumulates, and user's commands are read from
standard input.

Without nick and addr arguments ircx assumes that the ircs
instance is already running, and only the user interface is run.
Ircx can be exited by pressing <del>; the /h command prints the
list of known commands.

The -t option sets the target (channel or nick) to which the
input commands apply.  If the target is a channel (the first
character is '#'), the channel is joined.  The -b option sets the
number of lines that are printed from the end of the log file
when ircx starts.

An ircs instance is defined by its service name (and log file if
-f option is used).  Like ircs, ircx uses by default the service
file /srv/ircs and log directory /tmp/ircs; the service name
"ircs" can be changed by the -s option.  When running multiple
ircs instances, like when connecting to multiple IRC networks,
the -s and (optionally) -f options should be used to
differentiate between the instances.

Irctime copies the given files (standard input by default) to its
standard output, converting the default human-readable ircs
timestamps to ISO 8601 format.

.SH EXAMPLES
Connect to freenode using nick and username "foo":
.IP
.EX
ircx foo chat.freenode.net
.EE
.PP
Join the channel "#cat-v" assuming ircs is already running:
.IP
.EX
ircx -t '#cat-v'
.EE
.PP
Follow server and private messages assuming ircs is already
running:
.IP
.EX
ircx
.EE
.PP
Check what ircs instances are running:
.IP
.EX
ps -a | grep ircs
.EE

.SH SOURCE

http://www.plan9.fi/src/ircs.tgz

.SH SEE ALSO

https://tools.ietf.org/html/rfc2812

.SH BUGS

The -t (set target) option does not affect the output of ircx
when the -f (set log file) option is used; ircx prints out all
messages from the log file regardless of the target.